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 un output in XML
HTTPS è obbligatorio per le richieste che utilizzano una chiave API.
Alcuni parametri sono obbligatori, mentre altri sono facoltativi. Come avviene nello standard per gli URL, i parametri vengono separati utilizzando la e commerciale (&).
Il resto della pagina descrive separatamente la geocodifica e la geocodifica inversa, in quanto sono disponibili parametri diversi per ogni tipo di richiesta.
Parametri di geocodifica (ricerca di latitudine/longitudine)
Parametri obbligatori in una richiesta di geocodifica:
address: l'indirizzo o il plus code che vuoi geocodificare. Specifica gli indirizzi in base al formato utilizzato dal servizio postale nazionale del paese interessato. È consigliabile evitare elementi aggiuntivi relativi all'indirizzo, come nomi di attività e numeri di unità, suite o piano. Gli elementi dell'indirizzo devono essere delimitati da spazi (mostrati qui come caratteri di escape dell'URL in%20):address=24%20Sussex%20Drive%20Ottawa%20ON
Formato e codici aggiuntivi come mostrato qui (i segni più vengono preceduti da caratteri di escape negli URL in%2Be gli spazi vengono preceduti da URL di escape in%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
posizione esplicita (CWC8+R9 Mountain View, CA, USA è
CWC8%2BR9%20Mountain%20View%20CA%20USA).
--OR--
components: un filtro dei componenti con elementi separati da una barra verticale (|). Il filtro dei componenti è accettato anche come parametro facoltativo se viene fornito un elementoaddress. Ogni elemento nel filtro dei componenti è costituito da una coppiacomponent:valuee limita completamente i risultati del geocodificatore. Leggi ulteriori informazioni sul filtro dei componenti di seguito.- Il codice globale è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9 è
key: chiave API della tua applicazione. Questa chiave identifica l'applicazione ai fini della gestione della quota. Scopri come ottenere una chiave.
Per ulteriori indicazioni, consulta le Domande frequenti.
Parametri facoltativi in una richiesta di geocodifica:
bounds: il riquadro di delimitazione dell'area visibile all'interno del quale polarizzare i risultati geocodificati in modo più evidente. Questo parametro influenzerà solo i risultati del geocodificatore, ma non limiterà completamente i risultati. Per ulteriori informazioni, consulta la sezione Differenziazione dell'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 completo.
- 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 che sia leggibile sia per l'utente sia per le persone del posto. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in un testo leggibile dall'utente se necessario, osservando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo vengono tutti restituiti 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 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 quadrato in ungherese.
region: il codice regione, specificato come valore a due caratteri ccTLD ("dominio di primo livello"). Questo parametro influenzerà solo i risultati del geocodificatore, ma non li limiterà completamente. Per ulteriori informazioni, consulta la sezione Differenziazione delle regioni di seguito. Il parametro può influire sui risultati anche 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 includeaddress. Ogni elemento nel filtro dei componenti è costituito da una coppiacomponent:valuee limita completamente i risultati del geocodificatore. Leggi ulteriori informazioni sul filtro dei componenti di seguito.
Risposte
Le risposte di geocodifica vengono restituite nel formato indicato dal flag output all'interno della richiesta dell'URL oppure in formato JSON per impostazione predefinita.
In questo esempio, l'API Geocoding richiede una risposta json
per una query sull'ID luogo "ChIJeRpOeF67j4AR9ydy_PIzPuM". L'ID luogo è relativo all'edificio all'indirizzo 1600 Amphitheatre Parkway, Mountain View, CA.
Questa richiesta mostra l'utilizzo del flag output JSON:
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
Questa richiesta dimostra l'utilizzo del flag output XML:
https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&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"
]
}
],
"formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
"geometry": {
"location": {
"lat": 37.4224428,
"lng": -122.0842467
},
"location_type": "ROOFTOP",
"viewport": {
"northeast": {
"lat": 37.4239627802915,
"lng": -122.0829089197085
},
"southwest": {
"lat": 37.4212648197085,
"lng": -122.0856068802915
}
}
},
"place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
"plus_code": {
"compound_code": "CWC8+X8 Mountain View, CA",
"global_code": "849VCWC8+X8"
},
"types": [
"street_address"
]
}
],
"status": "OK"
}
Tieni presente che la risposta JSON contiene due elementi principali:
"status"contiene metadati nella richiesta. Consulta la sezione Codici di stato di seguito."results"contiene un array di informazioni sugli indirizzi geocodificati e informazioni sulla geometria.
In genere, viene restituita una sola voce nell'array "results" per le ricerche di indirizzi,anche se il geocodificatore può restituire diversi risultati quando le query sugli 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 è composta da un singolo
<GeocodeResponse> e da due elementi di primo livello:
<status>contiene metadati nella richiesta. Consulta la sezione Codici di stato di seguito.- Zero o più elementi
<result>, ciascuno contenente un singolo set di informazioni sugli indirizzi geocodificati e 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 di strutture XML richiede un po' di attenzione, in modo da poter fare riferimento a nodi ed elementi appropriati. Consulta
Analisi di XML con XPath per alcuni pattern di progettazione consigliati per l'elaborazione dell'output.
- I risultati XML sono aggregati in un elemento
<GeocodeResponse>principale. - JSON indica le voci con più elementi tramite array plurali (
types), mentre XML le denota utilizzando più elementi singolari (<type>). - Gli elementi vuoti vengono indicati tramite array vuoti in JSON, ma dall'assenza di questi elementi nel file XML. Una risposta che non genera risultati restituirà un array
resultsvuoto in JSON, ma non gli elementi<result>in XML, ad esempio.
Codici di stato
Il campo "status" all'interno dell'oggetto di risposta Geocoding contiene lo stato della richiesta e potrebbe contenere informazioni di debug che consentono di individuare il motivo per cui 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 e è stato restituito almeno un codice geografico."ZERO_RESULTS"indica che la geocodifica è riuscita, ma non ha restituito alcun risultato. Questo può accadere se al geocodificatore è stato trasmesso un codiceaddressinesistente.OVER_DAILY_LIMITindica una delle seguenti condizioni:- 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 questo problema.
"OVER_QUERY_LIMIT"indica che hai superato la quota."REQUEST_DENIED"indica che la tua richiesta è stata rifiutata."INVALID_REQUEST"in genere 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. Se riprovi, la richiesta potrebbe andare a buon fine.
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 di risposta Geocodifica. Questo campo contiene informazioni più
dettagliate sui motivi alla base 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 composte da zero o più elementi <result>.
Un risultato tipico contiene i seguenti campi:
- L'array
types[]indica il tipo di risultato restituito. Questo array contiene un insieme di zero o più tag che identificano il tipo di funzionalità restituito nel risultato. Ad esempio, un codice geografico di "Chicago" restituisce "località", che indica che "Chicago" è una città, e "politica", che indica che si tratta di un'entità politica. I componenti potrebbero avere un array di tipi vuoto quando non esistono tipi noti per quel componente di indirizzo. L'API potrebbe aggiungere nuovi valori di tipo secondo necessità. Per saperne di più, vedi Tipi di indirizzo e componenti degli indirizzi. formatted_addressè una stringa contenente l'indirizzo leggibile di questa sede.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 è logicamente composto da uno o più componenti indirizzo. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è costituito dai seguenti componenti: "111" (il numero civico), "8th Avenue" (il percorso), "New York" (la città) e "NY" (lo stato USA).
Non analizzare l'indirizzo formattato in modo programmatico. Devi invece utilizzare i singoli componenti dell'indirizzo, che la risposta dell'API include in aggiunta al campo indirizzo formattato.
address_components[]è un array contenente i componenti separati 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 di testo completa o il nome del componente dell'indirizzo come 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 può averelong_namedi "Alaska" eshort_namedi "AK" utilizzando l'abbreviazione postale a due lettere.
Tieni presente le seguenti informazioni relative all'array
address_components[]:- L'array di componenti degli indirizzi può contenere più componenti di
formatted_address. - L'array non include necessariamente tutte le entità politiche che contengono un indirizzo, oltre a quelle incluse in
formatted_address. Per recuperare tutte le entità politiche che contengono un indirizzo specifico, devi utilizzare la geocodifica inversa, trasmettendo 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. In una risposta successiva potrebbe mancare un componente specifico.
Per gestire l'array dei 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 tutte le 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 di latitudine e longitudine geocodificate. 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 codice geografico preciso per il quale disponiamo di informazioni sulla posizione accurate in base 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 codici geografici sui tetti 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 visualizzare il risultato restituito, con 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 lo viene mostrato a un utente.bounds(facoltativamente restituito) archivia 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 nell'area visibile.
-
plus_code(vedi Open Location Code e plus code) è un riferimento di località 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 in luoghi in cui gli indirizzi non sono presenti (ovvero dove gli edifici non sono numerati o le strade non hanno nomi). 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 6 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 è riuscita a far corrispondere una parte dell'indirizzo richiesto. Ti consigliamo di esaminare la richiesta originale per verificare la presenza di errori ortografici e/o un indirizzo incompleto.Nella maggior parte dei casi, le corrispondenze parziali si verificano per indirizzi che non esistono all'interno della località indicata nella richiesta. Le corrispondenze parziali possono essere restituite 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 errato, 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, come il numero di telefono, l'orario di apertura, le recensioni degli utenti e altro ancora. Vedi la panoramica su ID luogo.
Tipi di indirizzi e tipi di componenti degli indirizzi
L'array types[] nel risultato indica il
tipo di indirizzo. Esempi di tipi di indirizzi includono una via, 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 codificate con il tipo political e
locality.
I seguenti tipi sono supportati e restituiti dal geocodificatore nelle matrici di tipo indirizzo e tipo di componente indirizzo:
street_addressindica un indirizzo preciso.routeindica una route con nome (ad esempio "US 101").intersectionindica un incrocio principale, in genere due strade principali.politicalindica un'entità politica. In genere, questo tipo indica un poligono di un'amministrazione civile.countryindica l'entità politica nazionale e rappresenta in genere 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 stati. Non tutte le nazioni presentano questi livelli amministrativi. Nella maggior parte dei casi, i nomi brevi amministrativi_area_level_1 corrisponderanno strettamente alle suddivisioni ISO 3166-2 e ad altri elenchi diffusi; tuttavia, ciò non è garantito perché i nostri risultati di geocodifica si basano su una varietà di segnali e dati sulla posizione.administrative_area_level_2indica un'entità civile di secondo ordine inferiore al livello di paese. Negli Stati Uniti, questi livelli amministrativi sono contee. Non tutte le nazioni presentano questi livelli amministrativi.administrative_area_level_3indica un'entità civile di terzo ordine inferiore al livello di paese. Questo tipo indica una divisione civile minore. Non tutte le nazioni presentano questi livelli amministrativi.administrative_area_level_4indica un'entità civile di quarto ordine inferiore al paese. Questo tipo indica una divisione civile minore. Non tutte le nazioni presentano questi livelli amministrativi.administrative_area_level_5indica un'entità civile di quinto ordine inferiore al paese. Questo tipo indica una divisione civile minore. Non tutte le nazioni presentano questi livelli amministrativi.administrative_area_level_6indica un'entità civile di sesto ordine inferiore al paese. Questo tipo indica una divisione civile minore. Non tutte le nazioni presentano questi livelli amministrativi.administrative_area_level_7indica un'entità civile di settimo ordine inferiore al paese. Questo tipo indica una divisione civile minore. Non tutte le nazioni presentano questi livelli amministrativi.colloquial_areaindica un nome alternativo di uso comune per l'entità.localityindica un'entità politica di una città o di un comune incorporato.sublocalityindica un'entità civile di primo ordine sotto una località. Per alcune località potrebbe essere disponibile uno dei seguenti tipi aggiuntivi: dasublocality_level_1asublocality_level_5. Ogni livello di circoscrizione rappresenta un'entità civile. I numeri più grandi indicano un'area geografica più piccola.neighborhoodindica un quartiere denominatopremiseindica una località con nome, in genere un edificio o un insieme di edifici con un nome comunesubpremiseindica un'entità di primo ordine sotto una località con nome, in genere un singolo edificio all'interno di un insieme di edifici con un nome comune.plus_codeindica un riferimento della posizione codificato, derivato da latitudine e longitudine. I Plus Code possono essere utilizzati in sostituzione degli indirizzi stradali in luoghi in cui non esistono (dove gli edifici non sono numerati o le strade non hanno nomi). Vedi https://plus.codes per i dettagli.postal_codeindica un codice postale utilizzato per l'invio della posta all'interno del paese.natural_featureindica un elemento naturale in evidenza.airportindica un aeroporto.parkindica un parco denominato.point_of_interestindica un punto d'interesse con 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 di tipi vuoto 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 qui elencati. Questo elenco non è completo ed è soggetto a modifiche.
floorindica il piano dell'indirizzo di un edificio.establishmentin genere indica un luogo che non è stato ancora classificato.landmarkindica un luogo nelle vicinanze utilizzato come riferimento per facilitare la navigazione.point_of_interestindica un punto d'interesse con nome.parkingindica un parcheggio.post_boxindica una casella postale specifica.postal_townindica un raggruppamento di aree geografiche, comelocalityesublocality, utilizzato per gli indirizzi postali in alcuni paesi.roomindica la stanza dell'indirizzo di un edificio.street_numberindica il numero civico esatto.bus_station,train_stationetransit_stationindicano la posizione di una fermata di autobus, treno o trasporto pubblico.
Differenziazione 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
all'interno dell'URL della richiesta, imposta il parametro bounds.
Il parametro bounds definisce le coordinate di latitudine/longitudine
degli angoli sud-ovest e nord-est di questo riquadro di delimitazione utilizzando una barra verticale
(|) per separare le coordinate.
Ad esempio, un geocodificato per "Washington" in genere restituisce lo stato 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 nordorientale degli Stati Uniti fa sì che questo codice geografico 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"
}
Differenziazione per regione
In una richiesta di geocodifica, puoi indicare al servizio di geocodifica di restituire i risultati con bias in una determinata regione utilizzando il parametro region. Questo parametro utilizza un argomento ccTLD (dominio di primo livello per il codice paese) che specifica la differenziazione per regione. La maggior parte dei codici ccTLD sono identici ai codici ISO 3166-1, con alcune eccezioni degne di nota. Ad esempio, il ccTLD 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 di geocodifica possono essere differenziati per ogni dominio in cui è stata lanciata ufficialmente l'applicazione principale di Google Maps. Tieni presente che la differenziazione 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 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 Geocoding, l'API Geocoding può restituire risultati relativi agli indirizzi limitati a un'area specifica. Puoi specificare la restrizione utilizzando
il filtro components. Un filtro è costituito da un elenco di component:value coppie separate da una barra verticale (|). I valori del filtro supportano gli stessi metodi di correzione ortografica e di corrispondenza parziale delle altre richieste di geocodifica. Se il geocodificatore trova una corrispondenza parziale per un
filtro del componente, la risposta conterrà un campo partial_match.
Gli components che possono essere filtrati includono:
postal_codecorrisponde apostal_codeepostal_code_prefix.countrycorrisponde al nome di un 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.
Il seguente components può essere utilizzato per influenzare i risultati, ma non verrà applicato:
routecorrisponde al nome lungo o breve di un percorso.localitycorrispondenze con i tipilocalityesublocality.administrative_areacorrisponde a tutti i livelli diadministrative_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 di componenti ripetuti, l'API li valuta come AND, non OR.
- I risultati sono coerenti con Google Maps, che a volte restituisce
risposte
ZERO_RESULTSimpreviste. L'utilizzo di Place Autocomplete può fornire risultati migliori in alcuni casi d'uso. Per scoprire di più, consulta queste domande frequenti. - Per ogni componente dell'indirizzo, specificalo nel parametro
addresso in un filtrocomponents, ma non in entrambi. Se specifichi gli stessi valori in entrambi, potresti ottenereZERO_RESULTS.
Un codice geografico per "High St, Hastings" con components=country:GB
restituisce un risultato ad Hastings, in Inghilterra, anziché ad Hastings-On-Hudson, 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à di "Santa Cruz" con components=country:ES
restituisce Santa Cruz de Tenerife nelle Isole Canarie, 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 creare query valide senza il parametro dell'indirizzo utilizzando il filtro components. (quando geocodifica 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"
}