API de Maps Tools Resolution (experimental)

La API de Maps Tools Resolution proporciona extremos de procesamiento por lotes para resolver nombres y URLs de ubicaciones en IDs de lugar de Google Maps.

Acceso y autenticación de la API

Métodos de autenticación

Las APIs admiten credenciales de clave de API y de 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 la solicitud

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

  • 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 búsquedas 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 es posible que no se resuelvan.
  • Requisitos de ResolveMapsUrls:
    • Cada URL debe ser una URL de Google Maps válida estructuralmente.
    • Estos son algunos de los formatos admitidos:
      • URL del lugar estándar: https://www.google.com/maps/place/...
      • URL acortada: https://maps.app.goo.gl/...
    • No se admiten las URLs de Maps basadas en búsquedas generales (p.ej., https://maps.google.com/?q=restaurant) ni las URLs que no dirigen a un solo lugar único.

Cómo controlar errores parciales

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

Cómo interpretar la respuesta

  1. Alineación garantizada 1:1: 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 errores: Si no se pudo resolver un elemento en el índice i, la lista de resultados contendrá un objeto vacío {} en el índice i.
  3. failedRequests Map: La respuesta contiene un mapa de failedRequests.
    • La clave es el índice basado en 0 del elemento que falló (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 devuelve 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): Es una lista repetida de consultas que se deben resolver (máximo 20).
  • locationBias (opcional): Es el rectángulo delimitador del viewport que se usa para sesgar los resultados hacia una región local.
  • regionCode (opcional): Código de país de CLDR (p.ej., "US", "FR") para sesgar los resultados.

Ejemplo de Curl: Resolución correcta

Esta búsqueda 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 que no se puede resolver, 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): Es una lista repetida de cadenas de URL de Google Maps que se deben resolver (máximo 20).

Ejemplo de Curl: Resolución correcta

Resuelve un vínculo estándar de un lugar 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)

Se resuelve una URL de lugar válida y una URL con formato incorrecto o no admitida.

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: Error de validación

Intentaste 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"
  }
}