Géocoder une adresse inversée

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

Le geocoding inversé traduit un emplacement sur une carte en une adresse lisible par l'humain. Vous représentez l'emplacement sur la carte par ses coordonnées de latitude et de longitude.

Lorsque vous effectuez un géocodage inversé d'un lieu, la réponse contient les éléments suivants :

Cette API renvoie différents types d'adresse, de l'adresse postale la plus précise aux entités politiques les moins précises comme les quartiers, les villes, les départements et les États. L'adresse la plus précise est généralement le premier résultat. Si vous souhaitez faire correspondre un type d'adresse spécifique, utilisez le paramètre types.

Requête de geocoding inversé

Une requête de géocodage inversé est une requête HTTP GET. Vous pouvez spécifier l'emplacement sous la forme d'une chaîne non structurée :

https://geocode.googleapis.com/v4/geocode/location/LATITUDE,LONGITUDE

Ou sous la forme d'un ensemble structuré de coordonnées de latitude et de longitude représentées par des paramètres de requête :

https://geocode.googleapis.com/v4/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

Vous utilisez généralement le format structuré lorsque vous traitez des composants de lieu capturés dans un formulaire HTML.

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 :

Transmettre une chaîne d'emplacement non structurée

Un emplacement non structuré est un emplacement formaté sous la forme d'une chaîne de coordonnées de latitude et de longitude séparées par une virgule :

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?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/location/37.4225508,-122.0846338"

Transmettre un lieu structuré

Spécifiez l'emplacement structuré à l'aide du paramètre de requête location, de type LatLng. L'objet LatLng vous permet de spécifier la latitude et la longitude en tant que paramètres de requête distincts :

https://geocode.googleapis.com/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

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 geocoding inversé :

  • 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.location : à utiliser uniquement avec GeocodeLocation pour le geocoding inversé.

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éponse de geocoding inversé

Le geocoding inversé renvoie un objet GeocodeLocationResponse contenant les éléments suivants :

  • Tableau results d'objets GeocodeResult qui représentent le 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.

    Le geocoding inversé renvoie plusieurs résultats dans le tableau results. Les résultats ne correspondent pas uniquement à des adresses postales, mais également à toutes les possibilités de nommer géographiquement un lieu. Par exemple, lors du geocoding d'un point dans la ville de Chicago, le point géocodé peut être indiqué sous la forme d'une adresse postale, d'une ville (Chicago), d'un État (Illinois) ou d'un pays (États-Unis). Toutes ces désignations sont des "adresses" pour le geocoder. Le geocoding inversé renvoie l'un de ces types comme résultat valide.

  • Le champ plusCode, de type PlusCode, contient le Plus Code qui se rapproche le plus de la latitude et de la longitude de la requête. De plus, chaque élément du tableau results contient un Plus Code. La distance entre le Plus Code décodé et le point de la requête est inférieure à 10 mètres.

    Remarque : L'API ne renvoie pas toujours de Plus Codes.

L'objet JSON complet est au format suivant :

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "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": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "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"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

Paramètres obligatoires

  • position

    Coordonnées de latitude et de longitude spécifiant l'emplacement pour lequel vous souhaitez obtenir l'adresse lisible par l'humain la plus proche.

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.

  • niveau de détail

    Une ou plusieurs granularités de localisation, spécifiées en tant que paramètres de requête distincts, comme défini par Granularity. Si vous spécifiez plusieurs paramètres granularity, l'API renvoie toutes les adresses correspondant à l'une des précisions.

    Le paramètre granularity ne limite pas la recherche aux niveaux de précision géographique spécifiés. En revanche, granularity agit comme un filtre post-recherche. L'API extrait tous les résultats pour le location spécifié, puis supprime ceux qui ne correspondent pas aux niveaux de précision géographique spécifiés.

    Si vous spécifiez à la fois types et granularity, l'API ne renvoie que les résultats qui correspondent aux deux. Exemple :

    https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

  • Types

    Un ou plusieurs types d'adresses, spécifiés en tant que paramètres de requête distincts. Les valeurs possibles sont extraites du tableau Types d'adresses et de composants d'adresse de la page "Types de lieux (New)". Si vous spécifiez plusieurs paramètres types, l'API renvoie toutes les adresses correspondant à l'un des types.

    Le paramètre types ne limite pas la recherche aux types d'adresses spécifiés. En revanche, types agit comme un filtre post-recherche. L'API récupère tous les résultats pour l'emplacement spécifié, puis supprime ceux qui ne correspondent pas aux types d'adresse spécifiés.

    Si vous spécifiez à la fois types et granularity, l'API ne renvoie que les résultats qui correspondent aux deux. Exemple :

    https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

  • 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 les champs placeID de la réponse.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
    La réponse est : 
    {
  "results": [
    {
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
    },
    {
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
    },
    {
      "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
    },
    {
      "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
    },
    ...
  ]
}

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