Richiesta
Una richiesta all'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
È necessario HTTPS.
Alcuni parametri sono obbligatori, mentre altri sono facoltativi. Come standard negli URL,
i parametri sono separati utilizzando il carattere e commerciale (&).
Il resto di questa pagina descrive la geocodifica e la geocodifica inversa separatamente, perché sono disponibili parametri diversi per ogni tipo di richiesta.
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 delle quote. Scopri come ottenere una chiave.In una richiesta devi specificare
addressocomponentso entrambi:address: l'indirizzo o il plus code che vuoi geocodificare. Specifica gli indirizzi in conformità al formato utilizzato dal servizio postale nazionale del paese interessato. Elementi aggiuntivi dell'indirizzo come nomi di attività e numeri di unità, appartamenti o piani devono essere evitati. Gli elementi dell'indirizzo devono essere delimitati da spazi (qui mostrati con codifica URL per%20):address=24%20Sussex%20Drive%20Ottawa%20ON
Formatta i codici plus come mostrato qui (i segni più sono codificati in URL per%2Be gli spazi sono codificati in URL per%20):- Il codice globale è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9 è
849VCWC8%2BR9). - Il codice composto è un codice locale di almeno 6 caratteri con una località esplicita (CWC8+R9 Mountain View, CA, USA è
CWC8%2BR9%20Mountain%20View%20CA%20USA).
- Il 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 del filtro dei componenti è costituito da una coppiacomponent:valuee limita completamente i risultati del geocodificatore. Di seguito sono riportate ulteriori informazioni sul filtro dei componenti.
Per ulteriori indicazioni, consulta le Domande frequenti.
Parametri facoltativi in una richiesta di geocodifica:
bounds: la casella delimitante dell'area visibile all'interno della quale applicare un bias ai risultati di geocodifica in modo più evidente. Questo parametro influirà solo sui risultati del geocodificatore, senza limitarli completamente. Per ulteriori informazioni, consulta la sezione Bias del viewport 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'Accept-Languageheader o la lingua nativa del dominio da cui viene inviata la richiesta. - Il geocodificatore fa del suo meglio per fornire un indirizzo stradale ben leggibile sia per l'utente sia per i residenti. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in un script 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ù simile.
- 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 possono essere validi in una lingua, ma non in un'altra. Ad esempio, utca e tér sono sinonimi di strada e piazza, rispettivamente, in ungherese.
region: il codice regione, specificato come valore di due caratteri di un ccTLD ("dominio di primo livello"). Questo parametro influisce solo su alcuni risultati del geocodificatore, senza limitarli completamente. Per maggiori informazioni, consulta Bias di regione 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 del filtro dei componenti è costituito da una coppiacomponent:valuee limita completamente i risultati del geocodificatore. Di seguito sono riportate ulteriori informazioni sul filtro dei componenti.extra_computations: utilizza questo parametro per specificare le seguenti funzionalità aggiuntive nella risposta:ADDRESS_DESCRIPTORS: per ulteriori dettagli, consulta i descrittori di indirizzo.BUILDING_AND_ENTRANCES: per maggiori dettagli, consulta la sezione su ingressi e contorni 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 in formato JSON per impostazione predefinita.
In questo esempio, l'API Geocoding richiede una risposta 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 principali:
"status"contiene i metadati della richiesta. Consulta Codici stato di seguito."results"contiene un array di informazioni sull'indirizzo geocodificato e sulla geometria.
In genere, per le ricerche di indirizzi viene restituita una sola voce nell'array "results", anche se il geocodificatore può restituire più risultati quando le query sull'indirizzo 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 è composta da un singolo
<GeocodeResponse> e da due elementi di primo livello:
<status>contiene i metadati della richiesta. Consulta Codici stato di seguito.- Zero o più elementi
<result>, ciascuno contenente un singolo insieme di informazioni sull'indirizzo geocodificato e sulla geometria.
La risposta XML è notevolmente più lunga della risposta JSON. Per questo motivo, ti consigliamo di utilizzare json come indicatore di output preferito, a meno che il tuo servizio non richieda xml per qualche motivo.
Inoltre, l'elaborazione delle strutture XML richiede un po' di attenzione, in modo da fare riferimento ai nodi e agli elementi appropriati. Consulta
Analisi XML con XPath per alcuni pattern di progettazione consigliati per l'elaborazione dell'output.
- I risultati XML sono racchiusi in un elemento principale
<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 matrici vuote in JSON, ma dall'assenza di un elemento simile 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 della risposta di geocodifica contiene lo stato della richiesta e potrebbe contenere informazioni di debug per aiutarti a capire perché il geocoding non funziona. Il campo "status" può contenere i seguenti valori:
"OK"indica che non si sono verificati errori; l'indirizzo è stato analizzato correttamente e almeno un codice geografico è stato restituito."ZERO_RESULTS"indica che il codice geografico è andato a buon fine, ma non ha restituito risultati. Ciò può verificarsi se al geocodificatore è stato passato unaddressinesistente.OVER_DAILY_LIMITindica una delle seguenti condizioni:- La chiave API è mancante o non valida.
- La fatturazione non è stata attivata 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.- In genere,
"INVALID_REQUEST"indica che la query (address,componentsolatlng) non è presente. "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 provi di nuovo.
Messaggi di errore
Quando il geocodificatore restituisce un codice di stato diverso da OK, all'interno dell'oggetto di risposta di geocodifica potrebbe essere presente un altro campo error_message. Questo campo contiene informazioni più dettagliate sui motivi alla base del codice di stato specificato.
Risultati
Quando il geocodificatore restituisce 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 codice geografico di "Chicago" restituisce "località", che indica che "Chicago" è una città, e restituisce anche "politico", che indica che si tratta di un'entità politica. I componenti potrebbero avere un array di tipi vuoto se non sono presenti 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 componenti dell'indirizzo. formatted_addressè una stringa contenente l'indirizzo in formato leggibile di questa stazione di ricarica.Spesso questo indirizzo è equivalente all'indirizzo postale. Tieni presente che alcuni paesi, come il Regno Unito, non consentono la distribuzione di indirizzi postali veri a causa di limitazioni relative alle 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 USA).
Non analizzare l'indirizzo formattato tramite programmazione. 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 componenti distinti 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. Consulta l'elenco dei tipi supportati.long_nameè la descrizione completa del testo o il nome del componente dell'indirizzo restituito dal geocodificatore.short_nameè un nome testuale abbreviato per l'elemento dell'indirizzo, se disponibile. Ad esempio, un componente dell'indirizzo per lo stato dell'Alaska potrebbe avere unlong_namedi "Alaska" e unshort_namedi "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, a parte 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 invariato 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 essere mancante in una risposta successiva.
Per gestire l'array di componenti, devi analizzare la risposta e selezionare i valori appropriati tramite espressioni. Consulta la guida all' analisi di una risposta.
postcode_localities[]è un array che indica fino a 100 località contenute in un codice postale. È presente solo quando il risultato è un codice postale che contiene più località.geometrycontiene le seguenti informazioni:locationcontiene il valore geocodificato della latitudine e della longitudine. Per le normali ricerche di indirizzi, questo campo è in genere il più importante.location_typememorizza dati aggiuntivi sulla località specificata. Al momento sono supportati i seguenti valori:"ROOFTOP"indica che il risultato restituito è un codice geografico preciso per il quale sono disponibili informazioni sulla posizione precise fino all'indirizzo."RANGE_INTERPOLATED"indica che il risultato restituito riflette un' approssimazione (di solito su una strada) interpolata tra due punti precisi (ad esempio incroci). I risultati interpolati vengono generalmente restituiti quando i codici geografici dei tetti non sono disponibili per un indirizzo."GEOMETRIC_CENTER"indica che il risultato restituito è il centro geometrico di un risultato come un 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 latitudine,longitudine che definisconosouthwestenortheastil angolo della scatola delimitante dell'area visibile. In genere, la visualizzazione viene utilizzata per inquadrare un risultato quando viene mostrato a un utente.bounds(restituito facoltativamente) memorizza la bounding box che può contenere completamente il risultato restituito. Tieni presente che questi limiti potrebbero non corrispondere al viewport consigliato. Ad esempio, San Francisco include le isole Farallon, che tecnicamente fanno parte della città, ma probabilmente non dovrebbero essere restituite nel viewport.
-
plus_code(vedi Open Location Code e plus code) è un riferimento di posizione codificato, ricavato 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 più piccola. I plus code possono essere utilizzati al posto 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 codici Plus.Quando il servizio restituisce un codice Plus, questo è formattato come codice globale e codice composto:
global_codeè un codice area di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9).compound_codeè un codice locale di almeno 6 caratteri con una località esplicita (CWC8+R9, Mountain View, CA, USA). Non analizzare questi contenuti tramite programmazione.
-
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 gli indirizzi che non esistono nella località specificata nella richiesta. Possono essere riportate anche corrispondenze parziali 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 sia per Henrietta Street. Tieni presente che se una richiesta include un componente dell'indirizzo scritto male, il servizio di geocodifica potrebbe suggerire un indirizzo alternativo. Anche i suggerimenti attivati in questo modo verranno contrassegnati 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, ad esempio numero di telefono, orario di apertura, recensioni degli utenti e altro ancora. Consulta la panoramica dell'ID luogo.
Punti di navigazione
Il camponavigation_points all'interno della risposta di geocodifica contiene un elenco
di punti utili per raggiungere il luogo. Nello specifico, devono essere utilizzati come punti di partenza o di arrivo per i percorsi su una rete stradale da o verso il luogo. Ogni punto di navigazione contiene i seguenti valori:
locationcontiene il valore di latitudine e longitudine del punto di navigazione. Questa posizione sarà sempre molto vicina alla rete stradale e rappresenta un punto di partenza o di arrivo ideale per raggiungere e partire da un luogo. Il punto è intenzionalmente leggermente spostato dalla linea di mezzeria della strada per contrassegnare chiaramente il lato della strada in cui si trova il luogo.restricted_travel_modesè un elenco di modalità di viaggio da cui non è possibile accedere al punto di navigazione:"DRIVE"è la modalità di viaggio corrispondente alle indicazioni stradali."WALK"è la modalità di viaggio corrispondente alle indicazioni a piedi.
Tipi di indirizzi e tipi di componenti di indirizzi
L'array types[] nel risultato indica il
tipo di indirizzo. Esempi di tipi di indirizzi includono un indirizzo, un paese o un'entità politica. In address_components[] è presente anche un array types[] che indica il tipo di ogni parte dell'indirizzo. Alcuni esempi sono il numero civico o il paese. Di seguito è riportato un elenco completo dei tipi. Gli indirizzi possono avere più tipi. I tipi possono essere considerati "tag".
Ad esempio, molte città sono contrassegnate con il tipo political e locality.
I seguenti tipi sono supportati e restituiti dal geocodificatore sia nell'array di tipi di indirizzi sia nell'array di tipi di componenti dell'indirizzo:
street_addressindica un indirizzo stradale preciso.routeindica un percorso denominato (ad es. "US 101").intersectionindica un incrocio importante, in genere di due strade principali.politicalindica un'entità politica. In genere, questo tipo indica un poligono di un'amministrazione civile.countryindica l'entità politica nazionale ed è tipicamente il tipo di ordine più elevato restituito dal geocodificatore.administrative_area_level_1indica un'entità civile di primo ordine al di sotto del livello di paese. Negli Stati Uniti, questi livelli amministrativi sono gli stati. Non tutti i paesi presentano questi livelli amministrativi. Nella maggior parte dei casi, i nomi brevi di administrative_area_level_1 corrispondono quasi esattamente alle suddivisioni ISO 3166-2 e ad altri elenchi molto diffusi. Tuttavia, non è garantito, in quanto i risultati del nostro geocodificamento si basano su una serie di indicatori e dati sulla posizione.administrative_area_level_2indica un'entità civile di secondo ordine al di sotto del livello del paese. Negli Stati Uniti, questi livelli amministrativi sono le contee. Non tutti i paesi presentano questi livelli amministrativi.administrative_area_level_3indica un'entità civile di terzo ordine al di sotto del livello di paese. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.administrative_area_level_4indica una persona giuridica civile di quarto ordine al di sotto del livello di paese. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.administrative_area_level_5indica un'entità civile di quinto ordine al di sotto del livello di paese. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.administrative_area_level_6indica un'entità civile di sesto ordine al di sotto del livello del paese. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.administrative_area_level_7indica un'entità civile di settimo ordine al di sotto del livello di paese. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.colloquial_areaindica un nome alternativo di uso comune per l'entità.localityindica un'entità politica costituita come città o paese.sublocalityindica un'entità civile di primo ordine al di sotto di una località. Per alcune località potrebbe essere visualizzato uno dei seguenti tipi aggiuntivi:sublocality_level_1asublocality_level_5. Ogni livello di località secondaria è un'entità civile. Numeri più grandi indicano un'area geografica più piccola.neighborhoodindica un quartiere denominato.premiseindica una località con nome, in genere un edificio o un insieme di edifici con un nome comune.subpremiseindica un'entità indirizzabile al di sotto del livello della struttura, ad esempio un appartamento, un'unità o una suite.plus_codeindica un riferimento alla posizione codificato, ricavato dalla latitudine e dalla longitudine. I Plus Code possono essere utilizzati al posto degli indirizzi in 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_codeindica un codice postale utilizzato per la spedizione della posta tradizionale all'interno del paese.natural_featureindica una caratteristica naturale prominente.airportindica un aeroporto.parkindica un parco denominato.point_of_interestindica un punto di interesse denominato. In genere, questi "PDV" sono entità locali di spicco che non rientrano facilmente in un'altra categoria, come "Empire State Building" o "Torre Eiffel".
Un elenco vuoto di tipi indica che non sono presenti tipi noti per il particolare componente dell'indirizzo, ad esempio Lieu-dit in Francia.
Oltre a quanto indicato sopra, i componenti dell'indirizzo possono includere i tipi elencati di seguito. Questo elenco non è esaustivo ed è soggetto a modifiche.
floorindica il piano di un indirizzo dell'edificio.establishmentindica in genere un luogo che non è stato ancora classificato.landmarkindica un luogo nelle vicinanze utilizzato come riferimento per agevolare la navigazione.point_of_interestindica un punto di interesse denominato.parkingindica un parcheggio o un'area di parcheggio.post_boxindica una cassetta postale specifica.postal_townindica un raggruppamento di aree geografiche, ad esempiolocalityesublocality, utilizzato per gli indirizzi postali in alcuni paesi.roomindica la stanza di un indirizzo dell'edificio.street_numberindica il numero civico esatto.bus_station,train_stationetransit_stationindicano la posizione di una fermata di autobus, treno o trasporto pubblico.
Bias dell'area visibile
In una richiesta di geocodifica, puoi indicare al servizio di geocodifica di dare la preferenza ai risultati all'interno di un determinato viewport (espresso come una casella delimitante). Puoi farlo
nell'URL della richiesta impostando il parametro bounds.
Il parametro bounds definisce le coordinate di latitudine/longitudine
degli angoli sud-ovest e nord-est di questa area delimitata utilizzando un carattere barra verticale
(|) per separare le coordinate.
Ad esempio, un codice geografico per "Washington" restituisce in genere lo stato americano di Washington:
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-est degli Stati Uniti fa sì che questo codice geografico restituisca la città di Washington DC:
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"
}
Differenziazione della regione
In una richiesta di geocodifica, puoi indicare al servizio di geocodifica di restituire risultati orientati a una determinata regione utilizzando il parametro region. Questo parametro accetta un argomento ccTLD (dominio di primo livello con codice paese) che specifica la distorsione della regione. La maggior parte dei codici ccTLD è identica ai codici ISO 3166-1, con alcune eccezioni notevoli. Ad esempio, il TLD di primo livello del Regno Unito è "uk " (.co.uk), mentre il codice ISO 3166-1 è"gb " (tecnicamente per l'entità "Regno Unito di Gran Bretagna e Irlanda del Nord").
I risultati della geocodifica possono essere sbilanciati per ogni dominio in cui è stata lanciata ufficialmente l'applicazione principale di Google Maps. Tieni presente che l'applicazione di un bias preferisce i risultati per un dominio specifico. Se esistono risultati più pertinenti al di fuori di questo dominio, possono essere inclusi.
Ad esempio, un codice geografico 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 di due lettere ISO 3166-1. L'API segue lo standard ISO per la definizione dei paesi e il filtraggio funziona al meglio se 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 sul filtro 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 OR.
- I risultati sono coerenti con Google Maps, che a volte genera risposte
ZERO_RESULTSinaspettate. L'utilizzo di Place Autocomplete potrebbe fornire risultati migliori in alcuni casi d'uso. Per saperne di più, consulta queste domande frequenti. - Per ogni componente dell'indirizzo, specificalo nel parametro
addresso in un filtrocomponents, ma non in entrambi. La specifica degli stessi valori in entrambi può comportareZERO_RESULTS.
Un codice geografico 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 indirizzo utilizzando il
components filtro. Quando esegui il geocoding 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"
}