Utilizzare l'API Region Lookup

Con l'API Region Lookup, puoi trovare gli ID luogo per le regioni, che puoi utilizzare per applicare uno stile ai poligoni dei confini nello stile basato sui dati per i confini. L'API Region Lookup supporta due tipi di richieste:

  • La ricerca delle regioni 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 posizione specifica come specificato da un indirizzo, LatLng o ID luogo.

Tipi di luoghi delle regioni supportati

Sono supportati i seguenti tipi di luoghi della regione: 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 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 delle regioni

Una richiesta di ricerca della 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 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 corrispondere. region_code è facoltativo se place_type è COUNTRY.
  • language Il codice lingua BCP-47, ad esempio "en-US" o "sr-Latn". Se non ne viene specificata nessuna, il valore predefinito è en-US.

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

È necessario 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 posizione a cui abbinare 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

    Risultati matched_place_id: ID luogo per la 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 per la California:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

  • region_code: US

    Risultati 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 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.

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, gli ID luogo con un livello di affidabilità 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 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 corrispondere. region_code è obbligatorio quando viene specificato address.
  • language Il codice lingua BCP-47, ad esempio "en-US" o "sr-Latn". Se non ne viene specificata nessuna, 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 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

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 "United States" e così via. region_code è obbligatorio quando place è 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 abbinare. 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 viene specificato un codice FIPS. region_code viene ignorato per i codici paese ISO-3166-1.
place_type PlaceType Obbligatorio. Il tipo di regione da abbinare.
region_code stringa Codice paese/regione ISO-3166 di due lettere per la località che stai cercando di abbinare. 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 alcuna lingua, viene utilizzata l'inglese per impostazione predefinita.

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 corrispondere. region_code è obbligatorio quando viene specificato address.
latlng LatLng La latitudine e la longitudine contenute all'interno di una regione da corrispondere.
place_id stringa Un ID luogo contenuto all'interno di una regione da corrispondere.
place_type place type Obbligatorio. Il tipo di regione da abbinare.
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 alcuna lingua, viene utilizzata l'inglese per impostazione predefinita.
region_code stringa Codice paese/regione ISO-3166 di due lettere per la località da corrispondere. region_code è obbligatorio quando viene specificato l'indirizzo.

Tipi di luoghi

Valore Descrizione
POSTAL_CODE Un codice postale, come quello utilizzato per la spedizione della posta tradizionale di un 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 costituita in società.
COUNTRY L'entità politica nazionale, in genere il tipo di ordine più elevato.

LatLng

Un oggetto che rappresenta una coppia di coordinate di latitudine e longitudine. Questo valore è espresso come una coppia di numeri 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 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 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, è 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 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 tipo di luogo e paese.