Requête et réponse de geocoding

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Demande

Une requête API Geocoding prend la forme suivante:

https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

outputFormat peut être l'une des valeurs suivantes:

  • json (recommandé) indique que la réponse est au format JSON (JavaScript Object Notation) ; ou
  • xml indique une sortie en XML.

HTTPS est requis pour les requêtes qui utilisent une clé API.

Certains paramètres sont obligatoires, tandis que d'autres sont facultatifs. Comme pour les URL, les paramètres sont séparés par une esperluette (&).

Le reste de cette page décrit séparément le geocoding et le geocoding inversé, car des paramètres différents sont disponibles pour chaque type de requête.

Paramètres de geocoding (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 les noms d'entreprise et les numéros d'étage, d'appartement ou de bureau, doivent être évités. Les éléments d'adresse postale doivent être délimités par des espaces (affichés ici sous la forme d'URL avec %20) :
    address=24%20Sussex%20Drive%20Ottawa%20ON
    . Mettez en forme les codes plus tels qu'ils apparaissent ici (les signes plus sont échappés avec une URL en %2B et les espaces sont échappés en URL vers %20) :
    • Le code global est un indicatif de zone de 4 caractères et un indicatif local à 6 caractères ou plus (849VCWC8+R9 correspond à 849VCWC8%2BR9).
    • Le code composé est un code local à six caractères ou plus associé à un emplacement explicite (CWC8+R9 Mountain View, CA, États-Unis correspond à CWC8%2BR9%20Mountain%20View%20CA%20USA).

    --OR--
    components : filtre de composants dont les éléments sont séparés par une barre verticale (|). Le filtre de composants est également accepté en tant que paramètre facultatif si une valeur address est fournie. Chaque élément du filtre des composants est constitué d'une paire component:value et limite complètement les résultats du geocoder. Vous trouverez plus d'informations sur le filtrage des composants ci-dessous.
  • 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.

Paramètres facultatifs dans une requête de geocoding :

  • bounds : cadre de délimitation de la fenêtre d'affichage dans laquelle pondérer les résultats du géocodage de manière plus proéminente. Ce paramètre n'influera que sur les résultats du geocoder. (Pour en savoir plus, consultez la section Pondération de la fenêtre d'affichage ci-dessous.)
  • language : langue dans laquelle les résultats sont renvoyés.
    • Consultez la liste des langues acceptées. Cette liste n'est pas exhaustive, car Google met souvent à jour les langues acceptées.
    • Si language n'est pas fourni, le geocoder tente d'utiliser la langue préférée spécifiée dans l'en-tête Accept-Language, ou la langue native du domaine à partir duquel la requête est envoyée.
    • Le geocoder s'efforce de fournir une adresse postale lisible aussi bien par l'utilisateur que par les locaux. Pour atteindre cet objectif, elle renvoie des adresses postales dans la langue locale, transcrites dans un script lisible par l'utilisateur si nécessaire, en observant 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 préférée, le geocoder utilise la correspondance la plus proche.
    • Le langage préféré a une petite influence sur l'ensemble de résultats que l'API choisit de renvoyer et l'ordre dans lequel elles sont renvoyées. Le geocoder interprète les abréviations différemment en fonction de la langue, comme les abréviations pour les types de rues, ou les synonymes qui peuvent être valides dans une langue, mais pas dans une autre. Par exemple, utca et tér sont des synonymes de rue et de carré en hongrois.
  • region : code de région, indiqué sous forme de valeur ccTLD (« domaine de premier niveau ») à deux caractères. Ce paramètre n'influera que sur les résultats du geocoder. (Pour en savoir plus, consultez la section Limiter les résultats à une région ci-dessous.)
  • components : filtre de composants avec des éléments séparés par une barre verticale (|). Le filtre des composants est obligatoire si la requête n'inclut pas de address. Chaque élément du filtre des composants est constitué d'une paire component:value et limite complètement les résultats du geocoder. Vous trouverez plus d'informations sur le filtrage des composants ci-dessous.

Réponses

Les réponses au geocoding sont renvoyées au format indiqué par l'option output dans le chemin de la requête d'URL.

Dans cet exemple, l'API Geocoding demande une réponse json pour une requête sur l'ID de lieu "ChIJeRpOeF67j4AR9ydy_PIzPuM", qui correspond à l'identifiant de lieu du bâtiment 1600 Amphitheatre Parkway, Mountain View, CA.

Cette requête illustre l'utilisation de l'option JSON output:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

Cette requête illustre l'utilisation de l'option XML output:

https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

Sélectionnez les onglets ci-dessous pour voir les 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"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4224428,
                    "lng": -122.0842467
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4239627802915,
                        "lng": -122.0829089197085
                    },
                    "southwest": {
                        "lat": 37.4212648197085,
                        "lng": -122.0856068802915
                    }
                }
            },
            "place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
            "plus_code": {
                "compound_code": "CWC8+X8 Mountain View, CA",
                "global_code": "849VCWC8+X8"
            },
            "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. Consultez la section Codes d'état ci-dessous.
  • "results" contient un tableau d'adresses et de données géométriques géocodées.

En règle générale, une seule entrée du tableau "results" est renvoyée pour les recherches d'adresses. Toutefois,le geocoder peut renvoyer plusieurs résultats lorsque les requêtes d'adresse 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 est constituée d'un seul élément <GeocodeResponse> et de deux éléments de premier niveau:

  • <status> contient des métadonnées sur la requête. Consultez la section Codes d'état ci-dessous.
  • Zéro, un ou plusieurs éléments <result>, chacun contenant un ensemble unique d'informations d'adresse géocodées et d'informations géométriques.

La réponse XML est considérablement plus longue que la réponse JSON. Pour cette raison, nous vous recommandons d'utiliser json comme option de sortie préférée, sauf si votre service nécessite xml pour une raison quelconque. De plus, le traitement des arborescences XML nécessite une certaine attention afin que vous puissiez faire référence aux nœuds et aux éléments appropriés. Consultez la page Analyser du code XML avec XPath pour obtenir des modèles de conception recommandés pour le traitement des résultats.

  • Les résultats XML sont encapsulés dans un élément <GeocodeResponse> racine.
  • JSON désigne des entrées comportant plusieurs éléments par des tableaux au pluriel (types), tandis que XML les indique à l'aide de plusieurs éléments singuliers (<type>).
  • Les éléments vides sont indiqués par des tableaux vides au format JSON, mais par l'absence de ces éléments en XML. Une réponse qui ne génère aucun résultat renvoie un tableau results vide 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 geocoding ne fonctionne pas. Le champ "status" peut contenir les valeurs suivantes:

  • "OK" indique qu'aucune erreur ne s'est produite. L'adresse a bien été analysée et au moins un géocode 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 un address inexistant.
  • OVER_DAILY_LIMIT indique l'un des éléments suivants :
    • La clé API est manquante ou incorrecte.
    • La facturation n'a pas été activée pour 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).

    Pour savoir comment résoudre ce problème, consultez les questions fréquentes sur Maps.

  • "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 ou latlng) 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 champ error_message supplémentaire dans l'objet de réponse Geocoding. Ce champ contient des informations plus détaillées sur les raisons de ce code d'état.

Résultats

Lorsque le geocoder renvoie les résultats, il les place dans un tableau results (JSON). Même si le geocoder ne renvoie aucun résultat (par exemple, si l'adresse n'existe pas), il renvoie un tableau results vide. (Les réponses XML sont composées de zéro ou plusieurs éléments <result>.)

Un résultat typique contient les champs suivants:

  • Le tableau types[] indique le type du résultat renvoyé. Ce tableau contient un ensemble de zéro ou plusieurs balises identifiant le type de caractéristique renvoyé dans le résultat. Par exemple, le géocodage de "Chicago" renvoie le terme "localité" qui indique que "Chicago" est une ville. Il renvoie également le terme "politique" qui indique qu'il s'agit d'une entité politique.
  • formatted_address est une chaîne contenant l'adresse lisible de cet établissement.

    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 distincts 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" comme long_name et "AK" comme short_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 toutes les localités contenues dans un code postal. Elle n'est présente que lorsque le résultat est un code postal contenant plusieurs localités.
  • geometry contient les informations suivantes :
    • location contient la latitude et la longitude géocodées. Pour les recherches d'adresse normales, ce champ est généralement le plus important.
    • location_type stocke des données supplémentaires sur l'établissement spécifié. Les valeurs suivantes sont actuellement acceptées:

      • "ROOFTOP" indique que le résultat renvoyé est un géocode précis pour lequel nous disposons d'informations de localisation précises, jusqu'à la précision de l'adresse postale.
      • "RANGE_INTERPOLATED" indique que le résultat renvoyé reflète une approximation (généralement sur une route) interpolée entre deux points précis (tels que des intersections). Les résultats interpolés sont généralement renvoyés lorsque les géocodes sur le toit ne sont pas disponibles pour une adresse postale.
      • "GEOMETRIC_CENTER" indique que le résultat est le centre géométrique d'un résultat, comme une polyligne (par exemple, une rue) ou un polygone (une région).
      • "APPROXIMATE" indique que le résultat renvoyé est approximatif.
    • viewport contient la fenêtre d'affichage recommandée pour l'affichage du résultat renvoyé, sous la forme de deux valeurs de latitude et de longitude définissant l'angle southwest et northeast du cadre de délimitation de la fenêtre d'affichage. En règle générale, la fenêtre d'affichage est utilisée pour encadrer un résultat lorsqu'il est proposé à un utilisateur.
    • bounds (éventuellement renvoyé) stocke le cadre de délimitation qui peut contenir complètement le résultat renvoyé. Notez que ces limites peuvent ne pas correspondre à la fenêtre d'affichage recommandée. Par exemple, San Francisco inclut les îles Farallon, qui font techniquement partie de la ville, mais ne devraient probablement pas être renvoyées dans la fenêtre d'affichage.
  • plus_code (voir Open Location Code et le code plus codes) est une référence de lieu encodée, calculée à partir des coordonnées de latitude et de longitude, qui représente une zone: 1/8000th de degré par 1/8000th de degré (environ 14m x 14m à l'équateur) ou moins. Les Plus Codes peuvent être utilisés pour remplacer des adresses postales dans des endroits où elles n'existent pas (où les bâtiments ne sont pas numérotés ni nommés).

    Les Plus Codes sont mis en forme comme un code global et un code composé :

    • global_code est un indicatif de zone de 4 caractères et un indicatif local à 6 caractères ou plus (849VCWC8+R9).
    • compound_code correspond à 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.
    En règle générale, le code global et le code composé sont renvoyés. Toutefois, si le résultat se trouve dans un emplacement distant (par exemple, un océan ou un désert), seul le code global peut être renvoyé.
  • 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 identifiant unique qui peut être utilisé avec d'autres API Google. Par exemple, vous pouvez utiliser place_id dans une requête API Places pour obtenir des informations sur un établissement local, comme son numéro de téléphone, ses horaires d'ouverture, les avis des utilisateurs, etc. Consultez la présentation des ID de lieu.

Types d'adresses et types de composants d'adresse

Le tableau types[] dans le résultat indique le type d'adresse. Il peut s'agir, par exemple, d'une adresse postale, d'un pays ou d'une entité politique. Il existe également un tableau types[] dans address_components[], indiquant le type de chaque partie de l'adresse. (un numéro de rue ou un pays, par exemple). (Vous trouverez ci-dessous la liste complète des types.) 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 le type political et le type locality.

Les types suivants sont acceptés et renvoyés par le geocoder dans les tableaux de types d'adresse et de type de composant 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 : 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 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.

En plus des éléments ci-dessus, les composants d'adresse peuvent inclure les types listés ici. 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, comme locality et sublocality, 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 et transit_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 les résultats dans une fenêtre d'affichage donnée (exprimée sous la forme d'un cadre de délimitation). Pour ce faire, vous devez définir 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'une barre verticale (|) pour séparer les coordonnées.

Par exemple, un géocode pour "Washington" renvoie généralement l'État de Washington:

Requête :

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY

Réponse :

{
   "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, l'ajout d'un argument bounds définissant un cadre de délimitation autour de la partie nord-est des États-Unis entraîne le géocodage de la ville de Washington, DC :

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

Réponse :

{
   "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 de geocoding, vous pouvez demander au service Geocoding de renvoyer des résultats pondérés vers une région particulière à l'aide du paramètre region. Ce paramètre utilise un argument ccTLD (domaine national de premier niveau) spécifiant le biais de région. La plupart des codes ccTLD sont identiques aux codes ISO 3166-1, à quelques exceptions près. Par exemple, le ccTLD du Royaume-Uni est "uk" (.co.uk) alors que son code ISO 3166-1 est "gb" (techniquement, il désigne l'entité "Royaume-Uni de Grande-Bretagne et d'Irlande du Nord").

Les résultats du geocoding peuvent être biaisés pour chaque domaine dans lequel l'application Google Maps principale est officiellement lancée. Notez que la pondération ne préfère que les résultats correspondant à un domaine spécifique. Si des résultats plus pertinents existent en dehors de ce domaine, ils peuvent être inclus.

Par exemple, un géocode pour "Toledo" renvoie ce résultat, car le domaine par défaut de 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

Réponse :

{
   "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"
}

Une requête de géocodage pour "Toledo" avec region=es (Espagne) renverra la ville espagnole.

Requête :

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key=YOUR_API_KEY

Réponse :

{
   "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 des 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 à l'aide du filtre components. Un filtre se compose d'une liste de paires component:value séparées par une barre verticale (|). Les valeurs de filtre acceptent les mêmes méthodes de correction orthographique et de correspondance partielle que les autres requêtes Geocoding. Si le geocoder trouve une correspondance partielle pour un filtre de composant, la réponse contient un champ partial_match.

Voici les components qui peuvent être filtrés:

  • postal_code correspond à postal_code et postal_code_prefix.
  • country, qui correspond à un nom de pays ou à un code pays ISO 3166-1 à deux lettres. L'API suit la norme ISO pour définir les pays, et le filtrage fonctionne mieux lorsque vous utilisez le code ISO correspondant du pays.

Les components suivantes peuvent être utilisées pour influencer les résultats, mais ne seront pas appliquées:

  • route correspond au nom long ou court d'un itinéraire.
  • locality correspond aux types locality et sublocality.
  • administrative_area correspond à tous les niveaux administrative_area.

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 évalue ces filtres comme un ET, et non un OU.
  • Les résultats correspondent à ceux de Google Maps, ce qui génère parfois des réponses ZERO_RESULTS inattendues. L'utilisation de Place Autocomplete peut offrir de meilleurs résultats dans certains cas d'utilisation. Pour en savoir plus, consultez ces questions fréquentes.
  • Pour chaque composant d'adresse, spécifiez-le dans le paramètre address ou dans un filtre components, mais pas les deux. La spécification des mêmes valeurs dans les deux peut entraîner ZERO_RESULTS.

Un géocode pour "High St, Hastings" avec components=country:GB renvoie un résultat à Hastings, en Angleterre, plutôt qu'à Hastings-On-Hudson, aux États-Unis.

Requête :

https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY

Réponse :

{
   "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"
}

Une requête de géocodage pour la localité de "Santa Cruz" avec components=country:ES renvoie Santa Cruz de Tenerife, dans les îles Canaries, en Espagne.

Requête :

https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY

Réponse :

{
   "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

Réponse :

{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

Vous pouvez envoyer des requêtes valides sans le paramètre d'adresse à l'aide du filtre components. (Lors du géocodage d'une adresse complète, le paramètre address est obligatoire si la requête contient les noms 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

Réponse :

{
   "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"
}