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:
- Abilita l'API Region Lookup nella console.
- 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
ounit_code
(obbligatorio) Il nome della regione (place
) ounit_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
olatlng
oplace_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 specificatoaddress
.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. |