API de Maps Tools Resolution

La API de Maps Tools Resolution forma parte de Maps Grounding Lite. Proporciona extremos por lotes que resuelven nombres de ubicaciones y URLs de Google Maps en IDs de lugar de Google Maps. Puedes usar los IDs de lugar que se devuelven con otras APIs de Google Maps Platform. Cada respuesta también incluye un vínculo que guarda los lugares resueltos como una lista en Google Maps.

La API de Resolution está disponible como métodos de REST y como herramientas en el servidor de MCP de Maps Grounding Lite:

Función Método REST Herramienta de MCP
Resuelve nombres o direcciones de ubicaciones en lugares resolveNames resolve_names
Cómo resolver URLs de Google Maps para lugares resolveMapsUrls resolve_maps_urls

Antes de comenzar

Para usar la API de Resolution, necesitas un proyecto de Google Cloud con la facturación habilitada y el servicio de la API de Maps Grounding Lite habilitado. Para obtener instrucciones, consulta Habilita el servicio de Maps Grounding Lite en tu proyecto de Google Cloud.

Acceso y autenticación de la API

La API de Resolution admite credenciales de clave de API y de OAuth 2.0.

Clave de API

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

https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY

En los ejemplos de esta página, reemplaza API_KEY por tu clave de API.

Alcances de OAuth 2.0

Si usas la autorización de OAuth, se admite el siguiente permiso:

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

Límites de uso

Las siguientes cuotas predeterminadas se aplican a la API de Resolution:

  • ResolveNames: 600 consultas por minuto, por proyecto.
  • ResolveMapsUrls: 600 consultas por minuto por proyecto
  • Tamaño del lote: Hasta 20 búsquedas o URLs por solicitud.

Cada solicitud cuenta como una consulta, independientemente de la cantidad de elementos que contenga.

Precios

Las solicitudes a ResolveNames y ResolveMapsUrls se facturan sin cargo ($0) con el SKU API de Places Text Search Essentials (IDs Only). Al igual que con el resto de Maps Grounding Lite, tu proyecto debe tener una cuenta de facturación.

