API Maps Tools Resolution

L'API Maps Tools Resolution fait partie de Maps Grounding Lite. Il fournit des points de terminaison par lot qui résolvent les noms de lieux et les URL Google Maps en ID de lieu Google Maps. Vous pouvez utiliser les ID de lieu renvoyés avec d'autres API Google Maps Platform. Chaque réponse inclut également un lien qui enregistre les lieux résolus sous forme de liste dans Google Maps.

L'API Resolution est disponible à la fois sous forme de méthodes REST et d'outils sur le serveur MCP Maps Grounding Lite :

Capacité Méthode REST Outil MCP
Résoudre des noms ou des adresses de lieux en lieux resolveNames resolve_names
Résoudre les URL Google Maps en lieux resolveMapsUrls resolve_maps_urls

Avant de commencer

Pour utiliser l'API Resolution, vous devez disposer d'un projet Google Cloud pour lequel la facturation est activée, et le service d'API Maps Grounding Lite doit être activé. Pour obtenir des instructions, consultez Activer le service Grounding Lite de Maps sur votre projet Google Cloud.

Accès et authentification de l'API

L'API Resolution est compatible avec les identifiants de clé API et OAuth 2.0.

Clé API

Vous pouvez authentifier les requêtes en transmettant une clé API Google Maps Platform valide dans l'en-tête X-Goog-Api-Key ou en l'ajoutant à l'URL de la requête :

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

Dans les exemples de cette page, remplacez API_KEY par votre clé API.

Champs d'application OAuth 2.0

Si vous utilisez l'autorisation OAuth, le champ d'application suivant est accepté :

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

Limites d'utilisation

Les quotas par défaut suivants s'appliquent à l'API Resolution :

  • ResolveNames : 600 requêtes par minute et par projet.
  • ResolveMapsUrls : 600 requêtes par minute et par projet.
  • Taille du lot : jusqu'à 20 requêtes ou URL par requête.

Chaque requête compte comme une seule requête, quel que soit le nombre d'éléments qu'elle contient.

Tarifs

Les requêtes adressées à ResolveNames et ResolveMapsUrls sont facturées sans frais (0 $) sous le SKU API Places Text Search Essentials (IDs Only). Comme pour le reste de Maps Grounding Lite, votre projet doit disposer d'un compte de facturation.

Validation et contraintes des requêtes

