Richiesta
Una richiesta API Geocoding assume 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 JSON (JavaScript Object Notation); oxmlindica l'output in XML
HTTPS è obbligatorio.
Alcuni parametri sono obbligatori, mentre altri sono facoltativi. Come negli URL standard, i parametri vengono separati mediante il carattere della e commerciale (&).
Il resto di questa 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 nel formato utilizzato dal servizio postale nazionale del paese in questione. È necessario evitare elementi aggiuntivi dell'indirizzo come nomi dell'attività e numeri di unità, appartamento o piano. Gli elementi dell'indirizzo devono essere delimitati da spazi (qui riportati come URL con escape in%20):address=24%20Sussex%20Drive%20Ottawa%20ON
Formatta i plus code come mostrato qui (i segni più sono preceduti da un carattere di escape in%2Be gli spazi sono sottoposti a escape in%20):- Il codice globale è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9 è
849VCWC8%2BR9). - codice composto è un codice locale di almeno 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 viene accettato anche come parametro facoltativo se viene fornito un elementoaddress. Ogni elemento del filtro dei componenti è composto da una coppiacomponent:valuee limita completamente i risultati provenienti dal 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 dell'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 differenziare i risultati del geocodice in modo più evidente. Questo parametro influenzerà solo, non completamente, i risultati provenienti dal geocodificatore. 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 esaustivo.
- Se
languagenon viene fornito, il geocodificatore tenta di utilizzare la lingua preferita specificata nell'intestazioneAccept-Languageo la lingua nativa del dominio da cui viene inviata la richiesta. - Il geocodificatore fa del suo meglio per fornire un indirizzo civico leggibile sia per l'utente sia per la gente del posto. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in uno script leggibile dall'utente se necessario, osservando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo vengono restituiti 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 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 rispettivamente di strada e piazza in ungherese.
region: il codice regione, specificato come valore a due caratteri ccTLD ("dominio di primo livello"). Questo parametro influenzerà solo i risultati dal geocodificatore, non completamente. Per ulteriori informazioni, consulta la sezione Differenziazione per 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 includeaddress. Ogni elemento del filtro dei componenti è composto da una coppiacomponent:valuee limita completamente i risultati provenienti dal geocodificatore. Leggi ulteriori informazioni sul filtro dei componenti di seguito.extra_computations: l'unico valore consentito per questo parametro èADDRESS_DESCRIPTORS. Vedi i descrittori degli indirizzi per maggiori dettagli.
Risposte
Le risposte di geocodifica vengono restituite nel formato indicato dal flag output
nella richiesta dell'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 dimostra 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 dimostra 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 metadati nella richiesta. Consulta la sezione Codici di stato di seguito."results"contiene un array di informazioni sugli indirizzi e sulla geometria geocodificate.
In genere, per le ricerche di indirizzi viene restituita solo una voce nell'array "results", 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 insieme di informazioni geocodificate sugli indirizzi e informazioni sulla geometria.
La risposta XML è notevolmente più lunga di quella 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 delle strutture XML richiede una certa attenzione, in modo da fare riferimento
a nodi ed elementi corretti. Consulta
Analizzare 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 mediante matrici plurali (
types), mentre XML le indica utilizzando più elementi singolari (<type>). - Gli elementi vuoti sono indicati tramite array vuoti in JSON, ma dall'assenza di qualsiasi elemento di questo tipo 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" nell'oggetto di risposta Geocoding contiene lo stato
della richiesta e potrebbe contenere informazioni di debug per aiutarti a capire perché la geocodifica non funziona. Il campo "status" può contenere i seguenti valori:
"OK"indica che non si sono verificati errori; l'indirizzo è stato analizzato correttamente ed è stato restituito almeno un geocodice."ZERO_RESULTS"indica che il geocodice è riuscito, ma non ha restituito risultati. Questo può accadere se al geocodificatore è stato trasmesso unaddressinesistente.OVER_DAILY_LIMITindica una delle seguenti condizioni:- La chiave API è mancante o non valida.
- La fatturazione non è stata abilitata nel tuo account.
- È stato superato un limite di utilizzo impostato autonomamente.
- 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 tua quota."REQUEST_DENIED"indica che la tua richiesta è stata rifiutata."INVALID_REQUEST"indica in genere che la query (address,componentsolatlng) non è presente."UNKNOWN_ERROR"indica che non è stato possibile elaborare la richiesta a causa di un errore del server. Riprova.
Messaggi di errore
Quando il geocodificatore restituisce un codice di stato diverso da OK, potrebbe esserci un campo error_message aggiuntivo all'interno dell'oggetto di risposta di 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 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 caratteristica restituito nel risultato. Ad esempio, il codice geografico "Chicago" restituisce "locality", che indica che "Chicago" è una città, e restituisce anche "political" che indica che si tratta di un'entità politica. I componenti potrebbero avere un array di tipi vuoto se non esistono tipi noti per quel componente dell'indirizzo. L'API potrebbe aggiungere nuovi valori di tipo, se necessario. Per ulteriori informazioni, vedi Tipi di indirizzo e componenti di indirizzo. formatted_addressè una stringa contenente l'indirizzo leggibile di questa località.Spesso, questo indirizzo equivale 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 è logicamente composto da uno o più componenti di 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 degli Stati Uniti).
Non analizzare l'indirizzo formattato in modo programmatico. Utilizza invece i singoli componenti dell'indirizzo, che include la risposta dell'API, in aggiunta al campo dell'indirizzo formattato.
address_components[]è un array contenente i componenti separati applicabili a questo indirizzo.In genere, ogni componente dell'indirizzo contiene i seguenti campi:
types[]è un array che indica il tipo del componente dell'indirizzo. Consulta l'elenco dei tipi supportati.long_nameè la descrizione testuale completa 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 indirizzo per lo stato dell'Alaska potrebbe avere "Alaska" comelong_nameeshort_name"AK" utilizzando l'abbreviazione postale a due lettere.
Tieni presente le seguenti informazioni sull'array
address_components[]:- L'array 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, ad eccezione di quelle incluse in
formatted_address. Per recuperare tutte le entità politiche che contengono un indirizzo specifico, devi utilizzare la geocodifica inversa, passando la latitudine/longitudine dell'indirizzo come parametro alla richiesta. - Non è garantito che il formato della risposta rimanga lo stesso tra una richiesta e l'altra. 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 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 fino a 100 località contenute in un codice postale. È presente solo se il risultato è un codice postale che include più località.geometrycontiene le seguenti informazioni:locationcontiene il valore di latitudine e longitudine geocodificati. 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 geocodice preciso per il quale le informazioni sulla posizione sono precise con precisione dell'indirizzo."RANGE_INTERPOLATED"indica che il risultato restituito riflette un'approssimazione (di solito su una strada) interpolata tra due punti precisi (come gli incroci). In genere, i risultati interpolati vengono restituiti quando i codici geografici del tetto 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, specificata sotto forma di due valori di latitudine e longitudine che definiscono gli angolisouthwestenortheastdel riquadro di delimitazione dell'area visibile. In genere l'area visibile viene utilizzata per inquadrare un risultato quando lo mostra a un utente.bounds(restituito facoltativamente) 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 Faallon, 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 posizione codificato, derivato dalle coordinate di latitudine e longitudine, che rappresenta un'area: 1/8000 di grado per 1/8000 di grado (circa 14 m x 14 m all'equatore) o inferiore. I Plus Code possono essere utilizzati in sostituzione degli indirizzi stradali in luoghi in cui gli indirizzi non sono presenti (in cui 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 località 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 è riuscito a far corrispondere 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à passata nella richiesta. Le corrispondenze parziali possono essere restituite anche 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 di un indirizzo con errori ortografici, 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 API Places per ottenere i dettagli di un'attività locale, come numero di telefono, orari di apertura, recensioni degli utenti e altro ancora. Consulta la panoramica di Place ID.
Tipi di indirizzi e di componenti di indirizzo
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. Questi tipi possono essere considerati "tag".
Ad esempio, molte città sono taggate con il tipo political e
locality.
I seguenti tipi sono supportati e restituiti dal geocodificatore negli array di tipo di indirizzo e di componente di indirizzo:
street_addressindica un indirizzo preciso.routeindica un percorso denominato (ad esempio "US 101").intersectionindica un incrocio principale, di solito composto da due strade principali.politicalindica un'entità politica. Di solito, questo tipo indica un poligono di alcune amministrazioni civili.countryindica l'entità politica nazionale ed è in genere il tipo di ordine più elevato restituito dal geocodificatore.administrative_area_level_1indica una persona giuridica civile di primo ordine al di sotto del livello nazionale. 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 Administration_area_level_1 corrisponderanno molto alle suddivisioni ISO 3166-2 e ad altri elenchi ampiamente diffusi. Tuttavia, questo non è garantito poiché i nostri risultati di geocodifica si basano su una varietà di indicatori e dati sulla posizione.administrative_area_level_2indica una persona giuridica civile di secondo ordine al di sotto del livello nazionale. All'interno degli Stati Uniti, questi livelli amministrativi sono contee. Non tutti i paesi presentano questi livelli amministrativi.administrative_area_level_3indica una persona giuridica civile di terzo ordine al di sotto del livello del paese. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.administrative_area_level_4indica una persona giuridica civile di quarto ordine al di sotto del livello del paese. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.administrative_area_level_5indica una persona giuridica di quinto ordine al di sotto del livello nazionale. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.administrative_area_level_6indica una persona giuridica civile di sesto ordine al di sotto del livello nazionale. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.administrative_area_level_7indica una persona giuridica civile di settimo ordine al di sotto del livello nazionale. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.colloquial_areaindica un nome alternativo di uso comune per l'entità.localityindica una città o un'entità politica incorporata in una città.sublocalityindica una persona giuridica di primo ordine sotto una località. Per alcune località potrebbe essere disponibile uno dei seguenti tipi: dasublocality_level_1asublocality_level_5. Ogni livello di circoscrizione è un'entità civile. Numeri più grandi indicano un'area geografica più piccola.neighborhoodindica un quartiere denominatopremiseindica una posizione denominata, di solito un edificio o un insieme di edifici con un nome comunesubpremiseindica un'entità di primo ordine sotto una località denominata, di solito un singolo edificio all'interno di una raccolta di edifici con un nome comuneplus_codeindica un riferimento a una località codificato, derivato da latitudine e longitudine. I plus code possono essere utilizzati in sostituzione degli indirizzi stradali in luoghi in cui non sono presenti (in cui gli edifici non sono numerati o le strade non hanno nomi). Per maggiori dettagli, visita la pagina https://plus.codes.postal_codeindica un codice postale utilizzato per la posta all'interno del paese.natural_featureindica una caratteristica 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 di spicco che non rientrano facilmente in un'altra categoria, come ad esempio "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 riportato sopra, i componenti dell'indirizzo possono includere i tipi elencati qui. Questo elenco non è completo ed è soggetto a modifiche.
floorindica il piano dell'indirizzo di un edificio.establishmentin genere indica un luogo che non è ancora stato 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 o una struttura di parcheggio.post_boxindica una casella postale specifica.postal_townindica un raggruppamento di aree geografiche, comelocalityesublocality, utilizzate 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 (espressi come riquadro di delimitazione). Per farlo,
nell'URL della richiesta devi impostare 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, il geocodice per "Washington" generalmente restituisce lo stato di Washington degli Stati Uniti:
Richiesta:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
Risposta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
Tuttavia, l'aggiunta di un argomento bounds che definisce un riquadro di delimitazione intorno alla parte nord-orientale degli Stati Uniti genera il risultato del geocodice 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 per regione
In una richiesta di geocodifica, puoi indicare al servizio di geocodifica di restituire risultati differenziati per una determinata regione utilizzando il parametro region. Questo parametro utilizza un argomento ccTLD (dominio di primo livello per il codice paese) che specifica il bias per la 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à "Il Regno Unito di Gran Bretagna e
Irlanda del Nord").
I risultati di geocodifica possono essere differenziati per ogni dominio in cui l'applicazione principale di Google Maps è stata lanciata ufficialmente. Tieni presente che la differenziazione preferisce i risultati per un dominio specifico; se esistono risultati più pertinenti al di fuori di questo dominio, possono essere inclusi.
Ad esempio, un geocodice per "Toledo" restituisce questo risultato, poiché il dominio predefinito per l'API Geocoding è impostato sugli Stati Uniti. Richiesta:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
Risposta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Una richiesta di geocodifica per "Toledo" con region=es (Spagna)
restituirà la città spagnola.
Richiesta:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
Risposta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Toledo",
"short_name" : "TO",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Filtro dei componenti
In una risposta Geocoding, l'API Geocoding può restituire risultati
di 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 valori 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 al meglio quando si utilizza il codice ISO corrispondente del paese.
Il seguente components può essere utilizzato per influenzare i risultati, ma non sarà applicato:
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 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 può 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. Specificare gli stessi valori in entrambi potrebbe generareZERO_RESULTS.
Il geocodice con components=country:GB per "High St, Hastings" restituisce un risultato a Hastings, in Inghilterra, anziché a 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"
}
La richiesta di codice geografico 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"
}
Il filtro dei componenti restituisce una risposta ZERO_RESULTS
solo se fornisci filtri che si escludono a vicenda.
Richiesta:
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
Risposta:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
Puoi eseguire query valide senza il parametro address, utilizzando il
filtro components. (durante la geocodifica di un indirizzo completo,
il parametro address è obbligatorio se la richiesta contiene
i nomi e il numero di 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"
}