Le geocoding consiste à traduire une adresse en un emplacement sur une carte. Lorsque vous géocodez une adresse, la réponse contient les éléments suivants :
- ID d'emplacement du lieu
- Coordonnées de latitude et de longitude du lieu
- Plus Code du lieu
- Détails de l'adresse étendus
Requête de geocoding
Une requête de geocode est une requête HTTP GET. Vous pouvez spécifier l'adresse sous forme de chaîne non structurée :
https://geocode.googleapis.com/v4/geocode/address/ADDRESS_STRING
Ou sous forme d'ensemble structuré de composants d'adresse représentés par des paramètres de requête :
https://geocode.googleapis.com/v4/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 mise en forme sous forme de chaîne ou de Plus Code. Le geocoding d'adresse ne résout pas les coordonnées de latitude et de longitude, ni les autres chaînes non structurées qui ne représentent pas une adresse ou un Plus Code. Les requêtes utilisant de telles chaînes ne sont pas acceptées et peuvent entraîner des réponses d'erreur ou un comportement non spécifié. Voici quelques exemples de requêtes non acceptées :
| Type de requête | Exemple |
|---|---|
| Coordonnées de latitude et de longitude. Utilisez plutôt le geocoding inversé. | "37.422131,-122.084801" |
| Trop de concepts ou de contraintes, tels que les noms de plusieurs lieux, routes ou villes dans une seule requête | "Market Street San Francisco San Jose Airport" |
| Éléments d'adresse postale non représentés sur Google Maps |
"C/O John Smith 123 Main Street" "P.O. Box 13 San Francisco" |
| Noms d'entreprises, de chaînes ou de catégories combinés à des lieux où ces entités ne sont pas disponibles | "Tesco near Dallas, Texas" |
| Requêtes ambiguës avec plusieurs interprétations | "Charger drop-off" |
| Noms historiques qui ne sont plus utilisés | "Middlesex United Kingdom" |
| Éléments ou intention non géospatiaux | "How many boats are in Ventura Harbor?" |
| Noms non officiels ou fantaisistes |
"The Jenga" "The Helter Skelter" |
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/v4/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 effectuer la requête à l'aide d'une commande curl :
curl -H "X-Goog-Api-Key: API_KEY" \ "https://geocode.googleapis.com/v4/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 tant que %2F :
https://geocode.googleapis.com/v4/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 l'URL "#" en tant que %2FE :
https://geocode.googleapis.com/v4/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 Plus Code 849VCWC8+R4. Assurez-vous d'encoder l'URL du caractère "+" en tant que %2B :
https://geocode.googleapis.com/v4/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 certains ou tous les 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/v4/geocode/address?address.postalCode=01062&key=API_KEY
Pour spécifier plusieurs composants d'adresse, par exemple pour les composants d'adresse capturés dans un formulaire HTML, utilisez plusieurs paramètres de requête :
https://geocode.googleapis.com/v4/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 une utilisation avec le geocoding direct :
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.address: à utiliser uniquement avecGeocodeAddresspour le geocoding direct.
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 lors du 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
Le geocoding renvoie un
GeocodeAddressResponse
objet qui contient le results tableau d'
GeocodeResult
objets. 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 postale ou Plus Code que vous souhaitez géocoder. Remarque : Le geocoding d'adresse ne résout pas les coordonnées de latitude et de longitude, ni les autres chaînes non structurées qui ne représentent pas une adresse ou un Plus Code. Pour en savoir plus et obtenir des exemples de requêtes non acceptées, consultez Transmettre une chaîne d'adresse non structurée. Indiquez les adresses au format utilisé par le service postal du pays concerné. Évitez d'ajouter des éléments d'adresse supplémentaires, tels que les noms d'entreprise et les numéros d'unité, de bureau ou d'étage. Les éléments d'adresse postale doivent être délimités par des espaces encodés en URL en tant que%20. Par exemple, transmettez l'adresse "24 Sussex Drive Ottawa ON" comme suit :24%20Sussex%20Drive%20Ottawa%20ON
%2Bet les espaces sont encodés en URL en tant que%20:- Un code global est un indicatif de zone de quatre caractères et un code local de six caractères ou plus. Par exemple, encodez "849VCWC8+R9" en tant que
849VCWC8%2BR9. - Un code composé est un code local de six caractères ou plus avec un
emplacement explicite. Par exemple, encodez "CWC8+R9 Mountain View, CA, USA"
en tant que
CWC8%2BR9%20Mountain%20View%20CA%20USA.
- Un code global est un indicatif de zone de quatre caractères et un code local de six caractères ou plus. Par exemple, encodez "849VCWC8+R9" en tant que
Paramètres facultatifs
locationBias
Spécifie une zone à rechercher en tant que
Viewport. Cet emplacement sert de biais, ce qui signifie que les résultats autour de l'emplacement spécifié peuvent être renvoyés, y compris les résultats proches, mais en dehors de la zone.Spécifiez la région en tant que Viewport rectangulaire. Un rectangle est une fenêtre d'affichage de latitude/longitude, représentée par deux points bas et hauts opposés en diagonale. 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 point unique. - Si
low.longitude>high.longitude, la plage de longitude est inversée (la fenêtre d'affichage croise la ligne de longitude de 180 degrés). - Si
low.longitude= -180 degrés ethigh.longitude= 180 degrés, la fenêtre d'affichage inclut toutes les longitudes. - Si
low.longitude= 180 degrés ethigh.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 zone représentée ne peut pas être vide. Une fenêtre d'affichage 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 - Si
languageCode
Langue dans laquelle renvoyer les résultats.
- Consultez la liste des langues acceptées. Google met souvent à jour les langues acceptées. Cette liste n'est donc pas exhaustive.
-
Si
languageCoden'est pas fourni, l'API utiliseenpar défaut. Si vous spécifiez un code de langue non valide, l'API renvoie uneINVALID_ARGUMENTerreur. - L'API fait de son mieux pour fournir une adresse postale lisible pour l'utilisateur et 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. Tous 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 préférée, 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éocodeur 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 de 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 geocoding d'une adresse, geocoding direct, ce paramètre peut influencer, mais pas limiter totalement, les résultats du service à la région spécifiée. Lors du geocoding d'un lieu ou d'un établissement, 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.
-
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
$fieldsoufields, ou à l'aide de l'en-tête HTTPX-Goog-FieldMask. Par exemple, la requête ci-dessous ne renverra que le champplaceIDde 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/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
{ "results": [ { "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc" } ] }
Pour en savoir plus, consultez Choisir les champs à renvoyer.
Pondération de l'emplacement
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/v4/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 ne renverra que la ville de Washington, D.C.:
https://geocode.googleapis.com/v4/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 geocoding, 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 prend une
valeur de code CLDR à deux caractères spécifiant la pondération de la région. La plupart des codes CLDR sont identiques aux codes ISO 3166-1.
Il n'existe pas de valeur par défaut pour regionCode. Par exemple, un geocode pour "Toledo" renvoie des résultats pour les États-Unis et pour l'Espagne :
https://geocode.googleapis.com/v4/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 geocoding pour "Toledo" avec regionCode=es (Espagne) ne renvoie que les résultats de l'Espagne :
https://geocode.googleapis.com/v4/geocode/address/Toledo?regionCode=es&key=API_KEY