Géocoder une adresse

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

Le geocoding traduit une adresse en un emplacement sur une carte. Lorsque vous géocodez une adresse, la réponse contient les éléments suivants :

Demande de géocodage

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

https://geocode.googleapis.com/v4beta/geocode/address/ADDRESS_STRING

Ou sous la forme d'un ensemble structuré de composants d'adresse représentés par des paramètres de requête :

https://geocode.googleapis.com/v4beta/geocode/address?STRUCTURED_ADDRESS

Vous utilisez généralement le format structuré lorsque vous traitez des composants d'adresse 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 et le masque de champ, dans les en-têtes dans le cadre de la requête GET.

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

Une adresse non structurée est une adresse formatée sous forme de chaîne ou de code Plus. Par exemple, l'exemple suivant transmet la chaîne d'adresse encodée en URL "1600 Amphitheatre Parkway, Mountain View, CA" :

https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY

Notez que le caractère "+" de l'URL est converti en espace.

Vous pouvez également envoyer la requête à l'aide d'une commande curl :

curl -H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

Les adresses peuvent contenir de nombreux types de caractères spéciaux. Par exemple, un "/" comme dans "7/1 King St, Concord West". Encodez l'URL en remplaçant "/" par %2F :

https://geocode.googleapis.com/v4beta/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

Un autre exemple courant est le caractère "#", comme dans "9500 W Bryn Mawr Ave #650, Rosemont". Encodez le caractère "#" en tant que %2FE dans l'URL :

https://geocode.googleapis.com/v4beta/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

Dans l'exemple suivant, vous spécifiez une chaîne d'adresse non structurée comme code Plus 849VCWC8+R4. Assurez-vous d'encoder le caractère "+" au format URL en le remplaçant par %2B :

https://geocode.googleapis.com/v4beta/geocode/address/849VCWC8%2BR4?key=API_KEY

Transmettre une adresse structurée

Spécifiez une adresse structurée à l'aide du paramètre de requête address, de type PostalAddress. L'objet PostalAddress vous permet de spécifier tout ou partie des composants d'adresse dans la requête en tant que paramètres de requête individuels.

Par exemple, pour spécifier uniquement le code postal de l'adresse, utilisez PostalAddress.postalCode :

https://geocode.googleapis.com/v4beta/geocode/address?address.postalCode=01062&key=API_KEY

Pour spécifier plusieurs composants d'adresse, par exemple des composants d'adresse capturés dans un formulaire HTML, utilisez plusieurs paramètres de requête :

https://geocode.googleapis.com/v4beta/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View&address.administrativeArea=CA&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 champs d'application suivants pour l'utilisation du géocodage direct :

  • 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.address — À utiliser uniquement avec GeocodeAddress pour le géocodage direct.

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 géocodage

Le géocodage renvoie un objet GeocodeAddressResponse qui contient le tableau results d'objets GeocodeResult. Chaque objet GeocodeResult représente un seul lieu.

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

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "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"
        },
        ...
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCWC8+R4",
        "compoundCode": "CWC8+R4 Mountain View, CA, USA"
      }
    }
  ]
}

Paramètres obligatoires

  • address : adresse ou Plus Code que vous souhaitez géocoder. Indiquez les adresses au format utilisé par le service postal du pays concerné. Évitez d'ajouter des éléments d'adresse supplémentaires, comme le nom de l'entreprise, ou les numéros d'unité, de bureau ou d'étage. Les éléments d'adresse postale doivent être délimités par des espaces et encodés au format URL en %20. Par exemple, transmettez l'adresse "24 Sussex Drive Ottawa ON" comme suit : 
    24%20Sussex%20Drive%20Ottawa%20ON
     Mettez en forme les Plus Codes comme indiqué ci-dessous. Les signes plus sont encodés au format URL en %2B et les espaces en %20 :
    • Un code global est un indicatif de zone de 4 caractères et un code local à 6 caractères ou plus. Par exemple, encodez "849VCWC8+R9" en 849VCWC8%2BR9.
    • Un code composé est un code local à six caractères ou plus associé à un emplacement explicite. Par exemple, encodez "CWC8+R9 Mountain View, CA, États-Unis" en CWC8%2BR9%20Mountain%20View%20CA%20USA.

