Risorse richieste:
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
HTTPS è obbligatorio per le richieste che utilizzano una chiave API.
Alcuni parametri sono obbligatori, mentre altri sono facoltativi. Come per gli URL, i parametri vengono separati utilizzando la e commerciale (&).
Il resto della pagina descrive separatamente la geocodifica e la geocodifica inversa, perché 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 conformità con il formato utilizzato dal servizio postale nazionale del paese interessato. È consigliabile evitare elementi aggiuntivi dell'indirizzo, come nomi delle attività e numeri di unità o di piani. Gli elementi dell'indirizzo civico devono essere delimitati da spazi (mostrati qui come escape tramite URL a%20):address=24%20Sussex%20Drive%20Ottawa%20ON
Formato i plus code come mostrato qui (i segni più vengono sottoposti a escape tramite URL in%2Be gli spazi vengono sottoposti a escape tramite URL in%20):- Il codice globale è un prefisso di 4 caratteri e il codice locale di almeno 6 caratteri (849VCWC8+R9 è
849VCWC8%2BR9). - code 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: 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 al geocodificatore. Consulta ulteriori informazioni sul filtro dei componenti di seguito.- Il codice globale è un prefisso di 4 caratteri e il codice locale di almeno 6 caratteri (849VCWC8+R9 è
key: la chiave API della tua applicazione. Questa chiave identifica l'applicazione ai fini della gestione della quota. Scopri come ottenere una chiave.
Consulta le Domande frequenti per ulteriori indicazioni.
Parametri facoltativi in una richiesta di geocodifica:
bounds: il riquadro di delimitazione dell'area visibile all'interno del quale eseguire una polarizzazione dei risultati di geocodifica in modo più evidente. Questo parametro influisce solo sui risultati del geocodificatore, non di quelli completamente limitati. 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. Poiché Google aggiorna spesso le lingue supportate, questo elenco potrebbe non essere esaustivo.
- Se il criterio
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 che per i locali. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, se necessario, trascritta in uno script leggibile dall'utente, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. Tutti i componenti dell'indirizzo vengono restituiti nella stessa lingua, scelta dal primo componente.
- Se il nome non è disponibile nella lingua preferita, il geocodificatore utilizza la corrispondenza più vicina.
- Il linguaggio preferito 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 dei 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 per la strada e la piazza rispettivamente in ungherese.
region: il codice della regione, specificato come valore di due caratteri ccTLD ("dominio di primo livello"). Questo parametro influisce solo sui risultati del geocodificatore, non limitandoli. Per saperne di più, consulta la Polarizzazione dell'area geografica di seguito. Il parametro può influire anche sui risultati in base alle leggi vigenti.components: filtro di 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 al geocodificatore. Consulta ulteriori informazioni sul filtro dei componenti di seguito.
Risposte
Le risposte di geocodifica vengono restituite nel formato indicato dal flag output
nella richiesta di URL o nel formato JSON per impostazione predefinita.
In questo esempio, l'API Geocoding richiede una risposta json per una query sul luogo ID "ChIJeRpOeF67j4AR9ydy_PIzPuM". Questo ID luogo è per l'edificio all'indirizzo 1600 Amphitheatre Parkway, Mountain View, CA, USA.
La richiesta dimostra l'utilizzo del flag JSON output:
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
La richiesta dimostra l'uso del flag XML output:
https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
Seleziona le schede di seguito per vedere esempi di risposte JSON e XML.
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 Codici di stato di seguito."results"contiene un array di informazioni indirizzo geocodificato e informazioni geometriche.
In genere, per le ricerche di indirizzi viene restituita una sola voce dell'array "results",ma il geocodificatore potrebbe restituire risultati diversi in presenza di query 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 solo elemento <GeocodeResponse> e da due elementi di primo livello:
<status>contiene metadati nella richiesta. Consulta Codici di stato di seguito.- Zero o più elementi
<result>, ciascuno contenente un singolo insieme di informazioni geometriche e di indirizzi degli indirizzi.
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 attenzione, per consentirti di fare riferimento a nodi ed elementi appropriati. Consulta la pagina
Analisi di XML con XPath per alcuni pattern di progettazione consigliati per l'elaborazione degli output.
- I risultati XML vengono inseriti in un elemento
<GeocodeResponse>principale. - JSON indica le voci con più elementi in base a array al plurale (
types), mentre XML indica queste ultime utilizzando più elementi singolari (<type>). - Gli elementi vuoti sono indicati tramite array vuoti in JSON, ma grazie all'assenza di tali elementi in XML. Una risposta che non genera risultati restituirà un array
resultsvuoto in JSON, ma nessun elemento<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 per aiutarti a 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 il codice geografico è riuscito, ma non ha restituito risultati. Questo può succedere se il geocodificatore ha trasmesso unaddressinesistente.OVER_DAILY_LIMITindica uno dei seguenti valori:- La chiave API risulta mancante o non valida.
- La fatturazione non è stata attivata sul tuo account.
- È stato superato il limite di utilizzo autoimpostato.
- Il metodo di pagamento indicato 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.- Generalmente
"INVALID_REQUEST"indica che la query (address,componentsolatlng) è mancante. "UNKNOWN_ERROR"indica che non è stato possibile elaborare la richiesta a causa di un errore del server. Se provi di nuovo, la richiesta potrebbe avere esito positivo.
Messaggi di errore
Quando il geocodificatore restituisce un codice di stato diverso da OK, potrebbe essere presente un campo error_message aggiuntivo nell'oggetto di risposta Geocodifica. Questo campo contiene informazioni più dettagliate sui motivi alla base del codice di stato specificato.
Risultati
Quando restituisce i risultati, il geocodificatore li inserisce all'interno di 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 del risultato restituito. Questo array contiene un insieme di zero o più tag che identificano il tipo di funzionalità restituita nel risultato. Ad esempio, un codice geografico di "Chicago" restituisce "località" che indica che "Chicago" è una città e restituisce anche "politica" che indica che si tratta di un'entità politica. I componenti potrebbero avere un array di tipi vuoto quando non sono presenti tipi noti per il componente dell'indirizzo. L'API potrebbe aggiungere nuovi valori del tipo, se necessario. Per saperne di più, vedi Tipi di indirizzi e 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 degli indirizzi postali veri a causa di limitazioni relative alle licenze.
L'indirizzo formattato è logicamente composto da uno o più componenti dell'indirizzo. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è costituito dai seguenti componenti: "111" (il numero della via), "8th Avenue" (il percorso), "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 includono la risposta dell'API oltre al campo dell'indirizzo formattato.
address_components[]è un array contenente i componenti distinti applicabili a questo indirizzo.In genere, ogni componente dell'indirizzo contiene i seguenti campi:
types[]è una matrice 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 Geocoder.short_nameè un nome testuale abbreviato per il componente dell'indirizzo, se disponibile. Ad esempio, un componente dell'indirizzo dello stato dell'Alaska potrebbe averelong_namecome "Alaska" e unshort_namein "AK" usando l'abbreviazione postale di due lettere.
Tieni presente i seguenti fatti relativi all'array
address_components[]:- La matrice dei componenti dell'indirizzo può contenere più componenti rispetto a
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 contenenti 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ò modificare la posizione nell'array. Il tipo di componente può cambiare. Un componente particolare potrebbe mancare in una risposta successiva.
Per gestire l'array dei 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 tutte le località contenute in un codice postale. È presente solo quando il risultato è un codice postale contenente più località.geometrycontiene le seguenti informazioni:locationcontiene la latitudine geocodificata e il valore della longitudine. Per le normali ricerche di indirizzo, 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 disponiamo di informazioni sulla posizione accurate fino alla precisione dell'indirizzo."RANGE_INTERPOLATED"indica che il risultato restituito riflette un'approssimazione (generale su una strada) interpolata tra due punti precisi (ad esempio incroci). I risultati interpolati vengono generalmente restituiti quando i codici geografici panoramici non sono disponibili per un indirizzo."GEOMETRIC_CENTER"indica che il risultato restituito è il centro geometrico di un risultato, ad esempio 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, specificato 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 lo si mostra a un utente.bounds(facoltativo) restituisce 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 sono tecnicamente parte della città, ma probabilmente non dovrebbero essere restituite nell'area visibile.
-
plus_code(vedi Apri codice posizione e più codici) è un riferimento per 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 in equatore) o inferiore. I plus code possono essere utilizzati per sostituire gli indirizzi stradali in luoghi in cui non esistono indirizzi (in cui 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 un codice globale e un 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 trovare una corrispondenza con una parte dell'indirizzo richiesto. Ti consigliamo di esaminare la richiesta originale per individuare errori di ortografia e/o un indirizzo incompleto.Nella maggior parte dei casi, le corrispondenze parziali si verificano per gli indirizzi stradali che non esistono nella località trasmessa nella richiesta. Le corrispondenze parziali possono anche essere restituite quando una richiesta corrisponde a due o più sedi 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. Anche i suggerimenti attivati in questo modo verranno contrassegnati come corrispondenze parziali.
place_idè un identificatore univoco che può essere utilizzato con altre API di Google. Ad esempio, potete utilizzareplace_idin una richiesta API Places per ricevere dettagli su un'attività locale, come numero di telefono, orari di apertura, recensioni degli utenti e altro ancora. Consulta la panoramica sull'ID luogo.
Tipi di indirizzi e tipi di componenti per indirizzi
La matrice types[] nel risultato indica il
tipo di indirizzo. Alcuni tipi di indirizzi sono: un indirizzo, un
paese o un'entità politica. È presente anche un array types[] in address_components[], che indica il tipo di ogni parte dell'indirizzo. Tra gli esempi ci sono il via 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 sia negli array dei tipi di indirizzi che di componenti:
street_addressindica un indirizzo esatto.routeindica un percorso denominato (ad esempio "US 101").intersectionindica un incrocio principale, generalmente di due strade principali.politicalindica un'entità politica. In genere, questo tipo indica un poligono di una qualche amministrazione civile.countryindica l'entità politica nazionale ed è in genere il tipo di ordine più alto restituito dal Geocoder.administrative_area_level_1indica una persona giuridica del primo ordine al di sotto del livello nazionale. All'interno degli Stati Uniti, questi livelli amministrativi sono stati definiti come stati. Non tutti i paesi presentano questi livelli amministrativi. Nella maggior parte dei casi, i nomi brevi di admin_area_level_1 corrisponderanno molto meglio alle suddivisioni ISO 3166-2 e ad altri elenchi diffusi; tuttavia, ciò non è garantito in quanto i nostri risultati di geocodifica si basano su una serie di indicatori e dati sulla posizione.administrative_area_level_2indica una persona giuridica del secondo ordine al di sotto del livello nazionale. Negli Stati Uniti, questi livelli amministrativi sono contee. Non tutti i paesi presentano questi livelli amministrativi.administrative_area_level_3indica una persona giuridica del terzo ordine al di sotto del livello nazionale. Questo tipo indica una divisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.administrative_area_level_4indica una persona giuridica del quarto ordine al di sotto del livello nazionale. Questo tipo indica una divisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.administrative_area_level_5indica una persona giuridica del quinto ordine al di sotto del livello nazionale. Questo tipo indica una divisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.administrative_area_level_6indica una persona giuridica del sesto ordine al di sotto del livello nazionale. Questo tipo indica una divisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.administrative_area_level_7indica una persona giuridica del settimo ordine al di sotto del livello nazionale. Questo tipo indica una divisione 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 da una città o da un'altra città.sublocalityindica una entità civile del primo ordine in una località. Per alcune località potrebbero essere presenti uno dei seguenti tipi aggiuntivi: dasublocality_level_1asublocality_level_5. Ogni livello di periferica è un'entità civile. I numeri più grandi indicano un'area geografica più piccola.neighborhoodindica un quartiere denominatopremiseindica una posizione denominata, in genere un edificio o una raccolta di edifici con un nome comunesubpremiseindica un'entità del primo ordine sotto una località denominata, in genere un edificio singolare all'interno di una raccolta di edifici con un nome comuneplus_codeindica un riferimento località codificato, derivato dalla latitudine e dalla longitudine. I plus code possono essere utilizzati per sostituire gli indirizzi in luoghi in cui non esistono (gli edifici non sono numerati o le strade non hanno un nome). Per informazioni dettagliate, consulta https://plus.codes.postal_codeindica un codice postale utilizzato per indirizzare la posta all'interno del paese.natural_featureindica una caratteristica naturale ben visibile.airportindica un aeroporto.parkindica un parco denominato.point_of_interestindica un punto di interesse denominato. In genere, questi "PDI" sono entità locali di spicco che non si adattano facilmente ad altre categorie, come "Empire State Building" o "Torre Eiffel".
Un elenco vuoto di tipi indica che non ci sono tipi noti per il componente dell'indirizzo particolare, ad esempio Lieu-dit in Francia.
Oltre a quanto descritto sopra, i componenti degli indirizzi possono includere i tipi elencati di seguito. 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 agevolare la navigazione.point_of_interestindica un punto di interesse denominato.parkingindica un parcheggio o una struttura di parcheggio.post_boxindica una casella 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 di un edificio.street_numberindica il numero esatto della via.bus_station,train_stationetransit_stationindicano la posizione di una fermata di autobus, treno o di 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 (espressi 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 un trattino
(|) per separare le coordinate.
Ad esempio, un codice geografico 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 definisca un riquadro di delimitazione nella parte nord-orientale degli Stati Uniti genera questo codice geografico che restituisce 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 della regione
In una richiesta di geocodifica, puoi indicare al servizio di geocodifica di restituire i risultati sottoposti a bias in una particolare regione utilizzando il parametro region. Questo parametro accetta un argomento ccTLD (dominio di primo livello con codice paese) che specifica il bias 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 codice ISO 3166-1 è"gb " (tecnicamente per l'entità "Regno Unito di Gran Bretagna e Irlanda del Nord").
I risultati relativi alla geocodifica possono essere influenzati da un bias per ogni dominio in cui l'applicazione Google Maps principale è stata lanciata ufficialmente. 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 di "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 di indirizzi limitati a un'area specifica. Puoi specificare la restrizione utilizzando il filtro components. Un filtro è costituito da un elenco di coppie component:value separate da una barra verticale (|). I valori di filtro supportano gli stessi metodi di correzione ortografica e di corrispondenza parziale di 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 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 viene utilizzato 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.localitycorrisponde ai tipi dilocalityesublocality.administrative_areacorrisponde a tutti i livelli diadministrative_area.
Note sul filtro dei componenti:
- Non ripetere questi filtri dei componenti nelle richieste perché l'API restituirà
Invalid_request:country,postal_code,route - Se la richiesta contiene filtri dei componenti ripetuti, l'API valuta questi filtri come AND, non come OR.
- I risultati sono coerenti con Google Maps, che a volte restituisce
risposte
ZERO_RESULTSimpreviste. L'utilizzo di Place Autocomplete potrebbe 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 entrambi. Se specifichi gli stessi valori in entrambi, potrebbe essere visualizzatoZERO_RESULTS.
Un codice geografico per "High St, Hastings" con components=country:GB restituisce un risultato a Hastings, Inghilterra anziché ad Hastings-On-Hudson, USA.
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, 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"
}
I filtri dei componenti restituiscono 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 effettuare query valide senza il parametro dell'indirizzo utilizzando il filtro components. (Quando si utilizza 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"
}