API de Maps Tools Resolution (experimental)

La API de resolución de herramientas de Maps proporciona extremos de procesamiento por lotes para resolver nombres de ubicaciones y URLs en IDs de lugares de Google Maps.

Acceso y autenticación de la API

Métodos de autenticación

Las APIs admiten credenciales de clave de API y OAuth 2.0:

1. Clave de API

Puedes autenticar las solicitudes agregando una clave de API de Google Maps Platform válida a la URL de la solicitud o en el encabezado X-Goog-Api-Key:

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

2. Permisos de OAuth 2.0

Si usas la autorización de OAuth, se admiten los siguientes permisos:

  • https://www.googleapis.com/auth/maps-platform.mapstools (recomendada)

Validación y restricciones de solicitudes

Para evitar una carga excesiva y garantizar tiempos de respuesta rápidos, las solicitudes por lotes se validan estrictamente:

  • Límite de tamaño del lote: Ambas APIs permiten un máximo de 20 elementos por solicitud.
  • Requisitos de ResolveNames:
    • Cada elemento de consultas debe especificar un parámetro de texto no vacío.
    • Las consultas deben representar un nombre o una dirección de lugar específicos (p.ej., "Googleplex, Mountain View, CA", "Torre Eiffel, París").
    • Las búsquedas categóricas generales (p.ej., "restaurantes en Nueva York") o los nombres de cadenas genéricos sin una ubicación (p.ej., "Starbucks") no son compatibles y pueden fallar en la resolución.
  • Requisitos de ResolveMapsUrls:
    • Cada URL debe ser una URL de Google Maps estructuralmente válida.
    • Estos son algunos de los formatos admitidos:
      • URL de lugar estándar: https://www.google.com/maps/place/...
      • URL acortada: https://maps.app.goo.gl/...
    • Las URLs de Maps generales basadas en consultas (p.ej., https://maps.google.com/?q=restaurant) y las URLs que no apuntan a un solo lugar único no son compatibles.

Manejo de errores parciales

Ambas APIs están diseñadas como procesadores por lotes. Si algunos elementos de un lote no se resuelven, la solicitud general no falla con un error de nivel superior. En cambio, la API muestra una respuesta de éxito parcial.

Cómo interpretar la respuesta

  1. Alineación 1:1 garantizada: Las listas de resultados (para ResolveNames) o entidades (para ResolveMapsUrls) que se muestran se asignan 1:1 con la lista de entrada.
  2. Elementos vacíos para fallas: Si un elemento en el índice i no se resolvió, la lista de resultados contendrá un objeto vacío {} en el índice i.
  3. Mapa failedRequests: La respuesta contiene un mapa failedRequests.
    • La clave es el índice basado en 0 del elemento con errores (representado como una cadena en JSON).
    • El valor es un objeto google.rpc.Status que contiene el código de error específico (de los estados estándar de gRPC/HTTP) y un mensaje detallado que explica por qué falló.

Fallas de nivel superior

Solo se muestra un error HTTP de nivel superior (p.ej., 400 Bad Request) si la solicitud no pasa la validación (p.ej., cuando se pasan más de 20 elementos o faltan campos obligatorios).

Especificación de la API y ejemplos de Curl

1. API de ResolveNames

Método: POST

https://mapstools.googleapis.com/v1alpha:resolveNames

Formato del cuerpo de la solicitud

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}
  • queries (obligatorio): Lista repetida de consultas para resolver (máximo 20).
  • locationBias (opcional): Cuadro delimitador del viewport para sesgar los resultados hacia una región local.
  • regionCode (opcional): Código de país CLDR (p.ej., "US", "FR") para sesgar los resultados.

Ejemplo de Curl: Resolución correcta

Esta consulta resuelve "Googleplex" y "Torre Eiffel".

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "Googleplex, Mountain View, CA" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveNames?key=KEY"
JSON Response
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

Ejemplo de Curl: Resultados mixtos (falla parcial)

En este ejemplo, el primer elemento es texto basura no resoluble y el segundo es un lugar válido.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "This is not a real place name at all 123456789" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveNames?key=KEY"
JSON Response
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. API de ResolveMapsUrls

Método: POST

https://mapstools.googleapis.com/v1alpha:resolveMapsUrls

Formato del cuerpo de la solicitud

{
  "urls": [
    "string"
  ]
}
  • urls (obligatorio): Lista repetida de cadenas de URL de Google Maps para resolver (máximo 20).

Ejemplo de Curl: Resolución correcta

Resolución de un vínculo de lugar estándar de Google Maps.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
JSON Response
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

Ejemplo de Curl: Resultados mixtos (falla parcial)

Resolución de una URL de lugar válida y una URL con formato incorrecto o no compatible.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "urls": [
    "https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
JSON Response
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

Ejemplo de Curl: Falla de validación

Intento de pasar más de 20 URLs en una sola solicitud.

python3 -c 'import json; print(json.dumps({"urls": ["https://www.google.com/maps/place/Googleplex"] * 21}))' | \
curl -X POST \
-H "Content-Type: application/json" \
-d @- \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
JSON Response
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}