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 di confine negli stili basati sui dati per i confini. L'API Region Lookup supporta due tipi di richieste:

  • La ricerca per 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.
  • La ricerca per regione cerca la regione che contiene una località specifica come specificato da un indirizzo, LatLng o ID luogo.

Tipi di luoghi per le regioni supportati

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

Installare 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

Importare le dipendenze dalla libreria

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

  • Per le richieste di ricerca per regione, 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 per regione

Una richiesta di ricerca per regione accetta 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 stati e contee degli Stati Uniti) o un codice paese ISO-3166-1.
  • place_type (obbligatorio). Il valore del tipo di luogo per il tipo di luogo da cercare.
  • region_code . Codice paese/regione ISO-3166 di due lettere per la località da soddisfare. region_code è facoltativo se place_type è COUNTRY.
  • language. Il codice lingua BCP-47, ad esempio "en-US" o "sr-Latn". Se non viene specificato, 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 viene specificato, 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 associare 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 risultati: ID luogo per la 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

    Risultati di matched_place_id: ID luogo 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_types:

  • place_type: COUNTRY

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

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 è "Santa Clara County" e place_type è LOCALITY l'ID luogo per la contea di Santa Clara viene restituito come candidato.

Risposta di ricerca per 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 attendibilità inferiore vengono restituiti 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 nella regione (ad esempio, punto d'interesse, edificio e così via). Se non viene specificato, viene restituito un errore.
  • place_type (obbligatorio). Il valore del tipo di luogo per il tipo di regione da cercare.
  • region_code . Codice paese/regione ISO-3166 di due lettere per la località da soddisfare. region_code è obbligatorio quando viene specificato address.
  • language. Il codice lingua BCP-47, ad esempio "en-US" o "sr-Latn". Se non viene specificato, 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 mancata corrispondenza, 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 associare a un ID luogo. Utilizza il place campo 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 nome di luogo valido può essere "94109". Se place_type è `COUNTRY`, un place valido può essere "United States" e così via. region_code è obbligatorio quando place viene specificato, a meno che place_type non sia `COUNTRY`.
unit_code stringa I codici stato o contea FIPS (solo 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 si specifica un codice FIPS. region_code viene ignorato per i codici paese ISO-3166-1.
place_type PlaceType Obbligatorio. Il tipo di regione da soddisfare.
region_code stringa Codice paese/regione ISO-3166 di due lettere per la località che stai cercando di soddisfare. 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 viene richiesto il nome e l'indirizzo del luogo. Se non viene richiesto, il valore predefinito è l'inglese.

Identificatori SearchRegionRequestData

OBBLIGATORIO: uno tra address, latlng o place_id.

Campo Tipo Descrizione
address stringa Un indirizzo stradale non strutturato contenuto all'interno di una regione da soddisfare. region_code è obbligatorio quando address è specificato.
latlng LatLng La latitudine e la longitudine contenute all'interno di una regione da soddisfare.
place_id stringa Un ID luogo contenuto all'interno di una regione da soddisfare.
place_type tipo di luogo Obbligatorio. Il tipo di regione da soddisfare.
language_code stringa Il codice lingua BCP-47, ad esempio "en-US" o "sr-Latn", corrispondente alla lingua in cui viene richiesto il nome e l'indirizzo del luogo. Se non viene richiesto, il valore predefinito è l'inglese.
region_code stringa Codice paese/regione ISO-3166 di due lettere per la località da soddisfare. 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 Un'entità civile di primo ordine al di sotto del livello paese. Negli Stati Uniti, questi livelli amministrativi sono gli stati.
ADMINISTRATIVE_AREA_LEVEL_2 Un'entità civile 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 costituita in società.
COUNTRY L'entità politica nazionale, in genere il tipo di ordine più elevato.

LatLng

Un oggetto che rappresenta una coppia latitudine/longitudine. Viene espressa come una coppia di numeri con rappresentazione in virgola mobile 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 double La latitudine in gradi. Deve essere compresa nell'intervallo [-90.0, +90.0]. Ad esempio 47.47583476464538.
longitude double La longitudine in gradi. Deve essere compresa 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 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 è stata restituita administrative_area_level_2.
MultipleCandidatesFound Sono stati trovati più candidati per l'input. Controlla candidate_place_ids. se disponibile.
PlaceNameNotUnderstood Il nome del luogo fornito non è stato risolto in una regione.
UnitCodeNotFound Il codice unità non è stato trovato. Verifica che il codice unità sia valido e fornito nel formato corretto.
PlaceTypeNotAllowed L'ID luogo corrispondente non è incluso nella lista consentita di tipo di luogo e paese.