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. Vous représentez l'emplacement sur la carte à l'aide des coordonnées de latitude et de longitude.

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

Cette API renvoie différents types d'adresses, 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.

Demande 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/v4beta/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/v4beta/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

Vous utilisez généralement le format structuré lorsque vous traitez des composants de localisation 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 dans le cadre de la requête GET. Exemple :

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

Une position non structurée est une position mise en forme 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/v4beta/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/v4beta/geocode/location/37.4225508,-122.0846338"

Transmettre un emplacement 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/v4beta/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 être associé au champ d'application approprié. L'API Geocoding est compatible avec les niveaux d'accès suivants pour le géocodage inversé :

  • https://www.googleapis.com/auth/maps-platform.geocode — À utiliser avec tous les points de terminaison 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 https://www.googleapis.com/auth/cloud-platform général pour tous les points de terminaison 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 à tous les points de terminaison.

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

Réponse de geocoding inversé

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

  • Tableau results d'objets GeocodeResult représentant le lieu.

    Le geocoder 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 géocodeur. Le geocoder inversé renvoie l'un de ces types comme résultat valide.

  • Le champ plusCode, de type PlusCode, contient le Plus Code qui correspond le mieux à la latitude et à 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 demande est inférieure à 10 mètres.

L'objet JSON complet se présente sous la forme suivante :

{
  "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 indiquant l'adresse lisible la plus proche que vous souhaitez obtenir.

Paramètres facultatifs

  • languageCode

    Langue dans laquelle renvoyer les résultats.

    • Consultez la liste des langues disponibles. Google met souvent à jour les langues acceptées. Cette liste n'est donc pas exhaustive.
    • Si languageCode n'est pas fourni, l'API utilise en par défaut. Si vous spécifiez un code de langue non valide, l'API renvoie une erreur INVALID_ARGUMENT.
    • L'API met tout en œuvre pour fournir une adresse postale lisible à la fois pour l'utilisateur et les habitants. Pour atteindre cet objectif, il 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 de préférence. Les composants d'adresse sont tous renvoyés dans la même langue, qui est choisie à partir du premier composant.
    • Si un nom n'est pas disponible dans la langue de votre choix, l'API utilise la correspondance la plus proche.
    • La langue préférée a une faible influence sur l'ensemble des résultats que l'API choisit de renvoyer et sur l'ordre dans lequel ils sont renvoyés. Le géocoder 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 forme de valeur 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 les résultats du service pour la région spécifiée, mais sans les limiter totalement. Lors du geocoding d'un lieu ou d'un endroit (geocoding inversé ou 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 loi applicable.

  • précision

    Une ou plusieurs précisions géographiques, 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 granularités.

    Le paramètre granularity ne limite pas la recherche aux niveaux de précision géographique spécifiés. Au lieu de cela, granularity agit comme un filtre post-recherche. L'API récupère 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/v4beta/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. 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 au(x) type(s) d'adresse spécifié(s). Au lieu de cela, 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 au ou aux types d'adresses 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/v4beta/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

    Les valeurs suivantes sont acceptées :

    Types d'adresses et de composants d'adresse

    Le tableau types dans le corps GeocodeResult de la réponse indique le type d'adresse. Les types d'adresses incluent une adresse postale, un pays ou une entité politique. Le tableau types dans le champ AddressComponents du corps GeocodeResult indique le type de chaque partie de l'adresse. (un numéro de rue ou un pays, par exemple).

    Les adresses peuvent avoir plusieurs types. Les types peuvent être considérés comme des "tags". Par exemple, de nombreuses villes sont taguées avec les types political et locality.

    Les types suivants sont acceptés et renvoyés dans les tableaux de types d'adresse et de types de composants d'adresse :

    Type d'adresse Description
    street_address Adresse postale précise.
    route Route nommée (par exemple, "US 101").
    intersection Intersection majeure, généralement sur deux routes principales.
    political Une entité politique Habituellement, ce type indique un polygone de certaines administrations civiles.
    country Entité politique nationale, généralement le type de premier ordre renvoyé par le Geocoder.
    administrative_area_level_1 Entité civile de premier ordre en dessous du niveau du pays. Aux États-Unis, ces niveaux administratifs correspondent aux États. Toutes les nations ne possèdent pas ces niveaux administratifs. Dans la plupart des cas, les noms courts administrative_area_level_1 correspondront fidèlement aux subdivisions ISO 3166-2 et aux autres listes largement diffusées. Cependant, cela n'est pas systématique, car nos résultats de géocodage se basent sur divers signaux et données de localisation.
    administrative_area_level_2 Entité civile de deuxième ordre en dessous du niveau du pays. Aux États-Unis, ces niveaux administratifs correspondent aux comtés. Toutes les nations ne possèdent pas ces niveaux administratifs.
    administrative_area_level_3 Entité civile de troisième ordre en dessous du niveau du pays. Ce type indique une division civile mineure. Toutes les nations ne possèdent pas ces niveaux administratifs.
    administrative_area_level_4 Entité civile de quatrième ordre en dessous du niveau du pays. Ce type indique une division civile mineure. Toutes les nations ne possèdent pas ces niveaux administratifs.
    administrative_area_level_5 Entité civile de cinquième ordre en dessous du niveau du pays. Ce type indique une division civile mineure. Toutes les nations ne possèdent pas ces niveaux administratifs.
    administrative_area_level_6 Entité civile de sixième ordre en dessous du niveau du pays. Ce type indique une division civile mineure. Toutes les nations ne possèdent pas ces niveaux administratifs.
    administrative_area_level_7 Entité civile de septième ordre en dessous du niveau du pays. Ce type indique une division civile mineure. Toutes les nations ne possèdent pas ces niveaux administratifs.
    colloquial_area Autre nom couramment utilisé pour l'entité.
    locality Entité politique de ville ou de municipalité incorporée.
    sublocality Entité civile de premier ordre située en dessous d'une localité. Pour certains établissements, vous pouvez recevoir l'un des types supplémentaires suivants : de sublocality_level_1 à sublocality_level_5. Chaque niveau de sous-localité correspond à une entité civile. Plus le nombre est élevé, plus la zone géographique est petite.
    neighborhood Quartier nommé.
    premise Lieu nommé, généralement un bâtiment ou un ensemble de bâtiments ayant un nom commun.
    subpremise Entité adressable en dessous du niveau de l'établissement, comme un appartement, une unité ou une suite.
    plus_code Référence de lieu encodée, déterminée par la latitude et la longitude. Vous pouvez utiliser des Plus Codes pour remplacer les adresses postales dans les endroits où elles n'existent pas (où les bâtiments ne sont pas numérotés ni nommés). Pour en savoir plus, consultez https://plus.codes.
    postal_code Code postal, utilisé pour adresser le courrier postal dans le pays.
    natural_feature Un élément géographique naturel important.
    airport Un aéroport.
    park Parc nommé.
    point_of_interest Point d'intérêt nommé. En général, ces "POI" sont des entités locales importantes qui ne correspondent à aucune autre catégorie, comme "Empire State Building" ou "Tour Eiffel".

    Une liste de types vide indique qu'il n'y a aucun type connu pour un composant d'adresse particulier (par exemple, un Lieu-dit en France).