Richiesta
Una richiesta dell'API Geocoding ha il seguente formato:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
dove outputFormat può essere uno dei seguenti valori:
json(consigliato) indica l'output in JavaScript Object Notation (JSON); oppurexmlindica l'output in XML
HTTPS è obbligatorio.
Alcuni parametri sono obbligatori, altri facoltativi. Come di consueto negli URL, i parametri sono separati dal carattere e commerciale (&).
Il resto di questa pagina descrive la geocodifica e la geocodifica inversa separatamente, perché per ogni tipo di richiesta sono disponibili parametri diversi.
Parametri di geocodifica (ricerca di latitudine/longitudine)
Parametri obbligatori in una richiesta di geocodifica:
key: la chiave API della tua applicazione. Questa chiave identifica la tua applicazione ai fini della gestione della quota. Scopri come ottenere una chiave.In una richiesta devi specificare
addressocomponentso entrambi:address: la via o il Plus Code che vuoi geocodificare. Nota: la geocodifica degli indirizzi non risolve le coordinate di latitudine e longitudine o altre stringhe non strutturate che non rappresentano un indirizzo o un Plus Code. Le richieste che utilizzano queste stringhe non sono supportate e potrebbero generare risposte di errore o comportamenti non specificati. Ecco alcuni esempi di query non supportate:
Specifica gli indirizzi in conformità al formato utilizzato dal servizio postale nazionale del paese interessato. Evita elementi aggiuntivi dell'indirizzo, come nomi di attività e numeri di unità, suite o piano. Gli elementi dell'indirizzo via devono essere delimitati da spazi (mostrati qui con escape URLTipo di query Esempio Coordinate di latitudine e longitudine. Utilizza invece la geocodifica inversa. "37.422131,-122.084801" Troppi concetti o vincoli, ad esempio i nomi di più luoghi, strade o città in una singola query "Market Street San Francisco San Jose Airport" Elementi dell'indirizzo postale non rappresentati su Google Maps "C/O Mario Rossi 123 Main Street"
"Casella postale 13 San Francisco"Nomi di attività, catene o categorie combinati con località in cui queste entità non sono disponibili "Tesco vicino a Dallas, Texas" Query ambigue con più interpretazioni "Consegna del caricabatterie" Nomi storici non più in uso "Middlesex United Kingdom" Elementi o intenti non geospaziali "Quante barche ci sono nel porto di Ventura?" Nomi non ufficiali o vanity "The Jenga"
"The Helter Skelter"%20):address=24%20Sussex%20Drive%20Ottawa%20ON
%2Be gli spazi sono preceduti da un carattere di escape dell'URL%20):- codice globale è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9 è
849VCWC8%2BR9). - codice composto è un codice locale di almeno sei caratteri con una
posizione esplicita (CWC8+R9 Mountain View, CA, USA è
CWC8%2BR9%20Mountain%20View%20CA%20USA).
- codice globale è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9 è
components: un filtro dei componenti con elementi separati da una barra verticale (|). Il filtro dei componenti è accettato anche come parametro facoltativo se viene fornito unaddress. Ogni elemento nel filtro dei componenti è costituito da una coppiacomponent:valuee limita completamente i risultati del geocodificatore. Scopri di più sul filtro dei componenti di seguito.
Per ulteriori indicazioni, consulta le domande frequenti.
Parametri facoltativi in una richiesta di geocodifica:
bounds: il riquadro di delimitazione dell'area visibile all'interno della quale dare maggiore risalto ai risultati di geocodifica. Questo parametro influenzerà, ma non limiterà completamente, i risultati del geocodificatore. Per saperne di più, consulta la sezione Preferenza per l'area visibile di seguito.language: la lingua in cui restituire i risultati.- Consulta l'elenco delle lingue supportate. Google aggiorna spesso le lingue supportate, pertanto questo elenco potrebbe non essere esaustivo.
- Se
languagenon viene fornito, il geocodificatore tenta di utilizzare la lingua preferita specificata nell'intestazioneAccept-Languageo la lingua nativa del dominio da cui viene inviata la richiesta. - Il geocodificatore fa del suo meglio per fornire un indirizzo leggibile sia per l'utente sia per le persone del posto. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in un alfabeto leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo vengono restituiti tutti nella stessa lingua, che viene scelta dal primo componente.
- Se un nome non è disponibile nella lingua preferita, il geocodificatore utilizza la corrispondenza più vicina.
- La lingua preferita ha una piccola influenza sull'insieme di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Il geocodificatore interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni per i tipi di strade o i sinonimi che potrebbero essere validi in una lingua ma non in un'altra. Ad esempio, utca e tér sono sinonimi rispettivamente di strada e piazza in ungherese.
region: il codice regione, specificato come valore di due caratteri ccTLD ("dominio di primo livello"). Questo parametro influenzerà, ma non limiterà completamente, i risultati del geocodificatore. Per saperne di più, consulta la sezione Spostamento dell'area geografica di seguito. Il parametro può anche influire sui risultati in base alla legge vigente.components: un filtro dei componenti con elementi separati da una barra verticale (|). Il filtro dei componenti è obbligatorio se la richiesta non include unaddress. Ogni elemento nel filtro dei componenti è costituito da una coppiacomponent:valuee limita completamente i risultati del geocodificatore. Per saperne di più sul filtro dei componenti, consulta la sezione di seguito.extra_computations: utilizza questo parametro per specificare le seguenti funzionalità aggiuntive nella risposta:ADDRESS_DESCRIPTORS: consulta i descrittori di indirizzi per maggiori dettagli.BUILDING_AND_ENTRANCES: per maggiori dettagli, consulta Ingressi e sagome degli edifici.
extra_computationsnella richiesta per ogni funzionalità, ad esempio:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
Risposte
Le risposte di geocodifica vengono restituite nel formato indicato dal flag output all'interno della richiesta URL o, per impostazione predefinita, in formato JSON.
In questo esempio, l'API Geocoding richiede una richiesta API json per una query sull'indirizzo "1600 Amphitheatre Parkway, Mountain View, CA".
Questa richiesta mostra l'utilizzo del flag JSON output:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Questa richiesta mostra l'utilizzo del flag XML output:
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Seleziona le schede di seguito per visualizzare le risposte JSON e XML di esempio.
JSON
{ "results": [ { "address_components": [ { "long_name": "1600", "short_name": "1600", "types": [ "street_number" ] }, { "long_name": "Amphitheatre Parkway", "short_name": "Amphitheatre Pkwy", "types": [ "route" ] }, { "long_name": "Mountain View", "short_name": "Mountain View", "types": [ "locality", "political" ] }, { "long_name": "Santa Clara County", "short_name": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ] }, { "long_name": "California", "short_name": "CA", "types": [ "administrative_area_level_1", "political" ] }, { "long_name": "United States", "short_name": "US", "types": [ "country", "political" ] }, { "long_name": "94043", "short_name": "94043", "types": [ "postal_code" ] }, { "long_name": "1351", "short_name": "1351", "types": [ "postal_code_suffix" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4222804, "lng": -122.0843428 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4237349802915, "lng": -122.083183169709 }, "southwest": { "lat": 37.4210370197085, "lng": -122.085881130292 } } }, "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8", "plus_code": { "compound_code": "CWC8+W7 Mountain View, CA", "global_code": "849VCWC8+W7" }, "types": [ "street_address" ] } ], "status": "OK" }
Tieni presente che la risposta JSON contiene due elementi root:
"status"contiene i metadati della richiesta. Consulta la sezione Codici di stato di seguito."results"contiene un array di informazioni sull'indirizzo geocodificato e informazioni sulla geometria.
In genere, per le ricerche di indirizzi viene restituita una sola voce nell'array "results", anche se il geocodificatore potrebbe restituire più risultati quando le query di indirizzi sono ambigue.
XML
<GeocodeResponse> <status>OK</status> <result> <type>street_address</type> <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address> <address_component> <long_name>1600</long_name> <short_name>1600</short_name> <type>street_number</type> </address_component> <address_component> <long_name>Amphitheatre Parkway</long_name> <short_name>Amphitheatre Pkwy</short_name> <type>route</type> </address_component> <address_component> <long_name>Mountain View</long_name> <short_name>Mountain View</short_name> <type>locality</type> <type>political</type> </address_component> <address_component> <long_name>Santa Clara County</long_name> <short_name>Santa Clara County</short_name> <type>administrative_area_level_2</type> <type>political</type> </address_component> <address_component> <long_name>California</long_name> <short_name>CA</short_name> <type>administrative_area_level_1</type> <type>political</type> </address_component> <address_component> <long_name>United States</long_name> <short_name>US</short_name> <type>country</type> <type>political</type> </address_component> <address_component> <long_name>94043</long_name> <short_name>94043</short_name> <type>postal_code</type> </address_component> <geometry> <location> <lat>37.4224428</lat> <lng>-122.0842467</lng> </location> <location_type>ROOFTOP</location_type> <viewport> <southwest> <lat>37.4212648</lat> <lng>-122.0856069</lng> </southwest> <northeast> <lat>37.4239628</lat> <lng>-122.0829089</lng> </northeast> </viewport> </geometry> <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id> <plus_code> <global_code>849VCWC8+X8</global_code> <compound_code>CWC8+X8 Mountain View, CA</compound_code> </plus_code> </result> </GeocodeResponse>
Tieni presente che la risposta XML è costituita da un singolo elemento <GeocodeResponse> e da due elementi di primo livello:
<status>contiene i metadati della richiesta. Consulta la sezione Codici di stato di seguito.- Zero o più elementi
<result>, ciascuno contenente un singolo insieme di informazioni sull'indirizzo geocodificato e informazioni sulla geometria.
La risposta XML è notevolmente più lunga della risposta JSON. Per questo motivo, ti consigliamo di utilizzare json come flag di output preferito, a meno che il tuo servizio non richieda xml per qualche motivo.
Inoltre, l'elaborazione degli alberi XML richiede una certa attenzione, in modo da fare riferimento ai nodi e agli elementi corretti. Consulta
Analisi di XML con XPath per alcuni pattern di progettazione consigliati per l'elaborazione dell'output.
- I risultati XML sono racchiusi in un elemento root
<GeocodeResponse>. - JSON indica le voci con più elementi tramite array plurali (
types), mentre XML le indica utilizzando più elementi singolari (<type>). - Gli elementi vuoti sono indicati tramite array vuoti in JSON, ma dall'assenza di un elemento di questo tipo in XML. Ad esempio, una risposta che non genera risultati restituirà un array
resultsvuoto in JSON, ma nessun elemento<result>in XML.
Codici di stato
Il campo "status" all'interno dell'oggetto di risposta di Geocoding contiene lo stato della richiesta e può contenere informazioni di debug per aiutarti a capire perché la geocodifica non funziona. Il campo "status" può contenere i seguenti valori:
"OK"indica che non si sono verificati errori; l'indirizzo è stato analizzato correttamente ed è stato restituito almeno un codice geografico."ZERO_RESULTS"indica che la geocodifica è andata a buon fine, ma non ha restituito risultati. Questo può accadere se al geocodificatore è stato passato unaddressinesistente.OVER_DAILY_LIMITindica una delle seguenti opzioni:- La chiave API è mancante o non valida.
- La fatturazione non è stata abilitata sul tuo account.
- È stato superato un limite di utilizzo autoimposto.
- Il metodo di pagamento fornito non è più valido (ad esempio, una carta di credito è scaduta).
Consulta le domande frequenti su Maps per scoprire come risolvere il problema.
"OVER_QUERY_LIMIT"indica che hai superato la quota."REQUEST_DENIED"indica che la tua richiesta è stata rifiutata."INVALID_REQUEST"indica in genere che la query (address,componentsolatlng) è mancante."UNKNOWN_ERROR"indica che non è stato possibile elaborare la richiesta a causa di un errore del server. La richiesta potrebbe andare a buon fine se riprovi.
Messaggi di errore
Quando il geocodificatore restituisce un codice di stato diverso da OK, potrebbe essere presente un campo error_message aggiuntivo all'interno dell'oggetto della risposta di geocodifica. Questo campo contiene informazioni più dettagliate sui motivi del codice di stato specificato.
Risultati
Quando il geocodificatore restituisce i risultati, li inserisce in un array results (JSON). Anche se il geocodificatore non restituisce risultati (ad esempio se l'indirizzo non esiste), restituisce comunque un array results vuoto. Le risposte XML sono costituite da zero o più elementi <result>.
Un risultato tipico contiene i seguenti campi:
- L'array
types[]indica il tipo del risultato restituito. Questo array contiene un insieme di zero o più tag che identificano il tipo di elemento restituito nel risultato. Ad esempio, un geocodice di "Chicago" restituisce "locality", che indica che "Chicago" è una città, e restituisce anche "political", che indica che si tratta di un'entità politica. Per saperne di più, consulta Tipi di indirizzi e tipi di componenti degli indirizzi. formatted_addressè una stringa contenente l'indirizzo leggibile di questa località.Spesso questo indirizzo corrisponde all'indirizzo postale. Tieni presente che alcuni paesi, come il Regno Unito, non consentono la distribuzione di indirizzi postali reali a causa di limitazioni delle licenze.
L'indirizzo formattato è composto logicamente da uno o più componenti dell'indirizzo. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è composto dai seguenti componenti: "111" (il numero civico), "8th Avenue" (la strada), "New York" (la città) e "NY" (lo stato degli Stati Uniti).
Non analizzare l'indirizzo formattato in modo programmatico. Devi invece utilizzare i singoli componenti dell'indirizzo, che la risposta dell'API include oltre al campo dell'indirizzo formattato.
address_components[]è un array contenente i singoli componenti applicabili a questo indirizzo.Ogni componente dell'indirizzo contiene in genere i seguenti campi:
types[]è un array che indica il tipo del componente dell'indirizzo. Il componente dell'indirizzo potrebbe avere un array di tipi vuoto se non esistono tipi noti per quel componente dell'indirizzo. L'API potrebbe aggiungere nuovi valori di tipo in base alle esigenze. Per saperne di più, consulta Tipi di indirizzi e tipi di componenti degli indirizzi.long_nameè il nome o la descrizione testuale completa del componente dell'indirizzo restituito dal geocodificatore.short_nameè un nome testuale abbreviato per il componente dell'indirizzo, se disponibile. Ad esempio, un componente dell'indirizzo per lo stato dell'Alaska potrebbe avere unlong_name"Alaska" e unshort_name"AK" utilizzando l'abbreviazione postale di 2 lettere.
Tieni presente quanto segue sull'array
address_components[]:- L'array di componenti dell'indirizzo può contenere più componenti rispetto a
formatted_address. - L'array non include necessariamente tutte le entità politiche che contengono un indirizzo, ad eccezione di quelle incluse in
formatted_address. Per recuperare tutte le entità politiche che contengono un indirizzo specifico, devi utilizzare la geocodifica inversa, passando la latitudine/longitudine dell'indirizzo come parametro alla richiesta. - Non è garantito che il formato della risposta rimanga lo stesso tra le richieste. In particolare, il numero di
address_componentsvaria in base all'indirizzo richiesto e può cambiare nel tempo per lo stesso indirizzo. Un componente può cambiare posizione nell'array. Il tipo di componente può cambiare. Un determinato componente potrebbe non essere presente in una risposta successiva.
Per gestire l'array di componenti, devi analizzare la risposta e selezionare i valori appropriati tramite le espressioni. Consulta la guida all' analisi di una risposta.
postcode_localities[]è un array che indica fino a 100 località contenute in un codice postale. Questo campo è presente solo quando il risultato è un codice postale che contiene più località.geometrycontiene le seguenti informazioni:locationcontiene il valore di latitudine e longitudine geocodificato. Per le normali ricerche di indirizzi, questo campo è in genere il più importante.location_typememorizza dati aggiuntivi sulla località specificata. Attualmente sono supportati i seguenti valori:"ROOFTOP"indica che il risultato restituito è un geocodice preciso per il quale disponiamo di dati sulla posizione accurati fino alla precisione dell'indirizzo."RANGE_INTERPOLATED"indica che il risultato restituito riflette un'approssimazione (di solito su una strada) interpolata tra due punti precisi (ad esempio gli incroci). I risultati interpolati vengono generalmente restituiti quando i geocodici di tipo ROOFTOP non sono disponibili per un indirizzo."GEOMETRIC_CENTER"indica che il risultato restituito è il centro geometrico di un risultato come una polilinea (ad esempio una strada) o un poligono (regione)."APPROXIMATE"indica che il risultato restituito è approssimativo.
viewportcontiene l'area visibile consigliata per la visualizzazione del risultato restituito, specificata come due valori di latitudine e longitudine che definiscono l'angolosouthwestenortheastdel riquadro di delimitazione dell'area visibile. In genere, l'area visibile viene utilizzata per inquadrare un risultato quando viene mostrato a un utente.bounds(restituito facoltativamente) memorizza il riquadro di delimitazione che può contenere completamente il risultato restituito. Tieni presente che questi limiti potrebbero non corrispondere all'area visibile consigliata. Ad esempio, San Francisco include le isole Farallon, che tecnicamente fanno parte della città, ma probabilmente non dovrebbero essere restituite nella visualizzazione.
-
plus_code(vedi Open Location Code e Plus Code) è un riferimento di posizione codificato, derivato dalle coordinate di latitudine e longitudine, che rappresenta un'area: 1/8000 di grado per 1/8000 di grado (circa 14 m x 14 m all'equatore) o inferiore. I Plus Code possono essere utilizzati in sostituzione degli indirizzi stradali nei luoghi in cui non esistono indirizzi (dove gli edifici non sono numerati o le strade non hanno un nome). L'API non restituisce sempre i Plus Code.Quando il servizio restituisce un Plus Code, questo viene formattato come codice globale e codice composto:
global_codeè un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9).compound_codeè un codice locale di almeno sei caratteri con una posizione esplicita (CWC8+R9, Mountain View, CA, USA). Non analizzare questi contenuti in modo programmatico.
-
partial_matchindica che il geocodificatore non ha restituito una corrispondenza esatta per la richiesta originale, anche se è stato in grado di trovare una corrispondenza per parte dell'indirizzo richiesto. Ti consigliamo di esaminare la richiesta originale per verificare la presenza di errori ortografici e/o di un indirizzo incompleto.Le corrispondenze parziali si verificano più spesso per indirizzi che non esistono all'interno della località che passi nella richiesta. Potrebbero essere restituite corrispondenze parziali anche quando una richiesta corrisponde a due o più località nella stessa località. Ad esempio, "Hillpar St, Bristol, UK" restituirà una corrispondenza parziale sia per Henry Street che per Henrietta Street. Tieni presente che se una richiesta include un componente dell'indirizzo con errori ortografici, il servizio di geocodifica potrebbe suggerire un indirizzo alternativo. I suggerimenti attivati in questo modo verranno contrassegnati anche come corrispondenza parziale.
place_idè un identificatore univoco che può essere utilizzato con altre API di Google. Ad esempio, puoi utilizzareplace_idin una richiesta dell'API Places per ottenere i dettagli di un'attività locale, come numero di telefono, orario di apertura, recensioni degli utenti e altro ancora. Consulta la panoramica degli ID luogo.
Tipi di indirizzi e tipi di componenti degli indirizzi
L'array types nella risposta indica il
tipo di indirizzo. Esempi di tipi di indirizzo includono un indirizzo, un paese o un'entità politica. L'array types nel campo address_component indica il tipo di ogni parte dell'indirizzo. Alcuni esempi sono il numero civico o il paese.
Gli indirizzi possono avere più tipi. I tipi possono essere considerati "tag".
Ad esempio, molte città sono taggate con i tipi political e locality.
I seguenti tipi sono supportati e restituiti negli array dei tipi di indirizzo e dei tipi di componenti dell'indirizzo:
| Tipo di indirizzo | Descrizione |
|---|---|
street_address |
Un indirizzo preciso. |
route |
Un percorso con nome (ad es. "US 101"). |
intersection |
Un incrocio importante, di solito tra due strade principali. |
political |
Un'entità politica. In genere, questo tipo indica un poligono di un'amministrazione civile. |
country |
L'entità politica nazionale, in genere il tipo di ordine più elevato restituito dal geocodificatore. |
administrative_area_level_1 |
Una divisione amministrativa principale al di sotto del livello paese. Negli Stati Uniti, questi livelli amministrativi sono gli stati. Non tutte le nazioni utilizzano questi livelli amministrativi. Nella maggior parte dei casi, i nomi brevi administrative_area_level_1 corrispondono esattamente alle suddivisioni ISO 3166-2 e ad altri elenchi ampiamente diffusi; tuttavia, questo non è garantito, poiché i nostri risultati di geocodifica si basano su una serie di indicatori e dati sulla posizione. |
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. Non tutte le nazioni utilizzano questi livelli amministrativi. |
administrative_area_level_3 |
Una divisione amministrativa di terzo livello al di sotto del livello paese. Questo tipo indica una divisione civile minore. Non tutte le nazioni utilizzano questi livelli amministrativi. |
administrative_area_level_4 |
Una divisione amministrativa di quarto livello al di sotto del livello paese. Questo tipo indica una divisione civile minore. Non tutte le nazioni utilizzano questi livelli amministrativi. |
administrative_area_level_5 |
Una divisione amministrativa di quinto livello al di sotto del livello paese. Questo tipo indica una divisione civile minore. Non tutte le nazioni utilizzano questi livelli amministrativi. |
administrative_area_level_6 |
Una divisione amministrativa di sesto livello al di sotto del livello paese. Questo tipo indica una divisione civile minore. Non tutte le nazioni utilizzano questi livelli amministrativi. |
administrative_area_level_7 |
Una divisione amministrativa di settimo livello al di sotto del livello paese. Questo tipo indica una divisione civile minore. Non tutte le nazioni utilizzano questi livelli amministrativi. |
colloquial_area |
Un nome alternativo comunemente utilizzato per l'entità. |
locality |
Un'entità politica di una città o un comune incorporato. |
sublocality |
Una divisione amministrativa principale al di sotto di una località. Per alcune località, potresti ricevere uno dei tipi aggiuntivi: da sublocality_level_1 a sublocality_level_5. Ogni livello di località secondaria è un'entità civile. I numeri più grandi indicano un'area geografica più piccola. |
neighborhood |
Un quartiere con un nome. |
premise |
Una località con un nome, in genere un edificio o un insieme di edifici con un nome comune. |
subpremise |
Un'entità indirizzabile al di sotto del livello dell'edificio, ad esempio un appartamento, un'unità o una suite. |
plus_code |
Un riferimento di località codificato, derivato da latitudine e longitudine. I Plus Code possono essere utilizzati in sostituzione delle vie nei luoghi in cui non esistono (dove gli edifici non sono numerati o le strade non hanno un nome). Per maggiori dettagli, visita la pagina https://plus.codes. |
postal_code |
Un codice postale utilizzato per la spedizione della posta tradizionale nel paese. |
natural_feature |
Un elemento naturale di rilievo. |
airport |
Un aeroporto. |
park |
Un parco con un nome. |
point_of_interest |
Un punto d'interesse con un nome. In genere, questi "PDI" sono entità locali importanti che non rientrano facilmente in un'altra categoria, come "Empire State Building" o "Torre Eiffel". |
Un elenco vuoto di tipi indica che non esistono tipi noti per il componente dell'indirizzo specifico (ad esempio, Lieu-dit in Francia).
Oltre a quanto sopra, i componenti dell'indirizzo possono includere i tipi elencati di seguito.
| Tipo di componente dell'indirizzo | Descrizione |
|---|---|
floor |
Il piano di un indirizzo di un edificio. |
establishment |
In genere, un luogo che non è stato ancora classificato. |
landmark |
Un luogo nelle vicinanze utilizzato come riferimento per facilitare la navigazione. |
point_of_interest |
Un punto d'interesse con un nome. |
parking |
Un parcheggio o una struttura per parcheggiare l'auto. |
post_box |
Una casella postale specifica. |
postal_town |
Un raggruppamento di aree geografiche, come locality e sublocality, utilizzato per gli indirizzi postali in alcuni paesi. |
room |
La stanza di un indirizzo di un edificio. |
street_number |
Il numero civico preciso. |
bus_station, train_station e transit_station |
La posizione di una fermata dell'autobus, del treno o del trasporto pubblico. |
Bias dell'area visibile
In una richiesta di geocodifica, puoi indicare al servizio di geocodifica di preferire i risultati all'interno di una determinata area visibile (espressa come riquadro di delimitazione). Per farlo, imposta il parametro bounds nell'URL della richiesta.
Il parametro bounds definisce le coordinate di latitudine/longitudine degli angoli sud-ovest e nord-est di questo riquadro di delimitazione utilizzando un carattere pipe (|) per separare le coordinate.
Ad esempio, un geocodice per "Washington" in genere restituisce lo stato di Washington negli Stati Uniti:
Richiesta:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
Risposta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
Tuttavia, l'aggiunta di un argomento bounds che definisce un riquadro di delimitazione intorno alla parte nord-orientale degli Stati Uniti fa sì che questo geocodice restituisca la città di Washington, D.C.:
Richiesta:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
Risposta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Bias della regione
In una richiesta di geocodifica, puoi indicare al servizio di geocodifica di restituire risultati con differenziazione dei risultati verso una determinata regione utilizzando il parametro region. Questo parametro accetta un argomento ccTLD (dominio di primo livello nazionale) che specifica l'influenza della regione. La maggior parte dei codici ccTLD è identica ai codici ISO 3166-1, con alcune eccezioni degne di nota. Ad esempio, il ccTLD del Regno Unito è "uk " (.co.uk), mentre il suo codice ISO 3166-1 è"gb " (tecnicamente per l'entità "Regno Unito di Gran Bretagna e Irlanda del Nord").
I risultati della geocodifica possono essere influenzati per ogni dominio in cui l'applicazione principale di Google Maps viene lanciata ufficialmente. Tieni presente che la selezione preferenziale preferisce solo i risultati per un dominio specifico; se esistono risultati più pertinenti al di fuori di questo dominio, potrebbero essere inclusi.
Ad esempio, un geocodice per "Toledo" restituisce questo risultato, poiché il dominio predefinito per l'API Geocoding è impostato sugli Stati Uniti. Richiesta:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
Risposta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Una richiesta di geocodifica per "Toledo" con region=es (Spagna) restituirà la città spagnola.
Richiesta:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
Risposta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Toledo",
"short_name" : "TO",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Filtro dei componenti
In una risposta di geocodifica, l'API Geocoding può restituire risultati relativi agli indirizzi limitati a un'area specifica. Puoi specificare la limitazione utilizzando il filtro components. Un filtro è costituito da un elenco di coppie component:value separate da una barra verticale (|). I valori dei filtri supportano gli stessi metodi di correzione ortografica e corrispondenza parziale delle altre richieste di geocodifica. Se il geocodificatore trova una corrispondenza parziale per un filtro dei componenti, la risposta conterrà un campo partial_match.
I components che possono essere filtrati includono:
postal_codecorrisponde apostal_codeepostal_code_prefix.countrycorrisponde a un nome di paese o a un codice paese ISO 3166-1 di due lettere. L'API segue lo standard ISO per la definizione dei paesi e il filtro funziona meglio quando si utilizza il codice ISO corrispondente del paese.
I seguenti components possono essere utilizzati per influenzare i risultati, ma non verranno applicati:
routecorrisponde al nome lungo o breve di un percorso.localitycorrisponde ai tipilocalityesublocality.administrative_areacorrisponde a tutti i livelliadministrative_area.
Note sui filtri dei componenti:
- Non ripetere questi filtri dei componenti nelle richieste, altrimenti l'API restituirà
Invalid_request:country,postal_code,route - Se la richiesta contiene filtri dei componenti ripetuti, l'API li valuta come AND, non come OR.
- I risultati sono coerenti con Google Maps, che occasionalmente restituisce risposte
ZERO_RESULTSimpreviste. L'utilizzo di Place Autocomplete potrebbe fornire risultati migliori in alcuni casi d'uso. Per saperne di più, consulta queste domande frequenti. - Ogni componente dell'indirizzo deve essere specificato nel parametro
addresso in un filtrocomponents, ma non in entrambi. Se specifichi gli stessi valori in entrambi i campi, potresti ricevere un erroreZERO_RESULTS.
Un geocodice per "High St, Hastings" con components=country:GB restituisce un risultato
a Hastings, in Inghilterra, anziché a Hastings-On-Hudson, negli Stati Uniti.
Richiesta:
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
Risposta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
Una richiesta di geocodifica per la località "Santa Cruz" con components=country:ES
restituisce Santa Cruz de Tenerife nelle Isole Canarie, in Spagna.
Richiesta:
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
Risposta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "Santa Cruz de Tenerife",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Santa Cruz de Tenerife, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
},
"location" : {
"lat" : 28.4636296,
"lng" : -16.2518467
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
}
},
"place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Il filtro dei componenti restituisce una risposta ZERO_RESULTS solo se fornisci filtri che si escludono a vicenda.
Richiesta:
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
Risposta:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
Puoi eseguire query valide senza il parametro address, utilizzando il filtro components. (Quando esegui la geocodifica di un indirizzo completo, il parametro address è obbligatorio se la richiesta contiene i nomi e i numeri degli edifici.)
Richiesta:
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
Risposta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}