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 à l'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 champs d'application suivants sont compatibles :

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

Validation des requêtes 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 des lots : les deux API autorisent un maximum de 20 éléments par requête.
  • Exigences de 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écifique (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 lieu (par exemple, "Starbucks") ne sont pas compatibles et peuvent échouer.
  • Exigences de ResolveMapsUrls:
    • Chaque URL doit être une URL Google Maps structurellement valide.
    • Les formats compatibles incluent les suivants :
      • 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 compatibles.

Gérer les erreurs partielles

Les deux API sont conçues comme des processeurs par lot. Si certains éléments d'un lot ne peuvent pas être résolus, la requête globale n'échoue pas avec une erreur de niveau supérieur. Au lieu de cela, l'API renvoie une réponse 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 de résultats contient un objet vide {} à l'index i.
  3. Carte failedRequests : la réponse contient une carte failedRequests.
    • La clé est l'index de base zéro 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 l'opération a échoué.

Échecs de niveau supérieur

Une erreur HTTP de niveau supérieur (par exemple, 400 Bad Request) n'est renvoyée que si la requête échoue à la validation (par exemple, lorsque vous transmettez plus de 20 éléments 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 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 pays CLDR (par exemple, "US", "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ésirable non résolvable, 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/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ésolution d'un lien 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!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 mal formée/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

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