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); oxml
indica l'output in XML
HTTPS è obbligatorio.
Alcuni parametri sono obbligatori, mentre altri sono facoltativi. Come avviene normalmente per gli URL,
separati mediante il carattere "e commerciale" (&
).
Il resto della pagina descrive la geocodifica e la geocodifica inversa separatamente, perché sono disponibili parametri diversi per ogni tipo di richiesta.
Parametri di geocodifica (ricerca di latitudine/longitudine)
Parametri obbligatori in una richiesta di geocodifica:
address
: la via o il plus code che vuoi geocodificare. Specifica gli indirizzi nel formato utilizzata dal servizio postale nazionale del paese in questione. Aggiuntivo elementi dell'indirizzo come nome dell'attività e numeri di unità, interno o piano da evitare. Gli elementi degli indirizzi devono essere delimitati da spazi (mostrato qui come URL con caratteri di escape in%20
):address=24%20Sussex%20Drive%20Ottawa%20ON
Formatta i plus code come mostrato qui (i segni più vengono sottoposti a escape in%2B
e gli spazi sono sottoposti a escape in%20
):- Il codice globale è un prefisso di 4 caratteri e di almeno 6 caratteri
il codice locale (849VCWC8+R9 è
849VCWC8%2BR9
). - compound code è un codice locale di almeno 6 caratteri con un
località esplicita (CWC8+R9 Mountain View, CA, USA è
CWC8%2BR9%20Mountain%20View%20CA%20USA
).
--OR--
components
: un filtro dei componenti con elementi separate da una barra verticale (|
). È accettato anche il filtro dei componenti come parametro facoltativo se viene fornito unaddress
. Ogni elemento del filtro dei componenti è composto da uncomponent:value
accoppiano e limita completamente i risultati dal geocodificatore. Leggi ulteriori informazioni su filtro dei componenti qui sotto.- Il codice globale è un prefisso di 4 caratteri e di almeno 6 caratteri
il codice locale (849VCWC8+R9 è
key
: chiave API dell'applicazione. Questa chiave identifica per la 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 entro il quale differenziare i risultati geocodificati in modo più evidente. Questo parametro influenzare solo, non del tutto, i risultati ottenuti dal geocodificatore. Per ulteriori informazioni informazioni, consulta la sezione Differenziazione dell'area visibile di seguito.)language
: la lingua in cui per restituire i risultati.- Consulta l'elenco delle lingue. Google aggiorna spesso le lingue supportate, pertanto questo potrebbe non essere esaustivo.
- Se
language
non viene specificato, il geocodificatore tenta di utilizzare la lingua preferita specificata nelAccept-Language
o la lingua nativa del dominio da cui viene inviata la richiesta. - Il geocodificatore fa del suo meglio per fornire un indirizzo civico illeggibile sia per l'utente che per la gente del posto. Per raggiungere questo obiettivo, restituisce le vie nella lingua locale, traslitterate in una leggibile dall'utente se necessario, rispettando lo script preferito lingua. Tutti gli altri indirizzi vengono restituiti nel formato lingua. I componenti dell'indirizzo vengono restituiti nella stessa lingua che viene scelto 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 che l'API sceglie di restituire e l'ordine in cui vengono restituiti. Il geocodificatore interpreta le abbreviazioni in modo diverso a seconda lingua, come le abbreviazioni dei tipi di strada 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 ccTLD ("dominio di primo livello") valore a due caratteri. Questo parametro senza limitare completamente i risultati ottenuti dal geocodificatore. Per ulteriori informazioni informazioni, consulta Differenziazione per regione di seguito.) La può influire anche sui risultati in base alla legge vigente.components
: un filtro dei componenti composto da elementi separate da una barra verticale (|
). Il filtro dei componenti è obbligatorio se la richiesta non include un valoreaddress
. Ogni elemento del filtro dei componenti è composto da uncomponent:value
accoppiano e limita completamente i risultati dal geocodificatore. Leggi ulteriori informazioni su filtro dei componenti qui sotto.extra_computations
: utilizza questo parametro per specificare la le seguenti funzionalità aggiuntive nella risposta:ADDRESS_DESCRIPTORS
- Vedi descrittori dell'indirizzo per ulteriori dettagli.BUILDING_AND_ENTRANCES
- Vedi ingressi e profili degli edifici per ulteriori dettagli.
extra_computations
nella richiesta per ogni caratteristica, Ad esempio:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
Risposte
Le risposte di geocodifica vengono restituite nel formato indicato dal flag output
.
all'interno della richiesta dell'URL o in formato JSON per impostazione predefinita.
In questo esempio, l'API Geocoding richiede un json
risposta a 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 Codici di stato riportati di seguito."results"
contiene un array di informazioni sugli indirizzi geocodificati e informazioni sulla geometria.
In genere, viene restituita solo una voce nell'array "results"
per
di indirizzi, anche se il geocodificatore può restituire diversi risultati
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 una singola
<GeocodeResponse>
e due elementi di primo livello:
<status>
contiene metadati nella richiesta. Consulta Codici di stato riportati di seguito.- Zero o più elementi
<result>
, ciascuno contenente un singolo insieme di informazioni geometriche e geometriche.
La risposta XML è notevolmente più lunga di quella JSON. Per
per questo motivo, ti consigliamo di usare json
come
flag di output a meno che il servizio non richieda xml
per qualche motivo.
Inoltre, l'elaborazione delle strutture XML richiede una certa attenzione, quindi puoi fare riferimento
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 mediante matrici plurali (
types
), mentre XML le indica utilizzando più elementi singolari (<type>
). - Gli elementi vuoti sono indicati da array vuoti in JSON, ma dall'assenza di alcun
questo elemento in XML. Una risposta che non genera risultati restituirà un campo
Array
results
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 scoprire 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 e in è 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 unaddress
inesistente.OVER_DAILY_LIMIT
indica uno dei seguenti valori:- 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, la carta di credito è scaduta).
Per saperne di più, consulta le Domande frequenti su Maps 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
,components
olatlng
) mancante."UNKNOWN_ERROR"
indica che non è stato possibile inviare la richiesta elaborati a causa di un errore del server. La richiesta può avere esito positivo se Riprova.
Messaggi di errore
Quando il geocodificatore restituisce un codice di stato diverso da OK
, potrebbe essere presente un ulteriore
error_message
all'interno dell'oggetto di risposta Geocoding. Questo campo contiene altri dati
informazioni dettagliate sui motivi alla base del codice di stato specificato.
Risultati
Quando il geocodificatore restituisce dei risultati, li inserisce in un file results
(JSON)
un array di dati. Anche se il geocodificatore non restituisce risultati (ad esempio se l'indirizzo non esiste),
restituisce un array results
vuoto. (Le risposte XML sono composte da zero o più
<result>
elements.)
Un risultato tipico contiene i seguenti campi:
- L'array
types[]
indica il tipo dell'array restituito o il risultato finale. Questo array contiene un insieme di zero o più tag che identificano il tipo di caratteristica restituita nel risultato. Ad esempio, il codice geografico "Chicago" resi "località" che indica che "Chicago" è una città, e restituisce anche "politico" che indica che si tratta di un'entità politica. I tipi dei componenti potrebbero essere vuoti quando 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 la stringa leggibile dell'indirizzo di questa località.Spesso, questo indirizzo equivale all'indirizzo postale. Tieni presente che alcune paesi, come il Regno Unito, non consentono la distribuzione di veri e propri indirizzi postali a causa di limitazioni di licenza.
L'indirizzo formattato è logicamente composto da uno o più indirizzi componenti. 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" (stato USA).
Non analizzare l'indirizzo formattato in modo programmatico. Dovresti invece usare i singoli componenti dell'indirizzo, che la risposta dell'API include in aggiunta nel campo dell'indirizzo formattato.
address_components[]
è un array contenente l'espressione separata applicabili a questo indirizzo.In genere, ogni componente dell'indirizzo contiene i seguenti campi:
types[]
è un array che indica il tipo di . Visualizza l'elenco di tipi supportati.long_name
è la descrizione testuale o il nome completo del indirizzo come restituito dal Geocoder.short_name
è un nome testuale abbreviato per l'indirizzo , se disponibile. Ad esempio, un componente dell'indirizzo per lo stato dell'Alaska potrebbe avere una metricalong_name
"Alaska" e unshort_name
di "AK" utilizzando l'abbreviazione postale a due lettere.
Prendi nota delle seguenti informazioni su
address_components[]
array:- L'array dei componenti dell'indirizzo può contenere più componenti rispetto
formatted_address
. - L'array non include necessariamente tutte le entità politiche
contenere un indirizzo, diverso da quelli inclusi nei
formatted_address
. Per recuperare tutte le entità politiche che contengono un indirizzo specifico, devi usare la geocodifica inversa, La latitudine/longitudine dell'indirizzo come parametro della richiesta. - Non è garantito che il formato della risposta rimanga lo stesso tra
richieste. In particolare, il numero di
address_components
varia in base all'indirizzo richiesto e può cambiare nel tempo in base all'indirizzo nello stesso indirizzo. Un componente può cambiare posizione nell'array. Il tipo di componente può cambiare. Un particolare componente può essere mancante in una risposta successiva.
Per gestire l'array di componenti, devi analizzare la risposta e selezionare i valori appropriati tramite espressioni. Consulta la guida per durante l'analisi di una risposta.
postcode_localities[]
è un array che indica fino a 100 località contenuti in un codice postale. È presente solo quando il risultato è un codice postale che contiene più località.geometry
contiene le seguenti informazioni:location
contiene il valore di latitudine e longitudine geocodificati. Per la normalità indirizzi IP, questo campo è in genere il più importante.location_type
memorizza dati aggiuntivi sulla località specificata. La attualmente sono supportati i seguenti valori:"ROOFTOP"
indica che il risultato restituito è un geocodice preciso per le informazioni sulla sede sono precise con precisione fino all'indirizzo."RANGE_INTERPOLATED"
indica che il risultato restituito rifletta 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 una strada ."GEOMETRIC_CENTER"
indica che il risultato restituito è il centro geometrico un risultato come una polilinea (ad esempio una strada) o un poligono (una regione)."APPROXIMATE"
indica che il risultato restituito è approssimativo.
viewport
contiene l'area visibile consigliata per la visualizzazione il risultato restituito, specificato come due valori di latitudine,longitudine che definisconosouthwest
enortheast
angolo del riquadro di delimitazione dell'area visibile. In genere, l'area visibile viene utilizzata per inquadrare un risultato quando viene mostrato a un utente.bounds
(restituito facoltativamente) consente di archiviare il riquadro di delimitazione che possono contenere completamente il risultato restituito. Tieni presente che questi limiti potrebbero non corrispondere area visibile consigliata. Ad esempio, San Francisco include il isole Faallon, che fanno tecnicamente parte della città, ma probabilmente non dovrebbero essere restituiti nell'area visibile).
-
plus_code
(vedi Apri codice posizione e plus code) è un modello codificato riferimento di località, ricavato dalle coordinate di latitudine e longitudine, 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 di indirizzi in luoghi in cui non esistono indirizzi (in cui gli edifici non sono numerati o le vie 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_match
indica che il geocodificatore non è tornato una corrispondenza esatta per la richiesta originale, anche se è stata in grado di corrispondere a parte l'indirizzo richiesto. Ti consigliamo di esaminare la richiesta originale relativa a errori ortografici e/o un indirizzo incompleto.Molto spesso le corrispondenze parziali si verificano per indirizzi che non esistono nella località passata nella richiesta. Anche le corrispondenze parziali possono essere restituito quando una richiesta corrisponde a due o più sedi nella stessa località. Ad esempio, "Via Roma, RM" restituirà una corrispondenza parziale per Henry Street e Henrietta Street. Tieni presente che se una richiesta include componente dell'indirizzo con errori ortografici, il servizio di geocodifica può suggerire un'alternativa . Anche i suggerimenti attivati in questo modo verranno contrassegnati come parziali corrispondono.
place_id
è un nome univoco un identificatore univoco che può essere utilizzato con altre API di Google. Ad esempio, puoi usaplace_id
in un Richiesta di API Places per ottenere i dettagli di un'attività locale, come il numero di telefono, l'orario di apertura, l'utente recensioni e altro ancora. Visualizza l'ID luogo Panoramica.
Tipi di indirizzi e di componenti di indirizzo
L'array types[]
nel risultato indica
tipo di indirizzo. Esempi di tipi di indirizzo sono: via, indirizzo
paese o un'entità politica. C'è anche un array types[]
in
address_components[]
, che indica il tipo di ogni parte
. Alcuni esempi sono il numero civico o il paese. (Di seguito un elenco completo
types.) Gli indirizzi possono avere più tipi. Questi tipi possono essere considerati "tag".
Ad esempio, molte città sono taggate con political
e
Tipo di locality
.
I seguenti tipi sono supportati e restituiti dal geocodificatore in entrambi i campi array di tipo di indirizzo e di componente di indirizzo:
street_address
indica un indirizzo preciso.route
indica un percorso denominato (ad esempio "US 101").intersection
indica un incrocio principale, di solito di due strade principali.political
indica un'entità politica. Di solito, questo tipo indica il poligono di qualche amministrazione civile.country
indica l'entità politica nazionale e pertanto è di solito è il tipo di ordine più alto restituito dal Geocoder.administrative_area_level_1
indica un'autorità civile di primo ordine inferiore a quella del paese. Negli Stati Uniti, i livelli amministrativi sono gli stati. Non tutte le nazioni mostrano questi a livello amministrativo. Nella maggior parte dei casi, admin_area_level_1 i nomi brevi corrisponderanno esattamente alle suddivisioni ISO 3166-2 e ad altre liste diffuse; Tuttavia, questo non è garantito in quanto i nostri risultati di geocodifica si basano su vari indicatori e dati sulla posizione.administrative_area_level_2
indica un'autorità civile di secondo ordine inferiore a quella del paese. Negli Stati Uniti, i livelli amministrativi sono contee. Non tutte le nazioni mostrano questi a livello amministrativo.administrative_area_level_3
indica un'autorità civile di terzo ordine inferiore a quella del paese. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.administrative_area_level_4
indica un ordine civile di quarto ordine inferiore a quella del paese. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.administrative_area_level_5
indica un'autorità civile di quinto ordine inferiore a quella del paese. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.administrative_area_level_6
indica un civile di sesto ordine inferiore a quella del paese. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.administrative_area_level_7
indica un'autorità civile di settimo ordine inferiore a quella del paese. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.colloquial_area
indica un nome alternativo di uso comune per l'entità.locality
indica una città o una città politica dell'oggetto.sublocality
indica una persona giuridica di primo ordine sotto una località. Per alcune località potrebbero essere disponibili i seguenti tipi aggiuntivi: Dasublocality_level_1
asublocality_level_5
. Ogni livello di circoscrizione è un'entità civile. Numeri più grandi indicano una minore geografica specifica.neighborhood
indica un quartiere denominatopremise
indica una località denominata, di solito un edificio o insieme di edifici con un nome comunesubpremise
indica un'entità di primo ordine sotto un nome posizione, di solito un singolo edificio all'interno di una serie di edifici con un nome comuneplus_code
indica un riferimento a località codificato, derivato da latitudine e longitudine. I Plus Code possono essere utilizzati in sostituzione di indirizzi in luoghi in cui non esistono (in cui gli edifici non sono numerati o le vie non hanno un nome). Vedi https://plus.codes per maggiori dettagli.postal_code
indica un codice postale utilizzato per gestire la posta all'interno del paese.natural_feature
indica una caratteristica naturale in evidenza.airport
indica un aeroporto.park
indica un parco denominato.point_of_interest
indica un punto d'interesse con nome. In genere, questi "PDI" sono entità locali di rilievo che non si adattano facilmente In un'altra categoria, ad esempio "Empire State Building" o "Torre Eiffel".
Un elenco di tipi vuoto indica che non esistono tipi noti per la dell'indirizzo, ad esempio Lieu-dit in Francia.
Oltre a quanto riportato sopra, i componenti dell'indirizzo possono includere i tipi elencati qui. Questo elenco è non esaustivi e soggetti a modifiche.
floor
indica il piano dell'indirizzo di un edificio.establishment
in genere indica un luogo non ancora categorizzati.landmark
indica un luogo nelle vicinanze utilizzato come riferimento, per facilitare la navigazione.point_of_interest
indica un punto d'interesse con nome.parking
indica un parcheggio o una struttura di parcheggio.post_box
indica una casella postale specifica.postal_town
indica un raggruppamento di aree geografiche, comelocality
esublocality
, utilizzati per gli indirizzi postali in alcuni paesi.room
indica la stanza dell'indirizzo di un edificio.street_number
indica il numero civico esatto.bus_station
,train_station
etransit_station
indica la posizione di un autobus, di un treno o di un pubblico fermata di trasporto pubblico.
Differenziazione dell'area visibile
In una richiesta di geocodifica, puoi indicare al servizio di geocodifica di preferire
risultati all'interno di una determinata area visibile (espressi come riquadro di delimitazione). Per farlo
nell'URL della richiesta impostando il parametro bounds
.
Il parametro bounds
definisce le coordinate di latitudine/longitudine
degli angoli sud-ovest e nord-est del riquadro di delimitazione utilizzando una barra verticale
(|
) per separare le coordinate.
Ad esempio, il codice geografico "Washington" restituisce in genere lo stato U.S.A. 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
la parte nord-orientale degli Stati Uniti restituisce questo 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 chiedere al servizio di geocodifica di restituire
risultati differenziati per una particolare regione utilizzando region
. Questo parametro accetta un ccTLD (codice paese di primo livello
dominio) che specifica il bias della regione. La maggior parte dei codici ccTLD è identica a
i codici ISO 3166-1, con alcune eccezioni degne di nota. Ad esempio, il team
Il ccTLD del Regno è "uk" (.co.uk
) mentre il codice ISO 3166-1 è "gb"
(tecnicamente per l'entità "The United Kingdom of Gran Bretagna and
Irlanda del Nord").
I risultati della geocodifica possono essere differenziati per ogni dominio in cui L'applicazione Google Maps è stata lanciata ufficialmente. Tieni presente che solo la differenziazione preferisce i risultati relativi a un dominio specifico; se esistono risultati più pertinenti esterni a questo dominio, possono essere incluse.
Ad esempio, il codice geografico "Toledo" restituisce questo risultato, come predefinito per l'API Geocoding sia impostato su 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)
restituisce 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 indirizzi
limitati a un'area specifica. Puoi specificare la limitazione utilizzando
il filtro components
. Un filtro è costituito da un elenco di
component:value
coppie separate da una barra verticale (|
).
I valori di filtro supportano gli stessi metodi di correzione ortografica e
come le altre richieste di Geocoding. Se il geocodificatore trova una corrispondenza parziale di
del componente, la risposta conterrà un campo partial_match
.
I valori components
che possono essere filtrati includono:
postal_code
corrisponde apostal_code
epostal_code_prefix
.country
corrisponde al nome di un paese o a due lettere ISO 3166-1 il prefisso internazionale del paese. L'API segue lo standard ISO per che definiscono i paesi e il filtro funziona al meglio quando si utilizza codice ISO corrispondente del paese.
Il seguente components
può essere usato per influenzare i risultati, ma non verrà
applicato:
route
corrisponde al nome lungo o breve di un percorso.locality
partite controlocality
e Tipi disublocality
.administrative_area
corrisponde a tutti iadministrative_area
livelli.
Note sul filtro dei componenti:
- Non ripetere questi filtri dei componenti nelle richieste, altrimenti l'API li restituirà
Invalid_request
:country
,postal_code
,route
- Se la richiesta contiene filtri dei componenti ripetuti, l'API li valuta i filtri come AND, non OR.
- I risultati sono coerenti con Google Maps, che a volte genera
risposte
ZERO_RESULTS
impreviste. Utilizzo di Place Autocomplete può fornire risultati migliori in alcuni casi d'uso. Per saperne di più, vedi questo Domande frequenti. - Per ogni componente dell'indirizzo, specificalo nel
address
o in un filtrocomponents
, ma non entrambi. Specificare gli stessi valori in entrambi possono generareZERO_RESULTS
.
Un codice geografico per "High St, Hastings" con components=country:GB
restituisce un risultato in Hastings, in Inghilterra anziché in 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 geocodice per la località di "Santa Cruz" con components=country:ES
torna a 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 metodo
Filtro components
. (Quando geocodifica un indirizzo completo,
il parametro address
è obbligatorio se la richiesta contiene
nomi e numeri 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"
}