Paramètres facultatifs

  • locationBias

    Spécifie une zone de recherche sous la forme d'un Viewport. Cet emplacement sert de biais, ce qui signifie que des résultats autour de l'emplacement spécifié peuvent être renvoyés, y compris des résultats proches de la zone, mais en dehors.

    Spécifiez la région en tant que Viewport rectangulaire. Un rectangle est une fenêtre d'affichage de latitude et de longitude, représentée par deux points bas et haut diagonalement opposés. Le point bas marque l'angle sud-ouest du rectangle, et le point haut représente l'angle nord-est du rectangle.

    Une fenêtre d'affichage est considérée comme une région fermée, ce qui signifie qu'elle inclut sa limite. Les limites de latitude doivent être comprises entre -90 et 90 degrés inclus, et les limites de longitude doivent être comprises entre -180 et 180 degrés inclus :

    • Si low = high, la fenêtre d'affichage se compose de ce seul point.
    • Si low.longitude > high.longitude, la plage de longitude est inversée (la fenêtre d'affichage traverse la ligne de longitude de 180 degrés).
    • Si low.longitude = -180 degrés et high.longitude = 180 degrés, la fenêtre d'affichage inclut toutes les longitudes.
    • Si low.longitude = 180 degrés et high.longitude = -180 degrés, la plage de longitude est vide.
    • Si low.latitude > high.latitude, la plage de latitude est vide.

    Les valeurs basse et haute doivent être renseignées, et la boîte représentée ne peut pas être vide. Un viewport vide génère une erreur.

    Par exemple, cette chaîne de requête définit une fenêtre d'affichage qui englobe entièrement la ville de New York :

    ?locationBias.rectangle.low.latitude=40.477398&locationBias.rectangle.low.longitude=-74.259087&locationBias.rectangle.high.latitude=40.91618&locationBias.rectangle.high.longitude=-73.70018

  • 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 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 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, ainsi que sur l'ordre dans lequel ils sont renvoyés. Le géocodeur interprète les abréviations différemment selon la langue, comme 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, sans toutefois 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.

Biais de localisation

Utilisez le paramètre locationBias pour demander au service Geocoding de privilégier les résultats à l'intérieur d'une fenêtre d'affichage donnée (exprimée sous la forme d'un cadre de délimitation). Le paramètre locationBias définit les coordonnées de latitude/longitude des angles sud-ouest et nord-est de ce cadre de délimitation.

Par exemple, une requête de geocoding pour l'adresse "Washington" peut renvoyer des résultats pour Washington, D.C. et pour l'État américain de Washington :

https://geocode.googleapis.com/v4beta/geocode/address/Washington?key=API_KEY

La réponse se présente sous la forme suivante :

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "location": {
        "latitude": 38.9071923,
        "longitude": -77.0368707
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "bounds": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "formattedAddress": "Washington, DC, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "Washington",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "location": {
        "latitude": 47.7510741,
        "longitude": -120.7401386
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024945,
          "longitude": -116.91607109999998
        }
      },
      "bounds": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024442,
          "longitude": -116.91607109999998
        }
      },
      "formattedAddress": "Washington, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "WA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
      ...
      ],
      "types": [
        "administrative_area_level_1",
        "political"
      ]
    }
  ]
}

Toutefois, si vous ajoutez un paramètre locationBias définissant un cadre de délimitation autour de la partie nord-est des États-Unis, le geocoding renvoie uniquement la ville de Washington, D.C.:

https://geocode.googleapis.com/v4beta/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72&locationBias.rectangle.high.latitude=43.39&locationBias.rectangle.high.longitude=-65.90&key=API_KEY

Pondération de la région

Dans une requête de géocodage, vous pouvez demander au service Geocoding de renvoyer des résultats pondérés en faveur d'une région en particulier à l'aide du paramètre regionCode. Ce paramètre accepte une valeur code CLDR à deux caractères spécifiant le biais régional. La plupart des codes CLDR sont identiques aux codes ISO 3166-1.

regionCode n'a pas de valeur par défaut. Par exemple, un geocode pour "Toledo" renvoie des résultats pour les États-Unis et pour l'Espagne :

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?key=API_KEY

Response:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "location": {
        "latitude": 41.652805199999996,
        "longitude": -83.5378674
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "bounds": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "formattedAddress": "Toledo, OH, USA",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM",
      "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM",
      "location": {
        "latitude": 39.8628296,
        "longitude": -4.0273067
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "bounds": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "formattedAddress": "Toledo, España",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "administrative_area_level_4",
            "political"
          ],
          "languageCode": "es"
        },
        ...
      ],
      "types": [
        "administrative_area_level_4",
        "political"
      ]
    },
    ...
  ]
}

Une requête de géocodage pour "Toledo" avec regionCode=es (Espagne) ne renvoie que les résultats de l'Espagne :

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?regionCode=es&key=API_KEY