Utilizzare l'API Region Lookup

Con l'API Region Lookup, puoi trovare gli ID luogo delle regioni, che puoi utilizzare per applicare stili ai poligoni dei confini negli stili basati sui dati per i confini. L'API Region Lookup supporta due tipi di richieste:

  • Ricerca regione cerca una regione in base al nome del luogo, al codice FIPS (solo stati e contee degli Stati Uniti) o al codice paese ISO-3166-1.
  • Ricerca per regione cerca la regione che contiene una località specifica, indicata da un indirizzo, da LatLng o da un ID luogo.

Tipi di luoghi per le regioni supportate

Sono supportati i seguenti tipi di località per le regioni: country, administrative_area_level_1, administrative_area_level_2, postal_code, locality.

Installa la libreria

Per utilizzare l'API Region Lookup, segui questi passaggi:

  1. Abilita l'API Region Lookup nella console.
  2. Installa la libreria open source: npm install @googlemaps/region-lookup

Importa le dipendenze dalla libreria

La libreria open source Region Lookup fornisce un insieme di funzioni e tipi TypeScript che devi importare nel tuo codice.

  • Per le richieste di ricerca delle regioni, importa quanto segue:

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

  • Per le richieste di ricerca di regioni, importa quanto segue:

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

Richieste di ricerca per regione

Una richiesta di ricerca di una regione accetta un nome o un codice identificativo di un luogo e restituisce un ID luogo. Per cercare una regione, chiama lookupRegion(), specificando un LookupRegionRequestData con i seguenti parametri:

  • place o unit_code (obbligatorio) Il nome della regione (place) o unit_code del luogo. unit_code può essere un codice FIPS (solo per stati e contee degli Stati Uniti) o un codice paese ISO-3166-1.
  • place_type (obbligatorio) Il valore tipo di luogo per il tipo di luogo da cercare.
  • region_code Codice paese/regione ISO-3166 di due lettere per la località da trovare. region_code è facoltativo se place_type è COUNTRY.
  • language Il codice lingua BCP-47, ad esempio "en-US" o "sr-Latn". Se non viene specificata alcuna lingua, il valore predefinito è en-US.

L'esempio seguente mostra una richiesta di ricerca per Newark, NJ.

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

È obbligatorio specificare il parametro place o unit_code. Se non ne viene specificato nessuno, viene restituito un errore.

Il parametro region_code è obbligatorio, a meno che place_type non sia COUNTRY.

place e unit_code specificano una località a cui abbinare un ID luogo. Ad esempio, se place è "California" e place_type è ADMINISTRATIVE_AREA_LEVEL_1, l'API restituisce l'ID luogo della California come matched_place_id:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

    Risultati di matched_place_id: ID luogo della California. Tutti gli altri tipi supportati non restituiscono corrispondenze.

Se unit_code è "6" (codice FIPS per la California), place_type è ADMINISTRATIVE_AREA_LEVEL_1 e region_code è "US", l'API restituisce l'ID luogo della California:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

  • region_code: US

    Risultati di matched_place_id: ID luogo per la California. Tutti gli altri tipi supportati non restituiscono corrispondenze.

Se unit_code è "US", l'API restituisce i seguenti risultati quando vengono specificati i seguenti place_type:

  • place_type: COUNTRY

    Risultati di matched_place_id: ID luogo per gli Stati Uniti. Tutti gli altri tipi supportati non restituiscono corrispondenze.

Se non viene trovata alcuna corrispondenza, matched_place_id non viene impostato.

In caso di ambiguità, vengono restituiti gli ID luogo candidati. Ad esempio, se place è "Contea di Santa Clara" e place_type è LOCALITY, l'ID luogo della Contea di Santa Clara viene restituito come candidato.

Risposta alla ricerca della regione

L'oggetto LookupRegionResponse contiene un matched_place_id se è stato trovato un risultato. Se non viene trovato alcun risultato, gli ID luogo con un livello di confidenza inferiore vengono restituiti come ID candidati, insieme a un codice di errore contenente informazioni di debug.

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

Richieste di ricerca per sezione

Per trovare una regione che contiene una località specifica, chiama searchRegion specificando un SearchRegionRequestData con i seguenti parametri:

  • address o latlng o place_id (obbligatorio) Contiene una stringa di indirizzo non strutturata, latlng o un ID luogo contenuto nella regione (ad esempio PDI, edificio e così via). Se non ne viene specificato nessuno, viene restituito un errore.
  • place_type (obbligatorio) Il valore tipo di luogo per il tipo di regione da cercare.
  • region_code Codice paese/regione ISO-3166 di due lettere per la località da trovare. region_code è obbligatorio quando è specificato address.
  • language Il codice lingua BCP-47, ad esempio "en-US" o "sr-Latn". Se non viene specificata alcuna lingua, il valore predefinito è en-US.

L'esempio seguente mostra una richiesta di ricerca per Burbank, CA.

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

Risposta di ricerca per regione

L'oggetto SearchRegionResponse contiene un matched_place_id se è stato trovato un risultato. In caso di corrispondenza non riuscita, la risposta contiene uno o più ID luogo candidati e un codice di errore.

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

Riferimento

Identificatori LookupRegionRequestData

