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 muestran 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
Resolver nombres o direcciones de ubicaciones en lugares resolveNames resolve_names
Resolver URLs de Google Maps en 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 Cómo habilitar el servicio 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 válida de Google Maps Platform 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 y por proyecto
  • ResolveMapsUrls: 600 consultas por minuto y por proyecto
  • Tamaño del lote: Hasta 20 búsquedas o URLs por solicitud

Cada solicitud cuenta como una búsqueda, independientemente de la cantidad de elementos que contenga.

Precios

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

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: 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 un nombre o una dirección de lugar específicos (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éricos 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 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 generales basadas en búsquedas (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 en un lote, la respuesta incluye un campo saveToMapsUrl. Este es un solo vínculo de 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.

Siempre usa 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 errores parciales

Ambos métodos son 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, y debes verificar la respuesta para detectar errores por elemento.

Interpreta la respuesta

  1. Alineación 1:1 garantizada: La lista de results devuelta (para ResolveNames) o la lista de entities (para ResolveMapsUrls) se asignan 1:1 con la lista de entrada, por índice.
  2. Elementos vacíos para errores: Si no se pudo resolver el elemento en el índice i, la lista de resultados contiene un objeto vacío {} en el índice i.
  3. Mapa de failedRequests: 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 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 supongas que falló todo el lote porque falló un elemento. Siempre revisa failedRequests para saber 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 al resolver 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 búsquedas o tiene una búsqueda con un valor text vacío, o una solicitud ResolveMapsUrls tiene una URL vacía o que no es una URL sintácticamente válida. Si hay un elemento no válido, falla 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 del servidor (500 INTERNAL): Vuelve a intentar la solicitud.

Usa la API de Resolution con el 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 demás 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 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 una lista repetida de consultas que se deben resolver (máximo 20).
  • locationBias (opcional): Es el rectángulo delimitador del viewport para sesgar los resultados hacia una región local.
  • regionCode (opcional): Código de país de CLDR (por ejemplo, "US" o "FR") para sesgar los resultados.

Ejemplo de curl: Resolución exitosa

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/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 elemento 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 URL 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: