Utiliser l'API Region Lookup

L'API Region Lookup vous permet de trouver les ID de lieu de régions, que vous pouvez utiliser pour personnaliser les polygones de délimitation avec un style basé sur les données pour les limites. 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és

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 :

  1. Activez l'API Region Lookup dans la console.
  2. 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 typages 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 s'affiche.

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 correspond à "Comté de Santa Clara" et que place_type est LOCALITY, l'ID de lieu du comté de Santa Clara est renvoyé en tant que proposition.

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 la 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", "Palo Alto, CA" peut être valide en tant que place. 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 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 au lieu 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 valeur 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 correspondent aux É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.