Annonce:De nouveaux styles de carte de base seront bientôt disponibles dans Google Maps Platform. Cette modification des styles de cartes inclut une nouvelle palette de couleurs par défaut, des épingles modernisées et une expérience utilisateur et une usabilité améliorées. Tous les styles de cartes seront automatiquement mis à jour en mars 2025. Pour en savoir plus sur la disponibilité et la façon de s'inscrire plus tôt, consultez Nouveau style de carte pour Google Maps Platform.

Cette page a été traduite par l'API Cloud Translation.

Service Geocoding

Remarque : Bibliothèques côté serveur

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 :

Accédez à la console Google Cloud.
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.
Dans la liste des API du tableau de bord, repérez l'API Geocoding.
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

Le 16 juillet 2018, un nouveau système de paiement à l'usage est entré en vigueur pour les services Maps, Routes et Places. Pour en savoir plus sur les nouveaux tarifs et les nouvelles limites d'utilisation du service JavaScript Geocoding, consultez Utilisation et facturation pour l'API Geocoding.

Règles

Le service Geocoding doit être utilisé conformément aux Règles décrites pour 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 via 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 la section Descripteurs d'adresse.
fulfillOnZeroResults : respectez la promesse avec un état ZERO_RESULT dans la réponse. Cela peut être utile, car même si aucun résultat de géocodage n'est renvoyé, des champs supplémentaires au niveau de la réponse peuvent toujours être renvoyés. Pour en savoir plus, consultez la section Traitement en cas d'absence de résultats.

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.

Remarque: La réponse de géocodage contient également des champs plus_code et address_descriptor au niveau de la réponse, mais ceux-ci ne sont pas accessibles via le rappel. Ils doivent plutôt être accessibles via la promesse. Pour en savoir plus, consultez Traitement en cas d'absence de résultats.

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 actuellement compatibles :
  - 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 seront 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 indique le type d'adresse. Le tableau types[] peut également être renvoyé dans un GeocoderAddressComponent pour indiquer le type du composant d'adresse. Les adresses renvoyées par le geocoder peuvent avoir plusieurs types, qui 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 par le geocoder dans les types d'adresse et 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é adressable en dessous du niveau de l'établissement, comme un appartement, un logement ou une suite.
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 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.

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.

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);
  }
});
}

Traiter les commandes en l'absence de résultats

Pour le géocodage inverse, la promesse est par défaut rompue sur status=ZERO_RESULTS. Toutefois, les champs de niveau de réponse supplémentaires de plus_code et address_descriptor peuvent toujours être renseignés dans ce cas. Si la valeur "true" est fournie pour le paramètre fulfillOnZeroResults, la promesse n'est pas interrompue 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 inverse n'est renvoyé, 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 repères et de zones. Pour en savoir plus sur cette fonctionnalité, regardez la démonstration des descripteurs d'adresse.

Les descripteurs d'adresse peuvent être activés à l'aide du paramètre extraComputations. Incluez extra_computations=ADDRESS_DESCRIPTORS dans une requête de géocodage, une requête de géocodage inversé ou une requête de géocodage 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 établissement à Delhi.

function addressDescriptorPlaceIdLookup() {
  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 ordre de pertinence en tenant compte de la proximité des coordonnées demandées, de la prévalence du repère et de sa visibilité. Chaque résultat de repère contient les valeurs suivantes:

place_id est l'ID de lieu du résultat des repères. 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 entre les points en mètres entre les coordonnées d'entrée et le résultat des repères.
travel_distance_meters correspond à la distance en mètres parcourue via le réseau routier (en ignorant les restrictions routières) entre la coordonnée d'entrée et le résultat des repères.
spatial_relationship est la relation estimée entre la coordonnée d'entrée et le résultat des repères:

"NEAR" est la relation par défaut lorsque aucune des conditions suivantes ne s'applique.
"WITHIN" lorsque la coordonnée d'entrée se trouve dans les limites de la structure associée au repère.
"BESIDE" lorsque les coordonnées saisies sont directement adjacentes au repère ou au point d'accès du repère.
"ACROSS_THE_ROAD" lorsque les coordonnées d'entrée sont directement en face du repère de l'autre côté du parcours.
"DOWN_THE_ROAD" lorsque les coordonnées d'entrée se trouvent sur le même itinéraire que le repère, mais pas "BESIDES" ni "ACROSS_THE_ROAD".
"AROUND_THE_CORNER" lorsque la coordonnée d'entrée se trouve sur une route perpendiculaire à celle du repère (limitée à un seul virage).
"BEHIND" lorsque les coordonnées d'entrée sont spatialement proches du repère, mais éloignées de son point d'accès.

types correspond aux types de lieux du repère.

L'objet areas contient jusqu'à trois réponses et se limite aux lieux qui représentent de petites régions, telles que les quartiers, les sous-localités et les grands complexes. Les zones contenant la coordonnée demandée sont listées en premier et trié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 structuration estimée entre la coordonnée d'entrée et le résultat des zones:

"NEAR" est la relation par défaut lorsque 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 du descripteur d'adresse

Cette fonctionnalité n'est disponible que dans certains pays.

Il s'agit d'une fonctionnalité en version Preview. Nous vous invitons à nous faire part de vos commentaires. Veuillez nous envoyer un e-mail à l'adresse address-descriptors-feedback@google.com.

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.

Remarque : Si vous incluez le paramètre componentRestrictions dans la requête, le paramètre location est ignoré.

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

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

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

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]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        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));
}

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

JavaScript

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

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

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]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        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));
}

window.initMap = initMap;index.js

Voir l'exemple

Essayer l'exemple

JSFiddle.net Google Cloud Shell

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, 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 :