Usare l'API Region lookup

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

  • La funzionalità Ricerca per regione consente di cercare una regione in base al nome della località, al codice FIPS (solo per 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 regionali supportati

Sono supportati i seguenti tipi di luoghi regionali: 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 Ricerca regione fornisce un insieme di funzioni e caratteri TypeScript da importare nel 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 regione

Una richiesta di ricerca di regione prende in considerazione il nome di una località o un codice identificativo 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 Il codice paese/regione ISO-3166 di due lettere della località corrispondente. region_code è facoltativo se il valore di place_type è COUNTRY.
  • language Il codice lingua BCP-47, ad esempio "en-US" o "sr-Latn". Se non viene specificato nessuno, 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 alcun valore, 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 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

    matched_place_id risultati: 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

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

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

Gli ID delle posizioni candidati vengono restituiti in caso di ambiguità. 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 di ricerca regione

L'oggetto LookupRegionResponse contiene un matched_place_id se è stato trovato un risultato. Se non viene trovato alcun risultato, gli ID luogo con 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 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 indirizzo non strutturata, latlng o ID luogo contenuto nella regione (ad esempio PDI, edificio e così via). Se non viene specificato alcun valore, viene restituito un errore.
  • place_type (obbligatorio) Il valore tipo di luogo per il tipo di regione da cercare.
  • region_code Il codice paese/regione ISO-3166 di due lettere della località corrispondente. region_code è obbligatorio quando viene specificato address.
  • language Il codice lingua BCP-47, ad esempio "en-US" o "sr-Latn". Se non viene specificato nessuno, 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 della ricerca per sezione

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 candidato e un codice di errore.

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

Riferimento

LookupRegionRequestData identificatori

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 è "località", un place valido può essere "Palo Alto, CA". Se place_type è "POSTAL_CODE", un place_name valido può essere "94109". Se place_type è "COUNTRY", un valore 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 statali o di contea FIP (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 regione. Ad esempio: se place_type è COUNTRY, un valore 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 valore unit_code valido può essere "6" (codice FIP per la California) o "12"(codice FIP per la Florida). Se place_type è ADMINISTRATIVE_AREA_LEVEL_2 (contea) e Region_code è "US", un unit_code valido può essere "6001" (codice FIP per la contea di Alameda in California) o "12086" (codice FIP per la contea di Miami-Dade in Florida). region_code è obbligatorio quando si specifica 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 Il codice paese/regione ISO-3166 di due lettere della località per la quale stai cercando di trovare una corrispondenza. Il campo 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 ne viene richiesta nessuna, il valore predefinito sarà l'inglese.

SearchRegionRequestData identificatori

REQUIRED: uno dei seguenti valori: address, latlng o place_id.

Campo Tipo Descrizione
address stringa Un indirizzo non strutturato contenuto all'interno di una regione corrispondente. region_code è obbligatorio quando viene specificato address.
latlng LatLng La latitudine e la longitudine di una regione corrispondente.
place_id stringa Un ID luogo all'interno di una regione da abbinare.
place_type tipo di luogo obbligatorio. Il tipo di regione da associare.
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 ne viene richiesta nessuna, il valore predefinito sarà l'inglese.
region_code stringa Il codice paese/regione ISO-3166 di due lettere della località da abbinare. Il campo region_code è obbligatorio quando viene specificato l'indirizzo.

Tipi di luogo

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

LatLng

Un oggetto che rappresenta una coppia latitudine/longitudine. Questo valore è espresso da una coppia di 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 essere compresi negli intervalli normalizzati.

Campo Tipo Descrizione
latitude double Latitudine in gradi. Deve essere compreso nell'intervallo [-90.0, +90.0]. Ad esempio 47.47583476464538.
longitude double 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 restituito 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 Più candidati sono stati abbinati all'input. Controlla candidate_place_ids. se disponibili.
PlaceNameNotUnderstood Il nome del luogo fornito non è stato risolto in una regione.
UnitCodeNotFound Codice unità non trovato. Verifica che il codice dell'unità sia valido e fornito nel formato corretto.
PlaceTypeNotAllowed L'ID luogo corrispondente non è nella lista consentita del tipo di luogo e del paese.