Requête
Une requête API Geocoding se présente sous la forme suivante:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
où outputFormat
peut correspondre à l'une des valeurs suivantes:
json
(recommandé) indique que le résultat est au format JSON (JavaScript Object Notation) ; ouxml
indique que la sortie est au format XML.
Veuillez indiquer le protocole HTTPS.
Certains paramètres sont obligatoires, tandis que d'autres sont facultatifs. Comme pour les URL,
sont séparés par une esperluette (&
).
Le reste de cette page décrit le geocoding et geocoding inversé séparément, car différents paramètres sont disponibles pour chaque type de requête.
Paramètres de géocodage (recherche de latitude/longitude)
Paramètres obligatoires dans une requête de geocoding:
address
: adresse postale ou Plus Code que vous souhaitez géocoder. Indiquez les adresses au format utilisé par le service postal du pays concerné. Les éléments d'adresse supplémentaires tels que le nom de l'entreprise et les numéros d'unité, de suite ou d'étage sont à éviter. Les adresses postales doivent être délimitées par des espaces (indiqué ici sous la forme d'un caractère d'échappement%20
avec une URL): Mettez en forme les plus codes comme indiqué ci-dessous (les signes plus sont échappés en fonction d'une URL enaddress=24%20Sussex%20Drive%20Ottawa%20ON
%2B
et les espaces avec une URL en%20
):- Le code global est un indicatif de zone à quatre caractères et au moins six caractères
code local (849VCWC8+R9 correspond à
849VCWC8%2BR9
). - code composé est un code local à six caractères ou plus associé à un
emplacement explicite (CWC8+R9 Mountain View, CA, États-Unis est
CWC8%2BR9%20Mountain%20View%20CA%20USA
).
--OR--
components
: filtre de composants avec des éléments séparées par une barre verticale (|
). Le filtre des composants est également accepté comme paramètre facultatif siaddress
est fourni. Chaque élément du filtre de composants est constituécomponent:value
et limite complètement les résultats du geocoder. En savoir plus sur filtrage des composants ci-dessous.- Le code global est un indicatif de zone à quatre caractères et au moins six caractères
code local (849VCWC8+R9 correspond à
key
: clé API de votre application. Cette clé identifie à votre application à des fins de gestion des quotas. Découvrez comment obtenir une clé.
Veuillez consulter les questions fréquentes pour en savoir plus pour obtenir des conseils supplémentaires.
Paramètres facultatifs dans une requête Geocoding:
bounds
: cadre de délimitation de la fenêtre d'affichage dans lequel pondérer les résultats du géocodage de manière plus proéminente. Ce paramètre d'influencer les résultats du geocoder, mais pas de les limiter totalement. (Pour plus d'informations consultez la section Pondération de la fenêtre d'affichage ci-dessous.)language
: langue dans laquelle et renvoyer des résultats.- Consultez la liste des appareils langues. Google met souvent à jour les langues acceptées. peut ne pas être exhaustive.
- Si
language
n'est pas fourni, le geocoder tente de utilisez la langue préférée spécifiée dans le l'en-têteAccept-Language
ou la langue maternelle du domaine à partir duquel la requête est envoyée. - Le géocodeur s'efforce de fournir une adresse de rue lisible à la fois pour l'utilisateur et les locaux. Pour atteindre cet objectif, renvoie des adresses postales dans la langue locale, après translittération en script lisible par l'utilisateur si nécessaire, en observant le langue. Toutes les autres adresses sont renvoyées dans la langue. Les composants de l'adresse sont tous renvoyés dans la même langue, choisie à partir du premier composant.
- Si un nom n'est pas disponible dans la langue préférée, le geocoder utilise la correspondance la plus proche.
- La langue préférée a une petite influence sur l'ensemble des résultats l'API choisit de les renvoyer, ainsi que 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 pouvant être valides dans une langue, mais pas dans une autre. Exemple : utca et tér sont des synonymes de rue et de carré, respectivement. en hongrois.
region
: code régional, spécifié sous la forme d'une valeur ccTLD (TLD pour top-level domain, domaine de premier niveau) à deux caractères. Ce paramètre ne permet sans restreindre totalement les résultats du geocoder. (Pour plus d'informations consultez la section Pondération de la région ci-dessous.) La peut également avoir une incidence sur les résultats en fonction du droit applicable.components
: filtre de composants avec des éléments séparées par une barre verticale (|
). Le filtre des composants est obligatoire si la requête n'inclut pas deaddress
. Chaque élément du filtre de composants est constituécomponent:value
et limite complètement les résultats du geocoder. En savoir plus sur filtrage des composants ci-dessous.extra_computations
: utilisez ce paramètre pour spécifier le les caractéristiques supplémentaires suivantes dans la réponse:ADDRESS_DESCRIPTORS
– Voir des descripteurs d'adresse.BUILDING_AND_ENTRANCES
– Voir les entrées et les contours des bâtiments.
extra_computations
dans la demande pour chaque fonctionnalité, Par exemple:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
Réponses
Les réponses de géocodage sont renvoyées au format indiqué par l'indicateur output
dans la requête d'URL, ou au format JSON par défaut.
Dans cet exemple, l'API Geocoding demande une réponse json
pour une requête sur l'adresse "1600 Amphitheatre Parkway, Mountain View, CA".
Cette requête illustre l'utilisation de l'indicateur JSON output
:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Cette requête illustre l'utilisation de l'indicateur XML output
:
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Sélectionnez les onglets ci-dessous pour voir des exemples de réponses JSON et XML.
JSON
{ "results": [ { "address_components": [ { "long_name": "1600", "short_name": "1600", "types": [ "street_number" ] }, { "long_name": "Amphitheatre Parkway", "short_name": "Amphitheatre Pkwy", "types": [ "route" ] }, { "long_name": "Mountain View", "short_name": "Mountain View", "types": [ "locality", "political" ] }, { "long_name": "Santa Clara County", "short_name": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ] }, { "long_name": "California", "short_name": "CA", "types": [ "administrative_area_level_1", "political" ] }, { "long_name": "United States", "short_name": "US", "types": [ "country", "political" ] }, { "long_name": "94043", "short_name": "94043", "types": [ "postal_code" ] }, { "long_name": "1351", "short_name": "1351", "types": [ "postal_code_suffix" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4222804, "lng": -122.0843428 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4237349802915, "lng": -122.083183169709 }, "southwest": { "lat": 37.4210370197085, "lng": -122.085881130292 } } }, "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8", "plus_code": { "compound_code": "CWC8+W7 Mountain View, CA", "global_code": "849VCWC8+W7" }, "types": [ "street_address" ] } ], "status": "OK" }
Notez que la réponse au format JSON contient deux éléments racine :
"status"
contient des métadonnées sur la requête. Voir Codes d'état ci-dessous."results"
contient un tableau d'informations d'adresse géocodées et des informations de géométrie.
En règle générale, une seule entrée du tableau "results"
est renvoyée pour
d'adresse, mais le geocoder peut renvoyer plusieurs résultats lorsque l'adresse
les requêtes sont ambiguës.
XML
<GeocodeResponse> <status>OK</status> <result> <type>street_address</type> <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address> <address_component> <long_name>1600</long_name> <short_name>1600</short_name> <type>street_number</type> </address_component> <address_component> <long_name>Amphitheatre Parkway</long_name> <short_name>Amphitheatre Pkwy</short_name> <type>route</type> </address_component> <address_component> <long_name>Mountain View</long_name> <short_name>Mountain View</short_name> <type>locality</type> <type>political</type> </address_component> <address_component> <long_name>Santa Clara County</long_name> <short_name>Santa Clara County</short_name> <type>administrative_area_level_2</type> <type>political</type> </address_component> <address_component> <long_name>California</long_name> <short_name>CA</short_name> <type>administrative_area_level_1</type> <type>political</type> </address_component> <address_component> <long_name>United States</long_name> <short_name>US</short_name> <type>country</type> <type>political</type> </address_component> <address_component> <long_name>94043</long_name> <short_name>94043</short_name> <type>postal_code</type> </address_component> <geometry> <location> <lat>37.4224428</lat> <lng>-122.0842467</lng> </location> <location_type>ROOFTOP</location_type> <viewport> <southwest> <lat>37.4212648</lat> <lng>-122.0856069</lng> </southwest> <northeast> <lat>37.4239628</lat> <lng>-122.0829089</lng> </northeast> </viewport> </geometry> <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id> <plus_code> <global_code>849VCWC8+X8</global_code> <compound_code>CWC8+X8 Mountain View, CA</compound_code> </plus_code> </result> </GeocodeResponse>
Notez que la réponse XML se compose d'un seul
<GeocodeResponse>
et deux éléments de niveau supérieur:
<status>
contient des métadonnées sur la requête. Consultez la section Codes d'état ci-dessous.- Éventuellement un ou plusieurs éléments
<result>
, chacun contenant un seul ensemble d'informations d'adresse géocodées et d'informations de géométrie.
La réponse XML est considérablement plus longue que la réponse JSON. Pour
Pour cette raison, nous vous recommandons d'utiliser json
indicateur de sortie, sauf si votre service nécessite xml
pour une raison quelconque.
De plus, le traitement des arbres XML nécessite une certaine attention afin de référencer les nœuds et les éléments appropriés. Consultez Analyser du code XML avec XPath pour obtenir des exemples de modèles de conception recommandés pour le traitement des sorties.
- Les résultats XML sont encapsulés dans un élément racine
<GeocodeResponse>
. - Le format JSON indique les entrées comportant plusieurs éléments à l'aide de tableaux au pluriel (
types
), tandis que le format XML les indique à l'aide de plusieurs éléments au singulier (<type>
). - Les éléments vides sont indiqués sous forme de tableaux vides au format JSON, mais par l'absence de
de ce type en XML. Une réponse qui ne génère aucun résultat renvoie une réponse vide.
Tableau
results
au format JSON, mais aucun élément<result>
en XML par exemple.
Codes d'état
Le champ "status"
de l'objet de réponse Geocoding contient l'état de la requête et peut contenir des informations de débogage pour vous aider à déterminer pourquoi le géocodage ne fonctionne pas. Le champ "status"
peut contenir les valeurs suivantes:
"OK"
indique qu'aucune erreur ne s'est produite, que l'adresse a bien été analysée et qu'au moins un geocode a été renvoyé."ZERO_RESULTS"
indique que le géocode a abouti, mais n'a renvoyé aucun résultat. Cela peut se produire si le geocoder a reçu unaddress
inexistant.OVER_DAILY_LIMIT
indique l'une des options suivantes :- La clé API est manquante ou non valide.
- La facturation n'a pas été activée dans votre compte.
- Une limite d'utilisation que vous avez définie a été dépassée.
- Le mode de paiement fourni n'est plus valide (une carte de crédit est arrivée à expiration, par exemple).
Consultez les questions fréquentes sur Maps pour en savoir plus comment résoudre ce problème.
"OVER_QUERY_LIMIT"
indique que vous avez dépassé votre quota."REQUEST_DENIED"
indique que votre requête a été rejetée."INVALID_REQUEST"
indique généralement que la requête (address
,components
oulatlng
) est manquante."UNKNOWN_ERROR"
indique que la requête n'a pas pu être traitée en raison d'une erreur de serveur. Si vous essayez à nouveau, la requête pourrait aboutir.
Messages d'erreur
Lorsque le geocoder renvoie un code d'état autre que OK
, il peut y avoir un code supplémentaire
error_message
dans l'objet de réponse Geocoding. Ce champ contient plus
des informations détaillées sur les raisons de ce code d'état.
Résultats
Lorsque le géocodeur renvoie des résultats, il les place dans un tableau results
(JSON). Même si le geocoder ne renvoie aucun résultat (si l'adresse n'existe pas, par exemple), il
renvoie un tableau results
vide. (Les réponses XML sont composées de zéro ou plus
<result>
elements.)
Un résultat type contient les champs suivants :
- Le tableau
types[]
indique le type du résultat renvoyé. Ce tableau contient un ensemble de zéro, une ou plusieurs balises identifiant le type caractéristique renvoyée dans le résultat. Par exemple, le géocode de "Chicago" retours "localité" ce qui indique que "Chicago" est une ville, et renvoie également "politique" ce qui indique qu'il s'agit d'une entité politique. Les composants peuvent avoir un type vide s'il n'existe aucun type connu pour ce composant d'adresse. L'API peut ajouter de nouvelles valeurs de type si nécessaire. Pour en savoir plus, consultez Types d'adresses et composants d'adresse. formatted_address
est une chaîne contenant l'adresse lisible de ce lieu.Bien souvent, cette adresse équivaut à l'adresse postale. Notez que certains pays, comme le Royaume-Uni, n'autorisent pas la distribution des vraies adresses postales en raison de restrictions de licence.
L'adresse formatée est composée d'un ou de plusieurs composants d'adresse logiques. Par exemple, l'adresse "111 8th Avenue, New York, NY" comprend les éléments suivants : "111" (le numéro de rue), "8th Avenue" (la route), "New York" (la ville) et "NY" (l'État américain).
N'analysez pas l'adresse formatée de manière programmatique. Utilisez plutôt les composants d'adresse individuels, que la réponse de l'API inclut en plus du champ d'adresse formaté.
address_components[]
est un tableau contenant les composants applicables à cette adresse.Chaque composant d'adresse contient généralement les champs suivants :
types[]
est un tableau indiquant le type du composant d'adresse. Consultez la liste des types compatibles.long_name
est la description complète ou le nom du composant d'adresse renvoyé par le geocoder.short_name
est un nom textuel abrégé pour le composant d'adresse, s'il est disponible. Par exemple, un composant d'adresse pour l'Alaska peut avoir "Alaska" commelong_name
et "AK" commeshort_name
, correspondant à l'abréviation postale de deux lettres.
Notez les informations suivantes concernant le tableau
address_components[]
:- Le tableau de composants d'adresse peut contenir
formatted_address
et des composants supplémentaires. - Le tableau n'inclut pas nécessairement toutes les entités politiques contenant une adresse, à l'exception de celles incluses dans
formatted_address
. Pour récupérer toutes les entités politiques contenant une adresse spécifique, vous devez utiliser le geocoding inversé, en transmettant à la requête la latitude/longitude de l'adresse en tant que paramètre. - Le format de la réponse ne sera peut-être pas le même d'une requête à l'autre. En particulier, le nombre d'
address_components
varie selon l'adresse demandée et peut changer au fil du temps pour la même adresse. Un composant peut changer de position dans le tableau. Le type du composant peut changer. Un composant particulier peut être manquant dans une réponse ultérieure.
Pour gérer le tableau de composants, vous devez analyser la réponse et sélectionner les valeurs appropriées via des expressions. Consultez le guide pour analyser une réponse.
postcode_localities[]
est un tableau indiquant jusqu'à 100 localités contenues dans un code postal. Il n'est présent que lorsque le résultat est un code postal qui contient plusieurs localités.geometry
contient les informations suivantes:location
contient les valeurs de latitude et de longitude géocodées. Normale d'adresses, ce champ est généralement le plus important.location_type
stocke des données supplémentaires sur l'emplacement spécifié. Les valeurs suivantes sont actuellement compatibles :"ROOFTOP"
indique que le résultat renvoyé est un geocode précis pour dont nous disposons d'informations de localisation jusqu'à la précision de l'adresse postale."RANGE_INTERPOLATED"
indique que le résultat renvoyé reflète approximative (généralement sur une route) interpolée entre deux points précis (des intersections, par exemple). Les résultats interpolés sont généralement renvoyés lorsque le géocode des toitures n'est pas disponible pour une rue. adresse e-mail."GEOMETRIC_CENTER"
indique que le résultat renvoyé est le centre géométrique un résultat tel qu'une polyligne (par exemple, une rue) ou un polygone (une région)."APPROXIMATE"
indique que le le résultat renvoyé est approximatif.
viewport
contient la fenêtre d'affichage recommandée pour l'affichage le résultat renvoyé, spécifié sous la forme de deux valeurs latitude,longitude définissant lesouthwest
et Anglenortheast
du cadre de délimitation de la fenêtre d'affichage. En général, la fenêtre d'affichage sert à encadrer un résultat lorsqu'il est présenté à un utilisateur.bounds
(facultatif) stocke le cadre de délimitation. qui peut contenir l'intégralité du résultat renvoyé. Notez que ces limites peuvent être différentes fenêtre d'affichage recommandée. (Par exemple, San Francisco inclut les îles Farallon, qui font techniquement partie de la ville. Toutefois, elles ne doivent probablement pas être renvoyées dans la fenêtre d'affichage.)
-
plus_code
(voir Ouvrir le code d'emplacement et les plus codes) est une valeur une référence de lieu, déterminée par les coordonnées de latitude et de longitude, qui représente une zone: 1/8 000e de degré par 1/8 000e de degré (environ 14 m x 14 m à l'équateur) ou moins. Les Plus Codes peuvent être utilisés à la place des adresses postales dans des lieux qui n'ont pas d'adresse (lorsque les bâtiments sont numérotées ou les rues ne sont pas nommées). L'API ne renvoie pas toujours des plus codes.Lorsque le service renvoie un plus code, celui-ci prend la forme d'un code global et d'un code composé:
global_code
est un indicatif de zone à 4 caractères et un indicatif local à 6 caractères ou plus (849VCWC8+R9).compound_code
est un code local à six caractères ou plus avec un emplacement explicite (CWC8+R9, Mountain View, CA, États-Unis). N'analysez pas ce contenu de manière programmatique.
-
partial_match
indique que le geocoder n'a pas renvoyé de correspondance exacte pour la requête d'origine, bien qu'il ait pu trouver une partie de l'adresse demandée. Nous vous recommandons d'examiner la requête d'origine pour vérifier qu'elle ne contient pas d'erreur de syntaxe et/ou que l'adresse est bien complète.Les correspondances partielles sont souvent renvoyées lorsque l'adresse postale n'existe pas dans la localité que vous avez indiquée dans la requête. Les correspondances partielles peuvent aussi être renvoyées lorsqu'une requête correspond à plusieurs lieux au sein de la même localité. Par exemple, "Hillpar St, Bristol, UK" renvoie une correspondance partielle pour Henry Street et Henrietta Street. Notez que si une requête comprend un composant d'adresse mal saisi, le service de geocoding peut suggérer une autre adresse. Les suggestions déclenchées de cette façon sont également signalées comme des correspondances partielles.
place_id
est un pouvant être utilisé avec d'autres API Google. Par exemple, vous pouvez utilisezplace_id
dans un Requête de l'API Places pour obtenir Informations sur un établissement local (numéro de téléphone, horaires d'ouverture, nom d'utilisateur, etc.) des avis, et plus encore. Voir l'identifiant de lieu présentation.
Types d'adresses et de composants d'adresse
Le tableau types[]
du résultat indique
type d'adresse. Exemples de types d'adresse : adresse postale, adresse postale,
un pays ou une entité politique. Il existe également un tableau types[]
dans
address_components[]
, qui indique le type de chaque partie
adresse e-mail. (un numéro de rue ou un pays, par exemple). (Vous trouverez ci-dessous la liste complète
types.) Les adresses peuvent avoir plusieurs types. Les types peuvent être considérés comme des "balises".
Par exemple, de nombreuses villes sont taguées avec le political
et le
Type locality
.
Les types suivants sont pris en charge et renvoyés par le geocoder dans les deux les tableaux de types d'adresse et de types de composants d'adresse:
street_address
indique une adresse postale précise.route
indique une route nommée (par exemple, "US 101").intersection
indique une intersection majeure, généralement sur deux routes principales.political
indique une entité politique. Généralement, ce type indique un polygone de certaines administrations civiles.country
indique l'entité politique nationale et correspond généralement au type de premier ordre renvoyé par le Geocoder.administrative_area_level_1
indique une 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 geocoding se basent sur divers signaux et données de localisation.administrative_area_level_2
indique une 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
indique une 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
indique une 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
indique une 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
indique une 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
indique une 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
indique un autre nom couramment utilisé pour l'entité.locality
indique une entité politique de ville ou de municipalité incorporée.sublocality
indique une entité civile de premier ordre en dessous d'une localité. Pour certains établissements, vous pouvez recevoir l'un des types supplémentaires suivants : desublocality_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
indique un quartier nommé.premise
indique un lieu nommé, généralement un bâtiment ou un ensemble de bâtiments ayant un nom commun.subpremise
indique une entité de premier ordre située en dessous d'un lieu nommé, généralement un bâtiment particulier au sein d'un ensemble de bâtiments ayant un nom commun.plus_code
indique une 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
indique un code postal utilisé dans les adresses de courrier postal du pays.natural_feature
indique un élément géographique naturel important.airport
indique un aéroport.park
indique un parc nommé.point_of_interest
indique un 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.
Outre les types ci-dessus, les composants d'adresse peuvent inclure les types indiqués ici. Cette liste est Cette liste n'est pas exhaustive et est susceptible d'être modifiée.
floor
indique l'étage d'une adresse d'immeuble.establishment
indique généralement un lieu qui n'a pas encore été classé.landmark
indique un lieu à proximité qui sert de référence pour faciliter la navigation.point_of_interest
indique un point d'intérêt nommé.parking
indique un parking ou un espace de stationnement.post_box
indique une boîte postale spécifique.postal_town
indique un groupe de zones géographiques, commelocality
etsublocality
, utilisées pour les adresses postales dans certains pays.room
indique une salle associée à l'adresse d'un bâtiment.street_number
indique un numéro de rue précis.bus_station
,train_station
ettransit_station
indiquent la position d'un arrêt de bus, d'une gare ferroviaire ou d'un arrêt de transports en commun.
Pondération de la fenêtre d'affichage
Dans une requête Geocoding, vous pouvez demander au service Geocoding de privilégier
dans une fenêtre d'affichage donnée (exprimée sous la forme d'un cadre de délimitation). Pour ce faire, définissez le paramètre bounds
dans l'URL de la requête.
Le paramètre bounds
définit les coordonnées de latitude/longitude.
des angles sud-ouest et nord-est de ce cadre de délimitation à l'aide d'un pipe
(|
) pour séparer les coordonnées.
Par exemple, le géocode de "Washington" renvoie généralement l'État américain Washington:
Requête :
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
Toutefois, si vous ajoutez un argument bounds
définissant un cadre de délimitation autour de la partie nord-est des États-Unis, le geocode renvoie la ville de Washington, D.C. :
Requête :
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Pondération de la région
Dans une requête Geocoding, vous pouvez demander au service Geocoding de renvoyer
résultats pondérés en fonction d'une région particulière à l'aide du region
. Ce paramètre prend un argument ccTLD (domaine de premier niveau avec code pays) spécifiant le biais régional. La plupart des codes ccTLD sont identiques aux
Codes ISO 3166-1, à quelques exceptions près. Par exemple, le Royaume-Uni
Le ccTLD du Royaume-Uni est "uk" (.co.uk
), alors que son code ISO 3166-1 est "gb"
(d'un point de vue technique pour l'entité "Royaume-Uni de
Irlande du Nord").
Les résultats de géocodage peuvent être biaisés pour chaque domaine dans lequel l'application Google Maps principale est officiellement lancée. Notez que la pondération uniquement privilégient les résultats obtenus pour un domaine spécifique ; si des résultats plus pertinents sont disponibles en dehors de ce domaine, ils peuvent être inclus.
Par exemple, le géocode de "Toledo" renvoie ce résultat. Par défaut, pour l'API Geocoding est défini sur les États-Unis. Requête :
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Requête de geocoding pour "Toledo" avec region=es
(Espagne)
de renvoyer la ville espagnole.
Requête :
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Toledo",
"short_name" : "TO",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Filtrage par composants
Dans une réponse Geocoding, l'API Geocoding peut renvoyer des résultats d'adresse limités à une zone spécifique. Vous pouvez spécifier la restriction en utilisant
le filtre components
. Un filtre consiste
en une liste de
Paires component:value
séparées par une barre verticale (|
).
Les valeurs de filtre sont compatibles avec les mêmes méthodes de correction orthographique et de correction orthographique partielle
avec les autres requêtes Geocoding. Si le geocoder trouve une correspondance partielle pour une
filtre de composant, la réponse contiendra un champ partial_match
.
Les components
qui peuvent être filtrés incluent:
postal_code
correspond àpostal_code
etpostal_code_prefix
.country
, qui correspond à un nom de pays ou à un code pays ISO 3166-1 à deux lettres. L'API est conforme à la norme ISO définir des pays. Le filtrage est plus efficace lorsque vous utilisez code ISO correspondant du pays.
Les components
suivants peuvent être utilisés pour influencer les résultats, mais ne le seront pas
appliquée:
route
, qui correspond au nom long ou court d'une route.locality
matchs contrelocality
et Typessublocality
.administrative_area
correspond à tous lesadministrative_area
niveaux.
Remarques sur le filtrage des composants :
- Ne répétez pas ces filtres de composants dans les requêtes. Sinon, l'API renverra
Invalid_request
:country
,postal_code
,route
- Si la requête contient des filtres de composants répétés, l'API les évalue les filtres sous la forme d'un opérateur ET, et non d'un opérateur OU.
- Les résultats sont cohérents avec Google Maps, ce qui génère parfois
réponses
ZERO_RESULTS
inattendues. Utiliser Place Autocomplete peut fournir de meilleurs résultats dans certains cas d'utilisation. Pour en savoir plus, consultez ce Questions fréquentes. - Pour chaque composant d'adresse, spécifiez-le dans le
address
. ou dans un filtrecomponents
, mais pas les deux. Spécifier les mêmes valeurs peuvent avoir pour résultatZERO_RESULTS
.
Géocode de "High St, Hastings" avec components=country:GB
renvoie un résultat à Hastings, en Angleterre, plutôt qu'à Hastings-On-Hudson (États-Unis).
Requête :
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
Demande de géocode pour la localité de "Santa Cruz" avec components=country:ES
renvoie Santa Cruz de Tenerife aux Îles Canaries, en Espagne.
Requête :
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "Santa Cruz de Tenerife",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Santa Cruz de Tenerife, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
},
"location" : {
"lat" : 28.4636296,
"lng" : -16.2518467
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
}
},
"place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Le filtrage des composants renvoie une réponse ZERO_RESULTS
uniquement si vous fournissez des filtres qui s'excluent mutuellement.
Requête :
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
Response:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
Vous pouvez effectuer des requêtes valides sans paramètre d'adresse à l'aide de la méthode
Filtre components
. (Lorsque vous géocodez une adresse complète,
Le paramètre address
est obligatoire si la requête contient le paramètre
le nom et le nombre de bâtiments).
Requête :
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}