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 en tant que méthodes REST et en tant qu'outils sur le serveur MCP Maps Grounding Lite :

Avant de commencer

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

Accès à l'API et authentification

L'API Resolution est compatible avec les clés API et les identifiants 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 demande.

Chaque demande est comptabilisée comme une requête, quel que soit le nombre d'éléments qu'elle contient.

Tarifs

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

Validation des demandes et contraintes

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 du lot : les deux méthodes autorisent un maximum de 20 éléments par requête.
• Conditions requises pour 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écifiques (par exemple, "Googleplex, Mountain View, CA" ou "Tour Eiffel, Paris").
  • Les recherches générales par catégorie (par exemple, "restaurants à New York") ou les noms de chaînes génériques sans localisation (par exemple, "Starbucks") ne sont pas acceptées et peuvent ne pas aboutir.
• Conditions requises pour ResolveMapsUrls :
  • Chaque URL doit être une URL Google Maps valide sur le plan structurel.
  • Formats compatibles :
    • URL standard du lieu : https://www.google.com/maps/place/...
    • URL raccourcie : https://maps.app.goo.gl/...
  • Les URL Maps basées sur des requêtes générales (par exemple, https://maps.google.com/?q=restaurant) et celles qui ne renvoient pas à un 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 résolus avec succès dans le lot. 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 la résolution de certains éléments d'un lot échoue, la requête globale n'échoue pas avec une erreur de premier niveau. L'API renvoie plutôt une réponse de réussite partielle. Vous devez donc vérifier la réponse pour 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 1:1 à la liste d'entrée, par index.
2. Éléments vides en cas d'échec : si l'élément à l'index i n'a pas pu être résolu, la liste des résultats contient un objet vide {} à l'index i.
3. failedRequests map : la réponse contient une carte failedRequests.
   • La clé est l'index de base 0 de l'élément ayant échoué (représenté sous forme de chaîne au format JSON).
   • 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 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, le cas échéant, n'ont pas pu être résolus.

Erreurs par article

Le tableau suivant répertorie les erreurs par article qui peuvent s'afficher dans failedRequests :

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 une URL syntaxiquement valide. 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 de serveur (500 INTERNAL) : réessayez la requête.

Utiliser l'API Resolution avec MCP

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

• resolve_names : résout un lot de noms ou d'adresses de lieux en ID de lieux.
• resolve_maps_urls : résout un lot d'URL Google Maps en ID de lieux.

Lorsque vous configurez votre LLM pour qu'il utilise le serveur MCP Maps Grounding Lite, ces outils sont disponibles en plus des 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 d'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 des 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 pays CLDR (par exemple, "US" ou "FR") pour orienter 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 mixtes (échec partiel)

Dans cet exemple, le premier élément est un texte qui ne peut pas être résolu, et le deuxième élément 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 mixtes (é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 même 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 partager vos commentaires sur l'API Resolution, utilisez le composant public Issue Tracker de Maps Grounding Lite :

• Signaler un bug
• Envoyer une demande de fonctionnalité
• Envoyer des commentaires