API de Maps Tools Resolution

La API de Maps Tools Resolution forma parte de las herramientas de agentes de Maps Experience (antes, 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 devueltos 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 herramientas de agentes de Maps Experience:

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 Experience agent tools habilitado. Para obtener instrucciones, consulta Habilita las herramientas de agentes de Maps Experience en tu proyecto de Google Cloud.

Acceso y autenticación de la API

La API de Resolution admite credenciales de clave de API y 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 para cada proyecto.
• ResolveMapsUrls: 600 consultas por minuto para cada proyecto
• Tamaño del lote: Hasta 20 consultas o URLs en cada 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 (USD 0) con el SKU API de Places Text Search Essentials (IDs Only). Al igual que con el resto de las herramientas de agentes de Maps Experience, 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 según las siguientes reglas:

• Límite de tamaño del lote: Ambos métodos permiten un máximo de 20 elementos en cada solicitud.
• Requisitos de ResolveNames:
  • Cada elemento de queries debe especificar un parámetro text que no esté vacío.
  • Las consultas deben representar un nombre de lugar o una dirección específicos, como "Googleplex, Mountain View, CA" o "Eiffel Tower, Paris".
  • No se admiten las búsquedas categóricas generales, como "restaurants in New York", ni los nombres de cadenas genéricos sin una ubicación, como "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, como 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 su lugar, 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 results (para ResolveNames) o la lista entities (para ResolveMapsUrls) que se muestra se asigna 1:1 con la lista de entrada, por índice.
2. Elementos vacíos para errores: Si el elemento en el índice i no se resolvió, 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:

Reintenta 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 herramientas de agentes de Maps Experience 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, estas herramientas están disponibles junto con las otras herramientas de agentes de Experimentos de Maps. 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 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 seguimiento de errores público de las herramientas de agentes de Maps Experience:

• Informa un error
• Envía una solicitud de función
• Enviar comentarios