Pour éviter une charge excessive et garantir des temps de réponse rapides, les requêtes par lot sont strictement validées :

  • Limite de taille de lot : les deux méthodes autorisent un maximum de 20 éléments par requête.
  • Exigences de ResolveNames :
    • Chaque élément de queries doit spécifier un paramètre text non vide.
    • Les requêtes doivent représenter un nom de lieu ou une adresse spécifique (par exemple, "Googleplex, Mountain View, CA" ou "Tour Eiffel, Paris").
    • Les recherches catégorielles générales (par exemple, "restaurants à New York") ou les noms de chaînes génériques sans emplacement (par exemple, "Starbucks") ne sont pas acceptés et peuvent ne pas aboutir.
  • Exigences de ResolveMapsUrls :
    • Chaque URL doit être une URL Google Maps structurellement valide.
    • Formats compatibles (liste non exhaustive) :
      • URL de lieu standard : https://www.google.com/maps/place/...
      • URL raccourcie : https://maps.app.goo.gl/...
    • Les URL Maps générales basées sur des requêtes (par exemple, https://maps.google.com/?q=restaurant) et les URL qui ne pointent pas vers un seul lieu unique ne sont pas acceptées.

Enregistrer les lieux résolus dans Google Maps

Si au moins un élément d'un lot est résolu, la réponse inclut un champ saveToMapsUrl. Il s'agit d'un lien Google Maps unique qui contient tous les lieux du lot qui ont été résolus. Présentez ce lien aux utilisateurs qui souhaitent enregistrer, partager ou ouvrir les lieux résolus sous forme de liste dans Google Maps.

Utilisez toujours le lien renvoyé par l'API. Ne créez pas le lien vous-même. Si aucun élément du lot n'est résolu, la réponse n'inclut pas saveToMapsUrl.

Gérer les erreurs partielles

Les deux méthodes sont des processeurs par lot. Si certains éléments d'un lot ne sont pas résolus, la requête globale n'échoue pas avec une erreur de niveau supérieur. À la place, l'API renvoie une réponse de réussite partielle, et vous devez vérifier la réponse pour détecter les échecs par élément.

Interpréter la réponse

  1. Alignement 1:1 garanti : la liste results renvoyée (pour ResolveNames) ou la liste entities (pour ResolveMapsUrls) correspond à un mappage 1:1 avec la liste d'entrée, par index.
  2. Éléments vides pour les échecs : si la résolution de l'élément à l'index i a échoué, la liste de résultats contient un objet vide {} à l'index i.
  3. Mappage failedRequests : la réponse contient un mappage failedRequests.
    • La clé est l'index de l'élément ayant échoué (représenté sous forme de chaîne en JSON), en commençant par 0.
    • La valeur est un objet google.rpc.Status contenant le code d'erreur et un message expliquant pourquoi l'élément a échoué.
  4. saveToMapsUrl ne couvre que les réussites : le lien saveToMapsUrl n'inclut que les éléments qui ont été résolus. Les éléments ayant échoué ne sont pas inclus.

Ne partez pas du principe que l'ensemble du lot a échoué parce qu'un élément a échoué. Vérifiez toujours failedRequests pour savoir quels éléments n'ont pas pu être résolus, le cas échéant.

Erreurs par élément

Le tableau suivant répertorie les erreurs par élément que vous pouvez voir dans failedRequests :

Méthode Cause Code Message
ResolveNames Le nom ou l'adresse ne peuvent pas être résolus sous forme de lieu. 5 (NOT_FOUND) Place not found.
ResolveMapsUrls L'URL ne peut pas être résolue en un lieu. 3 (INVALID_ARGUMENT) Failed to resolve Maps URL to a place.
Les deux méthodes Une erreur interne s'est produite lors de la résolution de l'élément. 13 (INTERNAL) Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support

Réessayez uniquement les éléments qui ont échoué avec INTERNAL.

Échecs de premier niveau

L'API renvoie une erreur de premier niveau au lieu d'une réponse partielle dans les cas suivants :

  • Requête non valide (400 INVALID_ARGUMENT) : la requête contient plus de 20 éléments, une requête ResolveNames ne comporte aucune requête ou comporte une requête avec une valeur text vide, ou une requête ResolveMapsUrls comporte une URL vide ou qui n'est pas valide d'un point de vue syntaxique. Un seul élément non valide entraîne l'échec de l'ensemble de la requête.
  • Erreurs d'authentification, d'autorisation ou de quota : par exemple, la clé API est manquante ou non valide, ou la requête dépasse les limites d'utilisation.
  • Erreurs du serveur (500 INTERNAL) : relancez la requête.

Utiliser l'API Resolution avec MCP

Le serveur MCP Maps Grounding Lite sur https://mapstools.googleapis.com/mcp expose l'API Resolution sous la forme de deux outils :

Lorsque vous configurez votre LLM pour qu'il utilise le serveur MCP Maps Grounding Lite, ces outils sont disponibles avec les autres outils Maps Grounding Lite. Les outils acceptent les mêmes entrées, appliquent les mêmes contraintes et renvoient la même réponse d'échec partiel que les méthodes REST.

Les réponses de l'outil incluent le champ save_to_maps_url. Les descriptions des outils indiquent au LLM de présenter ce lien lorsque l'utilisateur souhaite enregistrer, partager ou ouvrir les lieux résolus sous forme de liste dans Google Maps, au lieu de créer lui-même un lien.

L'exemple suivant utilise curl pour appeler directement l'outil 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
}'

Pour appeler resolve_maps_urls, définissez name sur resolve_maps_urls et transmettez un tableau urls dans arguments.

Spécification de l'API REST et exemples curl

ResolveNames

Méthode : POST

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

Format du corps de la requête

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}
  • queries (obligatoire) : liste répétée de requêtes à résoudre (20 maximum).
  • locationBias (facultatif) : cadre de délimitation de la fenêtre d'affichage pour orienter les résultats vers une région locale.
  • regionCode (facultatif) : code de pays CLDR (par exemple, "US" ou "FR") pour biaiser les résultats.

Exemple Curl : résolution réussie

Cette requête résout "Googleplex" et "Tour 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"
Réponse 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"
}

Exemple curl : résultats mitigés (échec partiel)

Dans cet exemple, le premier élément est un texte qui ne peut pas être résolu, et le second est un lieu valide.

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"
Réponse 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éthode : POST

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

Format du corps de la requête

{
  "urls": [
    "string"
  ]
}
  • urls (obligatoire) : liste répétée de chaînes d'URL Google Maps à résoudre (20 maximum).

Exemple Curl : résolution réussie

L'exemple suivant résout une URL de lieu Google Maps standard :

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"
Réponse JSON
{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Exemple curl : résultats mitigés (échec partiel)

L'exemple suivant résout une URL de lieu valide et une URL qui ne peut pas être résolue en lieu :

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"
Réponse 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"
}

Exemple Curl : échec de la validation

L'exemple suivant transmet plus de 20 URL dans une seule requête :

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"
Réponse JSON
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}

Envoyer des commentaires

Pour signaler un problème ou envoyer des commentaires sur l'API Resolution, utilisez le composant public Issue Tracker de Maps Grounding Lite :