API Maps Tools Resolution (expérimentale)

L'API Maps Tools Resolution fournit des points de terminaison de traitement par lot pour résoudre les noms de lieux et les URL en ID de lieu Google Maps.

Accès aux API et authentification

Méthodes d'authentification

Les API sont compatibles avec les identifiants clé API et OAuth 2.0 :

1. Clé API

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

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

2. Champs d'application OAuth 2.0

Si vous utilisez l'autorisation OAuth, les niveaux d'accès suivants sont acceptés :

  • https://www.googleapis.com/auth/maps-platform.mapstools (recommandé)

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 des lots : les deux API autorisent un maximum de 20 éléments par requête.
  • Conditions requises pour ResolveNames :
    • Chaque élément de requête doit spécifier un paramètre de texte non vide.
    • Les requêtes doivent représenter un nom de lieu ou une adresse spécifiques (par exemple, "Googleplex, Mountain View, CA", "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 localisation (par exemple, "Starbucks") ne sont pas acceptées et peuvent ne pas être résolues.
  • Conditions requises pour ResolveMapsUrls :
    • Chaque URL doit être une URL Google Maps structurellement valide.
    • Voici quelques formats compatibles :
      • URL standard du lieu : 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 lieu unique ne sont pas acceptées.

Gérer les erreurs partielles

Les deux API sont conçues comme 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 niveau supérieur. Au lieu de cela, l'API renvoie une réponse Partial Success (Succès partiel).

Interpréter la réponse

  1. Alignement 1:1 garanti : les listes de résultats renvoyées (pour ResolveNames) ou d'entités (pour ResolveMapsUrls) sont mappées 1:1 avec la liste d'entrée.
  2. Éléments vides en cas d'échec : si un élément à l'index i n'a pas pu être résolu, la liste des résultats contiendra un objet vide {} à l'index i.
  3. failedRequests Map : la réponse contient une carte failedRequests.
    • La clé correspond à 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 spécifique (à partir des états gRPC/HTTP standards) et un message détaillé expliquant pourquoi la requête a échoué.

Échecs de premier niveau

Une erreur HTTP de premier niveau (par exemple, 400 Bad Request) n'est renvoyée que si la requête échoue à la validation (par exemple, lorsque plus de 20 éléments sont transmis ou que des champs obligatoires sont manquants).

Spécification de l'API et exemples Curl

1. API ResolveNames

Méthode : POST

https://mapstools.googleapis.com/v1alpha: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/v1alpha:resolveNames?key=KEY"
JSON Response
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

Exemple Curl : résultats mixtes (échec partiel)

Dans cet exemple, le premier élément est un texte indéchiffrable, tandis que le deuxième 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/v1alpha:resolveNames?key=KEY"
JSON Response
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. API ResolveMapsUrls

Méthode : POST

https://mapstools.googleapis.com/v1alpha: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

Résoudre un lien standard vers un lieu 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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
JSON Response
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

Exemple Curl : résultats mixtes (échec partiel)

Résolution d'une URL de lieu valide et d'une URL incorrecte/non compatible.

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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
JSON Response
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

Exemple Curl : échec de la validation

Vous avez tenté de transmettre 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/v1alpha:resolveMapsUrls?key=KEY"
JSON Response
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}