Utiliser l'API Region Lookup

Avec l'API Region Lookup, vous pouvez trouver les ID de lieu de régions, que vous pouvez utiliser pour personnaliser les polygones de limite avec un style basé sur les données. L'API Region Lookup prend en charge deux types de requêtes :

La consultation (lookup) par région identifie une région par nom de lieu, code FIPS (États et comtés des États-Unis uniquement) ou code pays ISO-3166-1.
La recherche (search) par région recherche la région qui contient un lieu spécifique indiqué par une adresse, une LatLng ou un ID de lieu.

Types de régions acceptées

Les types de régions suivants sont acceptés : country, administrative_area_level_1, administrative_area_level_2, postal_code et locality.

Installer la bibliothèque

Pour utiliser l'API Region Lookup, procédez comme suit :

Activez l'API Region Lookup dans la console.
Installez la bibliothèque Open Source : npm install @googlemaps/region-lookup

Importer des dépendances depuis la bibliothèque

La bibliothèque Open Source Region Lookup fournit un ensemble de fonctions et de typings TypeScript que vous devez importer dans votre code.

Pour les requêtes de consultation par région, importez :

import {
  lookupRegion,
  LookupRegionRequestData,
  LookupRegionResponseData,
  LookupRegionResponse,
  RegionIdentifier
} from "@googlemaps/region-lookup";

Pour les requêtes de recherche par région, importez :

import {
  searchRegion,
  RegionSearchValue,
  SearchRegionRequestData,
  SearchRegionResponse
} from "@googlemaps/region-lookup";

Requêtes de consultation par région

Une requête de consultation par région prend un nom de lieu ou un code d'identification et renvoie un ID de lieu. Pour lancer une consultation de région, appelez lookupRegion() en spécifiant un LookupRegionRequestData avec les paramètres suivants :

place ou unit_code (obligatoire) : nom de la région (place) ou unit_code du lieu. unit_code peut être soit un code FIPS (États et comtés des États-Unis uniquement), soit un code pays ISO-3166-1.
place_type (obligatoire) : valeur du type de lieu à consulter.
region_code : code pays/région ISO-3166 à deux lettres auquel le lieu doit correspondre. region_code est facultatif si place_type est COUNTRY.
language : code de langue BCP-47, tel que "en-US" ou "sr-Latn". Si aucune valeur n'est spécifiée, la valeur par défaut est "en-US".

L'exemple suivant illustre une requête de consultation pour Newark, New Jersey.

// Headers
const headers = {
  "X-Goog-Api-Key": "YOUR API KEY",
};
const data: LookupRegionRequestData = {
  identifiers: [
    {
      "place": "newark",
      "place_type": "locality",
      "region_code": "us",
      "language": "en",
    },
  ],
};
const response: LookupRegionResponse = await RegionLookup.lookupRegion({ headers, data });

Il est obligatoire d'indiquer soit place, soit unit_code. Si aucun des deux n'est spécifié, une erreur est renvoyée.

Le paramètre region_code est obligatoire, sauf si place_type est défini sur COUNTRY.

place et unit_code spécifient un lieu pour la correspondance avec l'ID de lieu. Par exemple, si place correspond à "Californie" et que place_type est ADMINISTRATIVE_AREA_LEVEL_1, l'API renvoie l'ID de lieu pour la Californie comme matched_place_id :

place_type : ADMINISTRATIVE_AREA_LEVEL_1

Résultats matched_place_id : ID de lieu pour la Californie. Tous les autres types compatibles ne renvoient aucune correspondance.

Si unit_code est "6" (code FIPS pour la Californie), place_type est ADMINISTRATIVE_AREA_LEVEL_1 et region_code est "US", l'API renvoie l'ID de lieu pour la Californie :

place_type : ADMINISTRATIVE_AREA_LEVEL_1
region_code : US

Résultats matched_place_id : ID de lieu pour la Californie. Tous les autres types compatibles ne renvoient aucune correspondance.

Si unit_code est "US", l'API renvoie les résultats suivants lorsque les place_type suivants sont spécifiés :

place_type : COUNTRY

Résultats matched_place_id : ID de lieu pour les États-Unis. Tous les autres types compatibles ne renvoient aucune correspondance.

Si aucune correspondance n'est trouvée, matched_place_id n'est pas défini.

En cas d'ambiguïté, plusieurs propositions d'ID de lieu sont renvoyées. Par exemple, si place est "Comté de Santa Clara" et que place_type est LOCALITY, l'ID de lieu du comté de Santa Clara est renvoyé en tant que candidat.

Réponse de la consultation de région

L'objet LookupRegionResponse contient un matched_place_id si un résultat a été trouvé. Si aucun résultat n'est trouvé, les ID de lieu dont le niveau de confiance est plus faible sont renvoyés en tant que propositions, avec un code d'erreur contenant des informations de débogage.

{
  "matches": [
    {
      "matchedPlaceId": "ChIJPV4oX_65j4ARVW8IJ6IJUYs"
    }
  ]
}

Requêtes de recherche par région

Pour rechercher une région contenant un lieu spécifique, appelez searchRegion en spécifiant un SearchRegionRequestData avec les paramètres suivants :

address, latlng ou place_id (obligatoire) : contient une chaîne d'adresse non structurée (latlng) ou un ID de lieu contenu dans une région (par exemple un POI, un bâtiment, etc.). Si aucun d'eux n'est spécifié, une erreur est renvoyée.
place_type (obligatoire) : valeur de type de lieu correspondant au type de région à rechercher.
region_code : code pays/région ISO-3166 à deux lettres auquel le lieu doit correspondre. region_code est obligatoire lorsque address est spécifié.
language : code de langue BCP-47, tel que "en-US" ou "sr-Latn". Si aucune valeur n'est spécifiée, la valeur par défaut est "en-US".

L'exemple suivant illustre une requête de recherche pour Burbank, Californie.

// Headers
const headers = {
  "X-Goog-Api-Key": "YOUR API KEY",
};

const data: SearchRegionRequestData = {
  search_values: [
    {
      "address": "2627 N Hollywood Way, Burbank, CA" ,
      "place_type": "locality" as const,
      "region_code": "us"
    },
  ],
};
const response = await regionLookupClient.searchRegion({ headers, data });

Réponse de la recherche par région

L'objet SearchRegionResponse contient un matched_place_id si un résultat a été trouvé. En cas d'échec de la correspondance, la réponse contient une ou plusieurs propositions d'ID de lieu et un code d'erreur.

{
  "matches": [
    {
      "matchedPlaceId": "ChIJPV4oX_65j4ARVW8IJ6IJUYs"
    }
  ]
}

Référence

Identifiants `LookupRegionRequestData`

Champ	Type	Description
`place`	chaîne	Nom de la région à faire correspondre à un ID de lieu. Utilisez le champ `place` en combinaison avec `place_type` pour rechercher l'ID de lieu de la région. Par exemple, si `place_type` correspond à "locality", un `place` valide peut être "Palo Alto, CA". Si `place_type` correspond à `POSTAL_CODE`, "94109" peut être un place_name valide. Si `place_type` correspond à `COUNTRY`, "États-Unis" peut être un `place` valide, etc. `region_code` est obligatoire lorsque `place` est spécifié, sauf si `place_type` est `COUNTRY`.
`unit_code`	chaîne	Codes FIPS de l'État ou du comté (États-Unis uniquement) ou code pays ISO-3166-1 à mettre en correspondance. Le champ `unit_code` est utilisé en combinaison avec `place_type` pour consulter l'ID de lieu de la région. Par exemple, si `place_type` correspond à `COUNTRY`, "US" (code Alpha-2 ISO-3166-1 pour les États-Unis) ou "BR" (code Alpha-2 ISO-3166-1 pour le Brésil) peuvent être des unit_code valides. Si `place_type` correspond à `ADMINISTRATIVE_AREA_LEVEL_1` (État) et que region_code correspond à "US", "6" (code FIPS pour la Californie) ou "12" (code FIPS pour la Floride) peuvent être des unit_code valides. Si place_type correspond à `ADMINISTRATIVE_AREA_LEVEL_2` (pays) et que region_code correspond à "US", "6001" (code FIPS pour le comté d'Alameda en Californie) ou "12086" (code FIPS pour le comté de Miami-Dade en Floride) peuvent être des unit_code valides. `region_code` est requis lors de la spécification d'un code FIPS. `region_code` est ignoré pour les codes de pays ISO-3166-1.
`place_type`	PlaceType	Obligatoire. Type de région à mettre en correspondance.
`region_code`	chaîne	Code pays/région ISO-3166 à deux lettres correspondant à l'établissement que vous essayez de mettre en correspondance. region_code est facultatif si `place_type` correspond à `COUNTRY`.
`language_code`	chaîne	Code de langue BCP-47 tel que "en-US" ou "sr-Latn", correspondant à la langue dans laquelle le nom et l'adresse du lieu sont demandés. Si aucune valeur n'est demandée, la langue par défaut est l'anglais.

Identifiants `SearchRegionRequestData`

OBLIGATOIRE : address, latlng ou place_id.

Champ	Type	Description
`address`	chaîne	Adresse postale non structurée contenue dans une région à mettre en correspondance. `region_code` est obligatoire lorsque `address` est spécifié.
`latlng`	LatLng	Latitude et longitude contenues dans une région à mettre en correspondance.
`place_id`	chaîne	ID de lieu contenu dans une région à mettre en correspondance.
`place_type`	type de lieu	Obligatoire. Type de région à mettre en correspondance.
`language_code`	chaîne	Code de langue BCP-47 tel que "en-US" ou "sr-Latn", correspondant à la langue dans laquelle le nom et l'adresse du lieu sont demandés. Si aucune n'est demandée, la langue par défaut est l'anglais.
`region_code`	chaîne	Code pays/région ISO-3166 à deux lettres du lieu à mettre en correspondance. `region_code` est obligatoire lorsque l'adresse est spécifiée.

Types de lieu

Valeur	Description
`POSTAL_CODE`	Code postal, utilisé pour adresser le courrier postal dans le pays.
`ADMINISTRATIVE_AREA_LEVEL_1`	Entité civile de premier ordre en dessous du niveau du pays. Aux États-Unis, ces niveaux administratifs sont les États.
`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.
`LOCALITY`	Entité politique de ville ou de municipalité incorporée.
`COUNTRY`	Entité politique nationale, généralement le type d'ordre le plus élevé.

LatLng

Objet représentant une paire latitude/longitude. Cette valeur est exprimée par une paire de doubles représentant les degrés de latitude et de longitude. Sauf indication contraire, cet objet doit être conforme à la norme WGS84. Les valeurs doivent se situer dans les limites normalisées.

Champ	Type	Description
`latitude`	double	Latitude en degrés. Elle doit être comprise dans la plage `[-90.0, +90.0]`. Exemple : `47.47583476464538`.
`longitude`	double	Longitude en degrés. Elle doit être comprise dans la plage `[-180.0, +180.0]`. Exemple `-121.73858779269906`.

Codes d'erreur

Valeur	Description
`UnknownError`	Une erreur inconnue s'est produite.
`NoMatchFound`	La requête n'a donné aucun résultat. Vérifiez `candidate_place_ids` si disponible.
`AddressNotUnderstood`	Échec du geocoding pour l'adresse indiquée.
`PlaceTypeMismatch`	Le type de lieu indiqué dans la réponse ne correspond pas à celui de la requête. Par exemple, `locality` a été demandé, mais `administrative_area_level_2` a été renvoyé.
`MultipleCandidatesFound`	Plusieurs propositions ont renvoyé une correspondance avec l'entrée. Vérifiez `candidate_place_ids` si disponible.
`PlaceNameNotUnderstood`	Le nom de lieu fourni n'a pas pu être résolu sous forme de région.
`UnitCodeNotFound`	Code d'unité introuvable. Vérifiez que le code d'unité est valide et fourni au bon format.
`PlaceTypeNotAllowed`	L'ID de lieu correspondant ne figure pas sur la liste d'autorisation de type de lieu et de pays.