Géocoder un lieu

Développeurs de l'Espace économique européen (EEE)

Le geocoding de lieu vous permet de récupérer une adresse à partir d'un ID de lieu.

Les ID de lieu identifient de façon unique un lieu dans la base de données Google Places et sur Google Maps. Récupérez les ID de lieu lorsque vous géocodez une adresse. Vous pouvez également récupérer un ID de lieu à partir de nombreuses autres API, telles que Place Details (New), Text Search (New) et Nearby Search (New).

Requêtes de géocodage de lieux

Une requête de géocodage de lieu est une requête HTTP GET au format suivant :

https://geocode.googleapis.com/v4/geocode/places/PLACE_ID

où PLACE_ID contient l'ID de lieu du lieu d'intérêt.

Transmettez tous les autres paramètres en tant que paramètres d'URL ou, pour les paramètres tels que la clé API ou le masque de champ, dans les en-têtes de la requête GET. Exemple :

https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?key=API_KEY

Ou dans une commande curl :

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"

Utiliser OAuth pour effectuer une requête

L'API Geocoding v4 est compatible avec OAuth 2.0 pour l'authentification. Pour utiliser OAuth avec l'API Geocoding, le jeton OAuth doit se voir attribuer le bon niveau d'accès. L'API Geocoding est compatible avec les champs d'application suivants pour le géocodage de lieux :

  • https://www.googleapis.com/auth/maps-platform.geocode : à utiliser avec toutes les méthodes de l'API Geocoding.
  • https://www.googleapis.com/auth/maps-platform.geocode.place : à utiliser uniquement avec GeocodePlace pour le geocoding de lieux.

Vous pouvez également utiliser le champ d'application général https://www.googleapis.com/auth/cloud-platform pour toutes les méthodes de l'API Geocoding. Ce champ d'application est utile pendant le développement, mais pas en production, car il s'agit d'un champ d'application général qui permet d'accéder à toutes les méthodes.

Pour en savoir plus et obtenir des exemples, consultez Utiliser OAuth.

Réponses de geocoding de lieux

Le geocoding de lieu renvoie un objet GeocodeResult qui représente le lieu correspondant à l'ID de lieu.

Les réponses de l'API Geocoding incluent des tableaux types à deux emplacements principaux dans GeocodeResult :

  1. GeocodeResult.types : ce tableau indique le ou les types globaux du résultat. Les valeurs possibles sont extraites des types de lieux utilisés par l'API Places. Pour en savoir plus, consultez les tableaux A et B des types de lieux.
  2. GeocodeResult.addressComponents[].types : chaque composant d'adresse comporte un tableau types indiquant le type de cette partie spécifique de l'adresse. Ces valeurs sont extraites du tableau Types d'adresses et de composants d'adresse utilisé par l'API Places.

L'objet JSON complet est au format suivant :

{
  "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "location": {
    "latitude": 37.4220541,
    "longitude": -122.08532419999999
  },
  "granularity": "ROOFTOP",
  "viewport": {
    "low": {
      "latitude": 37.4209489697085,
      "longitude": -122.08846930000001
    },
    "high": {
      "latitude": 37.4236469302915,
      "longitude": -122.0829156
    }
  },
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  "addressComponents": [
    {
      "longText": "1600",
      "shortText": "1600",
      "types": [
        "street_number"
      ]
    },
    {
      "longText": "Amphitheatre Parkway",
      "shortText": "Amphitheatre Pkwy",
      "types": [
        "route"
      ],
      "languageCode": "en"
    },
    {
      "longText": "Mountain View",
      "shortText": "Mountain View",
      "types": [
        "locality",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "Santa Clara County",
      "shortText": "Santa Clara County",
      "types": [
        "administrative_area_level_2",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "California",
      "shortText": "CA",
      "types": [
        "administrative_area_level_1",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "United States",
      "shortText": "US",
      "types": [
        "country",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "94043",
      "shortText": "94043",
      "types": [
        "postal_code"
      ]
    }
  ],
  "types": [
    "establishment",
    "point_of_interest"
  ]
}

Paramètres obligatoires

  • place : ID de lieu pour lequel vous souhaitez obtenir l'adresse lisible par l'humain. L'ID de lieu est un identifiant unique qui peut être utilisé avec d'autres API Google. Par exemple, vous pouvez utiliser le placeID renvoyé par l'API Roads pour obtenir l'adresse d'un point ancré. Pour en savoir plus sur les ID de lieu, consultez ID de lieu.

Paramètres facultatifs

  • languageCode

    Langue dans laquelle les résultats doivent être renvoyés.

    • Consultez la liste des langues acceptées. Google met souvent à jour les langues acceptées. Cette liste n'est donc pas exhaustive.
    • Si languageCode n'est pas fourni, l'API utilise par défaut la langue et l'écriture locales du lieu. Si vous spécifiez un code de langue non valide, l'API renvoie une erreur INVALID_ARGUMENT.
    • L'API s'efforce de fournir une adresse postale lisible à la fois pour l'utilisateur et pour les habitants. Pour atteindre cet objectif, elle renvoie les adresses postales dans la langue locale, translittérées dans un script lisible par l'utilisateur si nécessaire, en respectant la langue préférée. Toutes les autres adresses sont renvoyées dans la langue préférée. Les composants d'adresse sont tous renvoyés dans la même langue, qui est choisie à partir du premier composant.
    • Si aucun nom n'est disponible dans la langue préférée, l'API utilise la correspondance la plus proche.
    • La langue préférée a une légère influence sur l'ensemble des résultats que l'API choisit de renvoyer et l'ordre dans lequel ils sont renvoyés. Le geocoder interprète les abréviations différemment selon la langue, par exemple les abréviations des types de rues ou les synonymes qui peuvent être valides dans une langue, mais pas dans une autre.

  • regionCode

    Code de région sous la forme d'un code CLDR à deux caractères. Il n'existe pas de valeur par défaut. La plupart des codes CLDR sont identiques aux codes ISO 3166-1.

    Lors du géocodage d'une adresse (géocodage direct), ce paramètre peut influencer, mais pas limiter complètement, les résultats du service à la région spécifiée. Lors du geocoding d'un lieu ou d'un endroit, du geocoding inversé ou du geocoding de lieu, ce paramètre peut être utilisé pour mettre en forme l'adresse. Dans tous les cas, ce paramètre peut affecter les résultats en fonction de la législation applicable.

  • FieldMask

    Créez un masque de champ de réponse pour spécifier les champs à renvoyer dans la réponse. Transmettez le masque de champ de réponse à la méthode à l'aide du paramètre d'URL $fields ou fields, ou de l'en-tête HTTP X-Goog-FieldMask. Par exemple, la requête ci-dessous ne renverra que le champ formattedAddress de la réponse.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: formattedAddress' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    La réponse est : 
    {
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA"
}

    Pour en savoir plus, consultez Choisir les champs à renvoyer.