Validación y restricciones de solicitudes

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: Ambos métodos permiten un máximo de 20 elementos por solicitud.
  • Requisitos de ResolveNames:
    • Cada elemento de queries debe especificar un parámetro text no vacío.
    • Las búsquedas deben representar el nombre o la dirección de un lugar específico (por ejemplo, "Googleplex, Mountain View, CA" o "Torre Eiffel, París").
    • No se admiten las búsquedas categóricas generales (por ejemplo, "restaurantes en Nueva York") ni los nombres de cadenas genéricas sin una ubicación (por ejemplo, "Starbucks"), y es posible que no se resuelvan.
  • 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/...
    • No se admiten las URLs de Maps basadas en búsquedas generales (por ejemplo, https://maps.google.com/?q=restaurant) ni las URLs que no dirigen a un solo lugar único.

Cómo guardar lugares resueltos en Google Maps

Si se resuelve al menos un elemento de un lote, la respuesta incluye un campo saveToMapsUrl. Este es un vínculo único de Google Maps que contiene todos los lugares resueltos correctamente en el lote. Presenta este vínculo a los usuarios que quieran guardar, compartir o abrir los lugares resueltos como una lista en Google Maps.

Usa siempre el vínculo que devuelve la API. No construyas el vínculo por tu cuenta. Si no se resuelve ningún elemento del lote, la respuesta no incluye saveToMapsUrl.

Cómo controlar los errores parciales

Ambos métodos son 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 devuelve una respuesta de éxito parcial, y debes verificar la respuesta para detectar fallas por elemento.

Interpreta la respuesta

  1. Alineación 1:1 garantizada: La lista de results (para ResolveNames) o la lista de entities (para ResolveMapsUrls) que se muestra se asigna 1:1 con la lista de entrada, por índice.
  2. Elementos vacíos para fallas: Si el elemento en el índice i no se pudo resolver, la lista de resultados contiene 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 y un mensaje que explica por qué falló el elemento.
  4. saveToMapsUrl solo abarca los éxitos: El vínculo saveToMapsUrl solo incluye los elementos que se resolvieron. No se incluyen los elementos que fallaron.

No asumas que todo el lote falló porque un elemento falló. Siempre verifica failedRequests para averiguar qué elementos, si los hay, no se pudieron resolver.

Errores por elemento

En la siguiente tabla, se enumeran los errores por elemento que puedes ver en failedRequests:

Método Causa Código Mensaje
ResolveNames No se puede resolver el nombre o la dirección en un lugar. 5 (NOT_FOUND) Place not found.
ResolveMapsUrls No se puede resolver la URL en un lugar. 3 (INVALID_ARGUMENT) Failed to resolve Maps URL to a place.
Ambos métodos Se produjo un error interno cuando se resolvía el elemento. 13 (INTERNAL) Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support

Vuelve a intentar solo los elementos que fallaron con INTERNAL.

Fallas de nivel superior

La API devuelve un error de nivel superior en lugar de una respuesta parcial en los siguientes casos:

  • Solicitud no válida (400 INVALID_ARGUMENT): La solicitud contiene más de 20 elementos, una solicitud ResolveNames no tiene consultas o tiene una consulta con un valor text vacío, o una solicitud ResolveMapsUrls tiene una URL que está vacía o no es una URL sintácticamente válida. Un elemento no válido hace que falle toda la solicitud.
  • Errores de autenticación, permiso o cuota: Por ejemplo, falta la clave de API o no es válida, o la solicitud supera los límites de uso.
  • Errores de servidor (500 INTERNAL): Vuelve a intentar la solicitud.

Usa la API de Resolution con MCP

El servidor de MCP de Maps Grounding Lite en https://mapstools.googleapis.com/mcp expone la API de Resolution como dos herramientas:

  • resolve_names: Resuelve un lote de nombres o direcciones de ubicaciones en IDs de lugar.
  • resolve_maps_urls: Resuelve un lote de URLs de Google Maps en IDs de lugar.

Cuando configuras tu LLM para que use el servidor de MCP de Maps Grounding Lite, estas herramientas están disponibles junto con las otras herramientas de Maps Grounding Lite. Las herramientas aceptan las mismas entradas, aplican las mismas restricciones y devuelven la misma respuesta de falla parcial que los métodos de REST.

Las respuestas de la herramienta incluyen el campo save_to_maps_url. Las descripciones de las herramientas indican al LLM que presente este vínculo cuando el usuario quiera guardar, compartir o abrir los lugares resueltos como una lista en Google Maps, en lugar de construir un vínculo por sí mismo.

En el siguiente ejemplo, se usa curl para llamar directamente a la herramienta de resolve_names:

curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--header 'X-Goog-Api-Key: API_KEY' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      "queries": [
        { "text": "Googleplex, Mountain View, CA" },
        { "text": "Eiffel Tower, Paris" }
      ]
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Para llamar a resolve_maps_urls, establece name en resolve_maps_urls y pasa un array urls en arguments.

Especificación de la API de REST y ejemplos de curl

ResolveNames

Método: POST

https://mapstools.googleapis.com/v1: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 la lista repetida de consultas que se deben resolver (máximo 20).
  • locationBias (opcional): Es el cuadro delimitador del viewport para sesgar los resultados hacia una región local.
  • regionCode (opcional): Es el código de país CLDR (por ejemplo, "US" o "FR") para sesgar los resultados.

Ejemplo de curl: Resolución exitosa

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/v1:resolveNames?key=API_KEY"
Respuesta JSON
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw,ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

Ejemplo de curl: Resultados mixtos (falla parcial)

En este ejemplo, el primer elemento es texto 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/v1:resolveNames?key=API_KEY"
Respuesta JSON
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

ResolveMapsUrls

Método: POST

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

Formato del cuerpo de la solicitud

{
  "urls": [
    "string"
  ]
}
  • urls (obligatorio): Es una lista repetida de cadenas de URLs de Google Maps que se deben resolver (máximo 20).

Ejemplo de curl: Resolución exitosa

En el siguiente ejemplo, se resuelve una URL 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!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"
Respuesta JSON
{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Ejemplo de curl: Resultados mixtos (falla parcial)

En el siguiente ejemplo, se resuelve una URL de lugar válida y una URL que no se puede resolver en un lugar:

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!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"
Respuesta JSON
{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Failed to resolve Maps URL to a place."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Ejemplo de curl: Error de validación

En el siguiente ejemplo, se pasan 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/v1:resolveMapsUrls?key=API_KEY"
Respuesta JSON
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}

Enviar comentarios

Para informar un problema o compartir comentarios sobre la API de Resolution, usa el componente de la herramienta de seguimiento de errores pública de Maps Grounding Lite: