Service Geocoding

Remarque : Bibliothèques côté serveur
Développeurs de l'Espace économique européen (EEE)

Présentation

Le geocoding consiste à convertir des adresses (comme "1600 Amphitheatre Parkway, Mountain View, CA") en coordonnées géographiques (comme latitude 37.423021 et longitude -122.083739), que vous pouvez utiliser pour placer des repères ou positionner la carte.

Le geocoding inversé consiste à convertir des coordonnées géographiques en adresses lisibles (voir Geocoding inversé (recherche d'adresse)).

Vous pouvez également utiliser le geocoder pour trouver l'adresse correspondant à un identifiant de lieu donné.

L'API Maps JavaScript fournit une classe Geocoder pour le geocoding et le geocoding inversé de manière dynamique à partir d'une entrée utilisateur. Si vous souhaitez plutôt géocoder des adresses statiques connues, consultez le service Web Geocoding.

Premiers pas

Avant d'utiliser le service Geocoding dans l'API Maps JavaScript, assurez-vous d'abord que l'API Geocoding est activée dans la console Google Cloud, dans le même projet que celui configuré pour l'API Maps JavaScript.

Pour afficher la liste des API activées :

  1. Accédez à la console Google Cloud.
  2. Cliquez sur le bouton Sélectionner un projet, sélectionnez le projet que vous avez configuré pour l'API Maps JavaScript, puis cliquez sur Ouvrir.
  3. Dans la liste des API du tableau de bord, repérez l'API Geocoding.
  4. Si vous trouvez l'API dans la liste, vous pouvez continuer. Si l'API ne figure pas dans la liste, activez-la :
    1. En haut de la page, sélectionnez ACTIVER L'API pour afficher l'onglet Bibliothèque. Vous pouvez également sélectionner Bibliothèque dans le menu de gauche.
    2. Recherchez l'API Geocoding, puis sélectionnez-la dans la liste des résultats.
    3. Sélectionnez ACTIVER. Une fois le processus terminé, l'API Geocoding apparaît dans la liste des API du tableau de bord.

Tarifs et règles

Tarifs

Pour en savoir plus sur les tarifs et les règles d'utilisation du service JavaScript Geocoding, consultez Utilisation et facturation pour l'API Geocoding.

Règles

Vous devez utiliser le service Geocoding conformément aux Règles de l'API Geocoding.

Requêtes de geocoding

L'API Google Maps devant appeler un serveur externe, l'accès au service Geocoding est asynchrone. Pour cette raison, vous devez transmettre une méthode de rappel à exécuter à la fin de la requête. Cette méthode de rappel traite le ou les résultats. Notez que le geocoder peut renvoyer plusieurs résultats.

Vous pouvez accéder au service de geocoding de l'API Google Maps depuis votre code à l'aide de l'objet constructeur google.maps.Geocoder. La méthode Geocoder.geocode() envoie une requête au service de geocoding et lui transmet un littéral d'objet GeocoderRequest contenant les termes d'entrée et une méthode de rappel à exécuter à la réception de la réponse.

Le littéral d'objet GeocoderRequest contient les champs suivants :

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

Paramètres obligatoires : vous ne devez fournir qu'un seul des champs suivants.

  • address : adresse que vous souhaitez géocoder.
         ou
    location : LatLng (ou LatLngLiteral) pour lequel vous souhaitez obtenir l'adresse lisible la plus proche. Le geocoder effectue un geocoding inversé. Pour en savoir plus, consultez Geocoding inversé.
         ou
    placeId : ID du lieu pour lequel vous souhaitez obtenir l'adresse lisible la plus proche. Découvrez comment récupérer une adresse pour un ID de lieu.

Paramètres facultatifs :

  • bounds : LatLngBounds dans lequel pondérer les résultats du geocoding de manière plus proéminente. Le paramètre bounds ne fera qu'influer sur les résultats du geocoder, sans les limiter totalement. Vous trouverez plus d'informations sur la pondération de la fenêtre d'affichage ci-dessous.
  • componentRestrictions : permet de limiter les résultats à une zone spécifique. Vous trouverez plus d'informations sur le filtrage des composants ci-dessous.
  • region : code régional, spécifié sous forme de sous-tag de région Unicode à deux caractères (non numériques). Dans la plupart des cas, ces tags sont directement mappés avec les valeurs ccTLD ("domaine de premier niveau") à deux caractères que vous connaissez. Le paramètre region ne fera qu'influer sur les résultats du geocoder, sans les limiter totalement. Vous trouverez plus d'informations sur la pondération du code régional ci-dessous.
  • extraComputations : la seule valeur autorisée pour ce paramètre est ADDRESS_DESCRIPTORS. Pour en savoir plus, consultez Descripteurs d'adresse.
  • fulfillOnZeroResults : respectez la promesse d'un état ZERO_RESULT dans la réponse. Cela peut être souhaitable, car même avec zéro résultat de géocodage, des champs supplémentaires au niveau de la réponse peuvent toujours être renvoyés. Pour en savoir plus, consultez Fulfill on Zero Results.

Réponses aux requêtes de geocoding

Le service Geocoding nécessite une méthode de rappel à exécuter lors de la récupération des résultats du geocoder. Ce rappel doit transmettre deux paramètres pour contenir le results et un code status, dans cet ordre.

Résultats du geocoding

L'objet GeocoderResult représente un seul résultat de geocoding. Une requête de geocoding peut renvoyer plusieurs objets de résultat :

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

Ces champs sont décrits ci-dessous :

  • types[] est un tableau indiquant le type d'adresse du résultat renvoyé. Ce tableau contient un ensemble de zéro, une ou plusieurs balises identifiant le type de caractéristique renvoyé dans le résultat. Par exemple, le geocoding de "Chicago" renvoie le terme "Localité", ce qui signifie que "Chicago" est une ville. Il renvoie également le terme "politique", qui indique qu'il s'agit d'une entité politique. Pour en savoir plus, consultez la section Types d'adresses et de composants d'adresse ci-dessous.
  • 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 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 en savoir plus, consultez la section Types d'adresses et de composants d'adresse ci-dessous.

  • 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 l'identifiant unique d'un lieu, qui peut être utilisé avec d'autres API Google. Par exemple, vous pouvez utiliser place_id avec la bibliothèque de l'API Google 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.
  • postcode_localities[] est un tableau indiquant toutes les localités contenues dans un code postal. Il ne s'affiche que lorsque le résultat est un code postal contenant plusieurs localités.

  • geometry contient les informations suivantes :

    • location contient la valeur latitude,longitude géocodée. Notez que nous renvoyons cet emplacement en tant qu'objet LatLng, et non en tant que chaîne formatée.
    • location_type stocke des données supplémentaires sur l'emplacement spécifié. Les valeurs suivantes sont acceptées :
      • ROOFTOP indique que le résultat renvoyé reflète un geocode précis.
      • 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 (des intersections, par exemple). Les résultats interpolés sont généralement renvoyés lorsque le geocoding rooftop est indisponible pour une adresse postale.
      • GEOMETRIC_CENTER indique que la réponse renvoyée 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 stocke la fenêtre d'affichage recommandée pour le résultat renvoyé.
    • bounds (facultatif) stocke LatLngBounds, qui peut contenir le résultat renvoyé dans son ensemble. 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. Toutefois, elles ne doivent pas être renvoyées dans la fenêtre d'affichage.

Les adresses sont renvoyées par le geocoder en utilisant le paramètre de langue préférée du navigateur ou la langue spécifiée lors du chargement du code JavaScript de l'API à l'aide du paramètre language. Pour en savoir plus, consultez Localisation.

Types d'adresses et de composants d'adresse

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

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

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

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

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

En plus des types énumérés ci-dessus, les composants d'adresse peuvent contenir les types suivants.

Remarque : cette liste n'est pas exhaustive et est sujette à modification.

En plus des types énumérés ci-dessus, les composants d'adresse peuvent contenir les types suivants.

Type de composant d'adresse Description
floor Étage d'une adresse d'immeuble.
establishment Il s'agit généralement d'un lieu qui n'a pas encore été classé.
landmark Lieu à proximité qui sert de référence pour faciliter la navigation.
point_of_interest Point d'intérêt nommé.
parking Un parking ou un espace de stationnement.
post_box Boîte postale spécifique.
postal_town Groupe de zones géographiques, comme locality et sublocality, utilisé pour les adresses postales dans certains pays.
room Salle associée à l'adresse d'un bâtiment.
street_number Numéro de rue précis.
bus_station, train_station et transit_station Emplacement d'un arrêt de bus, de train ou de transports en commun.

Codes d'état

Le code status peut renvoyer l'une des 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 un address inexistant.
  • "OVER_QUERY_LIMIT" indique que vous avez dépassé votre quota.
  • "REQUEST_DENIED" indique que votre requête a été rejetée. La page Web n'est pas autorisée à utiliser le geocoder.
  • "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.
  • "ERROR" indique que la requête a expiré ou qu'un problème est survenu lors de la communication avec les serveurs Google. Si vous essayez à nouveau, la requête pourrait aboutir.

Dans cet exemple, nous géocodons une adresse et plaçons un repère aux valeurs de latitude et de longitude renvoyées. Notez que le handler est transmis en tant que littéral de fonction anonyme.

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

Voir un exemple

Limiter les résultats à une fenêtre d'affichage

Vous pouvez également 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). Pour ce faire, définissez le paramètre bounds dans le littéral d'objet GeocoderRequest afin d'établir les limites de cette fenêtre d'affichage. Notez que la pondération ne fait que privilégier les résultats compris dans les limites. Si des résultats plus pertinents existent en dehors de ces limites, ils peuvent être inclus.

Par exemple, un geocode pour "Winnetka" renvoie généralement cette banlieue de Chicago :

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

Toutefois, si vous spécifiez un paramètre bounds définissant un cadre de délimitation pour la vallée de San Fernando à Los Angeles, le geocoding renvoie le quartier nommé "Winnetka" de ce lieu :

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "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"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

Limiter les résultats à un code régional

Vous pouvez définir explicitement le service Geocoding pour qu'il renvoie des résultats pondérés en faveur d'une région en particulier à l'aide du paramètre region. Ce paramètre prend un code régional, spécifié comme sous-tag de région à deux caractères (non numériques) Unicode. Ces tags sont directement mappés avec les valeurs ccTLD ("domaine de premier niveau") à deux caractères que vous connaissez, comme "uk" dans "co.uk". Dans certains cas, le tag region est aussi compatible avec les codes ISO-3166-1, qui diffèrent parfois des valeurs ccTLD ("GB" pour "Grande-Bretagne", par exemple).

Lorsque vous utilisez le paramètre region :

  • Ne spécifiez qu'un seul pays ou qu'une seule région. Les valeurs multiples sont ignorées et peuvent entraîner l'échec de la requête.
  • N'utilisez que des sous-tags de région à deux caractères (format CLDR Unicode). Toutes les autres entrées entraîneront des erreurs.
  • Seuls les pays et régions listés dans les Détails de la couverture Google Maps Platform sont acceptés.

Des requêtes de geocoding peuvent être envoyées pour chaque domaine dans lequel l'application Google Maps propose le geocoding. Notez que la pondération ne fait que privilégier les résultats d'un domaine spécifique. Si des résultats plus pertinents existent en dehors de ce domaine, ils peuvent être inclus.

Par exemple, un geocode pour "Toledo" renvoie le résultat suivant, car le domaine par défaut du service Geocoding est défini sur les États-Unis :

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

Un geocode pour "Toledo" avec le champ region défini sur 'es' (Espagne) affichera la ville espagnole :

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "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":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

Filtrer par composants

Vous pouvez configurer le service Geocoding pour qu'il renvoie les résultats d'adresse limités à une zone spécifique en utilisant un filtre de composants. Spécifiez le filtre dans le paramètre componentRestrictions. Les valeurs de filtre sont compatibles avec les mêmes méthodes de correction orthographique et de correspondance partielle que les autres requêtes de geocoding.

Le geocoder ne renvoie que les résultats qui correspondent à tous les filtres des composants. Autrement dit, il évalue les spécifications de filtre comme un opérateur ET, et non comme un opérateur OU.

Un filtre de composants comprend un ou plusieurs des éléments suivants :

  • route, qui correspond au nom long ou court d'une route.
  • locality, qui correspond à la fois au type de localité et de sous-localité.
  • administrativeArea, qui correspond à tous les niveaux de la région administrative.
  • postalCode, qui correspond aux codes postaux et aux préfixes de codes postaux.
  • country, qui correspond à un nom de pays ou à un code pays ISO 3166-1 à deux lettres. Remarque : L'API respecte la norme ISO pour la définition des pays. Le filtrage fonctionne mieux lorsque vous utilisez le code ISO correspondant du pays.

L'exemple suivant illustre l'utilisation du paramètre componentRestrictions pour filtrer par country et postalCode :

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

Exécuter une commande sans résultat

Pour le géocodage inversé, la promesse est rompue par défaut sur status=ZERO_RESULTS. Toutefois, les champs de niveau de réponse supplémentaires plus_code et address_descriptor peuvent toujours être renseignés dans ce cas. Si la valeur "true" est fournie pour le paramètre fulfillOnZeroResults, renseigné dans ce cas. Si la valeur "true" est fournie pour le paramètre fulfillOnZeroResults, la promesse n'est pas rompue et ces champs supplémentaires sont accessibles à partir de la promesse, le cas échéant.

Voici un exemple de ce comportement pour une latitude/longitude en Antarctique. Même si aucun résultat de géocodage inversé n'est disponible, nous pouvons toujours imprimer le code Plus dans la promesse si nous définissons fulfillOnZeroResults=true. 

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(-75.290330, 38.653861);
      geocoder
        .geocode({
          'location': latlng,
          'fulfillOnZeroResults': true,
        })
        .then((response) => {
          console.log(response.plus_code);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

Descripteurs d'adresse

Les descripteurs d'adresse incluent des informations supplémentaires qui aident à décrire un lieu à l'aide de points de repère et de zones. Consultez la démonstration des descripteurs d'adresse pour découvrir cette fonctionnalité.

Les descripteurs d'adresse peuvent être activés à l'aide du paramètre extraComputations. Incluez extra_computations=ADDRESS_DESCRIPTORS dans une requête de geocoding, une requête de geocoding inversé ou une requête de geocoding de lieux pour recevoir des descripteurs d'adresse dans votre réponse.

Exemple de géocodage de lieux

La requête suivante contient l'adresse d'un lieu à Delhi.

function addressDescriptorPlaceIdLookup() {
  geocoder.geocode({
  geocoder.geocode({
    'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q',
    'extraComputations': ['ADDRESS_DESCRIPTORS']
    }, function(results, status) {
    if (status == 'OK') {
      console.log(results[0].address_descriptor);
    } else {
      window.alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

Exemple de geocoding inversé

La requête suivante contient la valeur de latitude/longitude d'un lieu à Delhi.

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(28.640964,77.235875);
      geocoder
        .geocode({
          'location': latlng,
          'extraComputations': ["ADDRESS_DESCRIPTORS"],
        })
        .then((response) => {
          console.log(response.address_descriptor);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

Exemple de descripteur d'adresse

Voici un exemple de address_descriptor.

  {
    "address_descriptor" : {
       "areas" : [
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Turkman Gate"
             },
             "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs"
          },
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Chandni Chowk"
             },
             "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI"
          },
          {
             "containment" : "NEAR",
             "display_name" : {
                "language_code" : "en",
                "text" : "Katar Ganj"
             },
             "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY"
          }
       ],
       "landmarks" : [
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delite Cinema"
             },
             "straight_line_distance_meters" : 29.9306755065918,
             "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM",
             "travel_distance_meters" : 418.7794799804688,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "establishment", "movie_theater", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "YES Bank"
             },
             "straight_line_distance_meters" : 66.83731079101562,
             "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ",
             "travel_distance_meters" : 489.0340270996094,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "UCO Bank"
             },
             "straight_line_distance_meters" : 25.38849639892578,
             "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM",
             "travel_distance_meters" : 403.2246398925781,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delhi By Cycle Meeting Point"
             },
             "straight_line_distance_meters" : 44.02867126464844,
             "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM",
             "travel_distance_meters" : 97.41281890869141,
             "spatial_relationship" : "AROUND_THE_CORNER",
             "types" : [
                "establishment",
                "point_of_interest",
                "tourist_attraction",
                "travel_agency"
             ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Axis Bank Branch"
             },
             "straight_line_distance_meters" : 102.3495178222656,
             "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4",
             "travel_distance_meters" : 330.8566284179688,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          }
       ]
    }
  }

Chaque objet address_descriptor contient deux tableaux : landmarks et areas. Le tableau landmarks contient jusqu'à cinq résultats classés par pertinence en tenant compte de la proximité avec les coordonnées demandées, de la prévalence du point de repère et de sa visibilité. Chaque résultat de point de repère contient les valeurs suivantes :

  • place_id est l'ID de lieu du résultat de points de repère. Consultez la présentation des ID de lieu.
  • display_name est le nom à afficher du repère et contient language_code et text.
  • straight_line_distance_meters correspond à la distance point à point en mètres entre la coordonnée d'entrée et le résultat des points de repère.
  • travel_distance_meters correspond à la distance en mètres parcourue sur le réseau routier (en ignorant les restrictions routières) entre la coordonnée saisie et le résultat des points de repère.
  • spatial_relationship correspond à la relation estimée entre la coordonnée d'entrée et le résultat des points de repère :
    • "NEAR" est la relation par défaut lorsqu'aucune des conditions suivantes ne s'applique.
    • "WITHIN" lorsque la coordonnée d'entrée est contenue dans les limites de la structure associée au repère.
    • "BESIDE" lorsque la coordonnée saisie est directement adjacente au point de repère ou à son point d'accès.
    • "ACROSS_THE_ROAD" lorsque la coordonnée d'entrée est directement opposée au repère de l'autre côté de l'itinéraire.
    • "DOWN_THE_ROAD" lorsque la coordonnée d'entrée se trouve sur le même itinéraire que le point de repère, mais pas "BESIDES" ni "ACROSS_THE_ROAD".
    • "AROUND_THE_CORNER" lorsque la coordonnée d'entrée se trouve sur un itinéraire perpendiculaire au point de repère (limité à un seul virage).
    • "BEHIND" lorsque la coordonnée d'entrée est spatialement proche du point de repère, mais éloignée de son point d'accès.
  • types correspond aux types de lieux du point de repère.

L'objet areas contient jusqu'à trois réponses et se limite aux lieux qui représentent de petites régions, comme les quartiers, les sous-localités et les grands complexes. Les zones contenant les coordonnées demandées sont listées en premier et classées de la plus petite à la plus grande. Chaque résultat areas contient les valeurs suivantes :

  • place_id est l'ID de lieu du résultat des zones. Consultez la présentation des ID de lieu.
  • display_name est le nom à afficher de la zone et contient language_code et text.
  • containment correspond à la relation de couverture estimée entre la coordonnée d'entrée et les résultats des zones :
    • "NEAR" est la relation par défaut lorsqu'aucune des conditions suivantes ne s'applique.
    • "WITHIN" lorsque la coordonnée d'entrée est proche du centre de la zone.
    • "OUTSKIRTS" lorsque la coordonnée d'entrée est proche du bord de la zone.

Couverture des descripteurs d'adresse

Les descripteurs d'adresse sont disponibles en version GA pour l'Inde. L'utilisation de descripteurs d'adresse en Inde n'entraîne aucun coût supplémentaire et est couverte par le SKU Essentials de géocodage (Inde) existant.

Commentaires

Cette fonctionnalité est disponible dans toutes les régions. Elle est en disponibilité générale pour l'Inde et en phase de lancement expérimental avant disponibilité générale pour toutes les autres régions. Nous aimerions avoir votre avis :

Geocoding inversé (recherche d'adresse)

Le terme geocoding désigne généralement la traduction d'une adresse lisible en un emplacement sur une carte. Le processus inverse, c'est-à-dire la conversion d'un emplacement sur la carte en une adresse lisible, est appelé geocoding inversé.

Au lieu de spécifier une address textuelle, indiquez une paire latitude/longitude séparée par une virgule dans le paramètre location.

Dans l'exemple suivant, nous géocodons des valeurs de latitude/longitude et centrons la carte sur le point géographique ainsi défini, puis affichons une fenêtre d'informations avec l'adresse formatée :

TypeScript

let marker;

async function initMap() {
    //  Request the needed libraries.
    const [{ Map, InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] =
        await Promise.all([
            google.maps.importLibrary(
                'maps'
            ) as Promise<google.maps.MapsLibrary>,
            google.maps.importLibrary(
                'geocoding'
            ) as Promise<google.maps.GeocodingLibrary>,
            google.maps.importLibrary(
                'marker'
            ) as Promise<google.maps.MarkerLibrary>,
        ]);

    // Get the gmp-map element.
    const mapElement = document.querySelector(
        'gmp-map'
    ) as google.maps.MapElement;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng') as HTMLInputElement;

    // Get the submit button.
    const submitButton = document.getElementById('submit') as HTMLElement;

    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
    });

    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    const geocoder = new Geocoder();
    const infowindow = new InfoWindow();

    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        geocodeLatLng(geocoder, innerMap, infowindow);
    });

    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
        geocodeLatLng(geocoder, innerMap, infowindow);
    });

    // Make an initial request upon loading.
    geocodeLatLng(geocoder, innerMap, infowindow);
}

async function geocodeLatLng(
    geocoder: google.maps.Geocoder,
    map: google.maps.Map,
    infowindow: google.maps.InfoWindow
) {
    const input = (document.getElementById('latlng') as HTMLInputElement).value;
    const latlngStr = input.split(',', 2);
    const latlng = {
        lat: parseFloat(latlngStr[0]),
        lng: parseFloat(latlngStr[1]),
    };

    geocoder
        .geocode({ location: latlng })
        .then((response) => {
            if (response.results[0]) {
                marker.position = latlng;
                map.setCenter(latlng);
                infowindow.setContent(response.results[0].formatted_address);
                infowindow.open(map, marker);
            } else {
                window.alert('No results found');
            }
        })
        .catch((e) => window.alert('Geocoder failed due to: ' + e));
}

initMap();
index.ts

JavaScript

let marker;
async function initMap() {
    //  Request the needed libraries.
    const [{ Map, InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('geocoding'),
        google.maps.importLibrary('marker'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng');
    // Get the submit button.
    const submitButton = document.getElementById('submit');
    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
    });
    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });
    const geocoder = new Geocoder();
    const infowindow = new InfoWindow();
    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Make an initial request upon loading.
    geocodeLatLng(geocoder, innerMap, infowindow);
}
async function geocodeLatLng(geocoder, map, infowindow) {
    const input = document.getElementById('latlng').value;
    const latlngStr = input.split(',', 2);
    const latlng = {
        lat: parseFloat(latlngStr[0]),
        lng: parseFloat(latlngStr[1]),
    };
    geocoder
        .geocode({ location: latlng })
        .then((response) => {
        if (response.results[0]) {
            marker.position = latlng;
            map.setCenter(latlng);
            infowindow.setContent(response.results[0].formatted_address);
            infowindow.open(map, marker);
        }
        else {
            window.alert('No results found');
        }
    })
        .catch((e) => window.alert('Geocoder failed due to: ' + e));
}
initMap();
index.js
Voir l'exemple

Essayer l'exemple

Notez que dans l'exemple précédent, nous avons montré le premier résultat en sélectionnant results[0]. Notez que le geocoding inversé renvoie souvent plusieurs résultats. Les adresses géocodées ne correspondent pas uniquement à des adresses postales, mais également à toutes les possibilités de nommer géographiquement un lieu. Par exemple, lors du geocoding d'un point dans la ville de Chicago, le point géocodé peut être indiqué sous la forme d'une adresse postale, d'une ville (Chicago), d'un État (Illinois) ou d'un pays (États-Unis). Toutes ces désignations sont des adresses pour le geocoder. Le geocoding inversé renvoie tous ces résultats.

Le geocoding inversé fait correspondre les entités politiques (pays, provinces, villes et quartiers), les adresses postales et les codes postaux.

Voici un exemple de liste d'adresses que la requête ci-dessus peut renvoyer : 

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

Les adresses sont renvoyées par ordre décroissant de correspondance. En règle générale, l'adresse la plus précise est le résultat le plus mis en avant, comme le montre notre exemple. Notez que nous renvoyons différents types d'adresse, de l'adresse postale la plus précise aux entités politiques les moins précises comme les quartiers, les villes, les départements, les États, etc. Si vous souhaitez obtenir une adresse plus générale, vous pouvez examiner le champ results[].types.

Remarque : Le geocoding inversé n'est pas une science exacte. Le geocoder tente de trouver l'adresse la plus proche avec une certaine tolérance.

Récupérer une adresse pour un ID de lieu

Renseignez un placeId pour rechercher l'adresse correspondant à un ID de lieu donné. L'identifiant de lieu est un identifiant unique qui peut être utilisé avec d'autres API Google. Par exemple, vous pouvez fournir le placeId renvoyé par l'API Roads pour obtenir l'adresse d'un point ancré. Pour en savoir plus sur les ID de lieu, consultez la présentation des ID de lieu.

Lorsque vous fournissez un placeId, la requête ne peut contenir aucun des champs suivants :

  • address
  • latLng
  • location
  • componentRestrictions

L'exemple suivant accepte un ID de lieu, trouve l'adresse correspondante et y centre la carte. Il affiche également une fenêtre d'informations indiquant l'adresse formatée du lieu correspondant :

TypeScript

// Initialize the map.
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.72, lng: -73.96 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodePlaceId(geocoder, map, infowindow);
    }
  );
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const placeId = (document.getElementById("place-id") as HTMLInputElement)
    .value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// Initialize the map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.72, lng: -73.96 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(geocoder, map, infowindow) {
  const placeId = document.getElementById("place-id").value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js
Voir l'exemple

Essayer l'exemple