Usare l'API Region lookup

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

  • La ricerca delle regioni consente di cercare una regione in base al nome del luogo, al codice FIPS (solo contee e stati degli Stati Uniti) o al codice paese ISO-3166-1.
  • La ricerca per regione cerca la regione che contiene una località specifica, come specificato da un indirizzo, da LatLng o da un ID luogo.

Tipi di località delle regioni supportati

I seguenti tipi di località della regione sono supportati: country, administrative_area_level_1, administrative_area_level_2, postal_code, locality.

Installa la libreria

Per utilizzare l'API Region Lookup:

  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 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 per regione, importa quanto segue:

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

Richieste di ricerca delle regioni

Una richiesta di ricerca della regione prende un nome di luogo o un codice identificatore 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 contee e stati 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 della località da abbinare. region_code è facoltativo se place_type è COUNTRY.
  • language Il codice lingua BCP-47, ad esempio "en-US" o "sr-Latn". Se non viene specificato alcun valore, il valore predefinito è en-US.

L'esempio seguente mostra una richiesta di ricerca per Newark, nel 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 });

È obbligatorio specificare il parametro place o unit_code. Se non 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à da associare a un ID luogo. Ad esempio, se place è "California" e place_type è ADMINISTRATIVE_AREA_LEVEL_1, l'API restituisce l'ID luogo per la California come matched_place_id:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

    matched_place_id results: place ID for California. Tutti gli altri tipi supportati non restituiscono alcuna corrispondenza.

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 per la California:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

  • region_code: US

    matched_place_id results: place ID per la California. Tutti gli altri tipi supportati non restituiscono alcuna corrispondenza.

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

  • place_type: COUNTRY

    matched_place_id results: ID posizione per gli Stati Uniti. Tutti gli altri tipi supportati non restituiscono alcuna corrispondenza.

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

Gli ID luogo candidati vengono restituiti in caso di ambiguità. Ad esempio, se place è "Contea di Santa Clara" e place_type è LOCALITY, l'ID luogo per la 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, vengono restituiti ID luogo con un'affidabilità inferiore come ID candidati, insieme a un codice di errore contenente informazioni di debug.

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

Richieste di ricerca per regione

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 ID luogo contenuto dalla regione (ad es. PDI, edificio e così via). Se non 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 della località da abbinare. region_code è obbligatorio quando viene specificato address.
  • language Il codice lingua BCP-47, ad esempio "en-US" o "sr-Latn". Se non viene specificato alcun valore, il valore predefinito è en-US.

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

// 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 alla ricerca per regione

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

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

Riferimento

LookupRegionRequestData identificatori

Campo Tipo Descrizione
place stringa Il nome della regione da associare 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 è "località", un valore place valido può essere "Palo Alto, CA". Se place_type è "POSTAL_CODE", un nome_luogo valido può essere "94109". Se place_type è "COUNTRY", un valore place valido può essere "United States" e così via. region_code è obbligatorio quando viene specificato place, a meno che place_type non sia "COUNTRY".
unit_code stringa I codici stato o contea (solo Stati Uniti) o il codice paese ISO-3166-1 da associare. 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 valore valido per unit_code 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 valore valido per unit_code 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 codice 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 viene specificato un codice FIP. region_code viene ignorato per i codici paese ISO-3166-1.
place_type PlaceType Obbligatorio. Il tipo di regione da associare.
region_code stringa Codice paese/regione ISO-3166 di due lettere per la località che stai cercando di trovare una corrispondenza. region_code è facoltativo se place_type è "COUNTRY".
language_code stringa Il codice lingua BCP-47, ad esempio "it-IT" o "sr-Latn", corrispondente alla lingua in cui sono richiesti il nome e l'indirizzo del luogo. Se non viene richiesto nessuno, per impostazione predefinita viene utilizzato l'inglese.

SearchRegionRequestData identificatori

OBBLIGATORIO: uno tra address, latlng o place_id.

Campo Tipo Descrizione
address stringa Un indirizzo stradale non strutturato contenuto in una regione da abbinare. region_code è obbligatorio quando viene specificato address.
latlng LatLng La latitudine e la longitudine contenute in una regione da associare.
place_id stringa Un ID luogo contenuto all'interno di una regione da associare.
place_type place type Obbligatorio. Il tipo di regione da associare.
language_code stringa Il codice lingua BCP-47, come ad esempio "en-US" o "sr-Latn", corrispondente alla lingua in cui sono richiesti il nome e l'indirizzo del luogo. Se non ne viene richiesta nessuna, viene utilizzato per impostazione predefinita l'inglese.
region_code stringa Codice paese/regione ISO-3166 di due lettere per la località da associare. 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 all'interno del paese.
ADMINISTRATIVE_AREA_LEVEL_1 Una persona giuridica civile di primo ordine al di sotto del livello del paese. Negli Stati Uniti, questi livelli amministrativi sono gli stati.
ADMINISTRATIVE_AREA_LEVEL_2 Un'entità civile di secondo ordine al di sotto del livello del paese. Negli Stati Uniti, questi livelli amministrativi sono le contee.
LOCALITY Un'entità politica costituita come città o paese.
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 numeri doppi per rappresentare i gradi di latitudine e i gradi di longitudine. Se non diversamente specificato, questo oggetto deve essere conforme allo standard WGS84. I valori devono rientrare in intervalli normalizzati.

Campo Tipo Descrizione
latitude double La latitudine in gradi. Deve essere compreso nell'intervallo [-90.0, +90.0]. Ad esempio 47.47583476464538.
longitude double 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 generato alcuna corrispondenza. Controlla candidate_place_ids se disponibile.
AddressNotUnderstood La geocodifica non è riuscita per l'indirizzo fornito.
PlaceTypeMismatch Il tipo di luogo nella risposta non corrisponde a quello della richiesta. Ad esempio, è stata richiesta locality, ma è stato restituito administrative_area_level_2.
MultipleCandidatesFound Sono stati trovati più candidati corrispondenti all'input. Controlla candidate_place_ids. se disponibile.
PlaceNameNotUnderstood Non è stato possibile risolvere il nome del luogo fornito in una regione.
UnitCodeNotFound Il codice unità non è stato trovato. Verifica che il codice dell'unità sia valido e fornito nel formato corretto.
PlaceTypeNotAllowed L'ID luogo corrispondente non è presente nella lista consentita di tipo di luogo e paese.