Campo Tipo Descrizione
place stringa Il nome della regione da abbinare a un ID luogo. Utilizza il campo place in combinazione con place_type per cercare l'ID luogo della regione. Ad esempio, se place_type è "locality", un place valido può essere "Palo Alto, CA". Se place_type è "POSTAL_CODE", un valore place_name valido può essere "94109". Se place_type è "COUNTRY", un place valido può essere "Stati Uniti" e così via. region_code è obbligatorio quando viene specificato place, a meno che place_type non sia "COUNTRY".
unit_code stringa I codici FIPS di stato o contea (solo per gli Stati Uniti) o il codice paese ISO-3166-1 da soddisfare. Il campo unit_code viene utilizzato in combinazione con place_type per cercare l'ID luogo della regione. Ad esempio: se place_type è COUNTRY, un unit_code valido può essere "US" (codice ISO-3166-1 Alpha-2 per gli Stati Uniti) o "BR" (codice ISO-3166-1 Alpha-2 per il Brasile). Se place_type è ADMINISTRATIVE_AREA_LEVEL_1 (stato) e region_code è "US", un unit_code valido può essere "6" (codice FIPS per la California) o "12"(codice FIPS per la Florida). Se place_type è ADMINISTRATIVE_AREA_LEVEL_2 (contea) e region_code è "US", un unit_code valido può essere "6001" (codice FIPS per la contea di Alameda in California) o "12086" (codice FIPS per la contea di Miami-Dade in Florida). region_code è obbligatorio quando specifichi un codice FIPS. region_code viene ignorato per i codici paese ISO-3166-1.
place_type PlaceType Obbligatorio. Il tipo di regione da far corrispondere.
region_code stringa Codice paese/regione ISO-3166 di due lettere per la località che stai cercando di trovare. region_code è facoltativo se place_type è "COUNTRY".
language_code stringa Il codice lingua BCP-47, ad esempio "en-US" o "sr-Latn", corrispondente alla lingua in cui vengono richiesti il nome e l'indirizzo del luogo. Se non viene richiesta nessuna lingua, l'impostazione predefinita è l'inglese.

Identificatori SearchRegionRequestData

OBBLIGATORIO: uno dei valori address, latlng o place_id.

Campo Tipo Descrizione
address stringa Un indirizzo non strutturato contenuto all'interno di una regione da abbinare. region_code è obbligatorio quando è specificato address.
latlng LatLng La latitudine e la longitudine contenute all'interno di una regione da abbinare.
place_id stringa Un ID luogo contenuto all'interno di una regione da trovare.
place_type place type Obbligatorio. Il tipo di regione da far corrispondere.
language_code stringa Il codice lingua BCP-47, ad esempio "en-US" o "sr-Latn", corrispondente alla lingua in cui sono richiesti il nome e l'indirizzo del luogo. Se non viene richiesta alcuna lingua, per impostazione predefinita viene utilizzato l'inglese.
region_code stringa Codice paese/regione ISO-3166 di due lettere per la località da trovare. region_code è obbligatorio quando viene specificato l'indirizzo.

Tipi di luoghi

Valore Descrizione
POSTAL_CODE Un codice postale, utilizzato per la spedizione della posta tradizionale nel paese.
ADMINISTRATIVE_AREA_LEVEL_1 Una divisione amministrativa principale al di sotto del livello paese. Negli Stati Uniti, questi livelli amministrativi sono gli stati.
ADMINISTRATIVE_AREA_LEVEL_2 Una divisione amministrativa di secondo livello al di sotto del livello paese. Negli Stati Uniti, questi livelli amministrativi sono le contee.
LOCALITY Un'entità politica di una città o di un comune incorporato.
COUNTRY L'entità politica nazionale, in genere il tipo di ordine più elevato.

LatLng

Un oggetto che rappresenta una coppia di latitudine/longitudine. Questo valore è espresso come una coppia di valori double per rappresentare i gradi di latitudine e longitudine. Se non diversamente specificato, questo oggetto deve essere conforme allo standard WGS84. I valori devono rientrare negli intervalli normalizzati.

Campo Tipo Descrizione
latitude doppia La latitudine in gradi. Deve essere compreso nell'intervallo [-90.0, +90.0]. Ad esempio 47.47583476464538.
longitude doppia La longitudine in gradi. Deve essere compreso nell'intervallo [-180.0, +180.0]. Ad esempio -121.73858779269906.

Codici di errore

Valore Descrizione
UnknownError Si è verificato un errore sconosciuto.
NoMatchFound La richiesta non ha prodotto corrispondenze, controlla candidate_place_ids se disponibile.
AddressNotUnderstood Geocodifica non riuscita per l'indirizzo fornito.
PlaceTypeMismatch Il tipo di luogo nella risposta non corrisponde a quello della richiesta. Ad esempio, è stato richiesto locality, ma è stato restituito administrative_area_level_2.
MultipleCandidatesFound Sono stati trovati più candidati corrispondenti all'input. Controlla candidate_place_ids. se disponibile.
PlaceNameNotUnderstood Il nome del luogo fornito non è stato risolto in una regione.
UnitCodeNotFound Il codice dell'unità non è stato trovato. Verifica che il codice dell'unità sia valido e fornito nel formato corretto.
PlaceTypeNotAllowed L'ID luogo corrispondente non è incluso nella lista consentita di tipi di luogo e paesi.