Richiesta di geocodifica e risposta

Richiesta

Una richiesta all'API Geocoding ha il seguente formato:

https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

dove outputFormat può essere uno dei seguenti valori:

• json (consigliato) indica l'output in JSON (JavaScript Object Notation); o
• xml indica l'output in XML

È necessario HTTPS.

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 dell'indirizzo devono essere delimitati da spazi (qui mostrati con codifica URL per %20):

  address=24%20Sussex%20Drive%20Ottawa%20ON

  Formatta i codici plus come mostrato qui (i segni più sono codificati in URL per %2B e gli spazi sono codificati in URL per %20):
  • Il codice globale è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9 è 849VCWC8%2BR9).
  • 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 un address. Ogni elemento del filtro dei componenti è composto da un component:value accoppiano e limita completamente i risultati dal geocodificatore. Di seguito sono riportate ulteriori informazioni sul filtro dei componenti.
• key: chiave API dell'applicazione. Questa chiave identifica per la 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 geocodificati in modo più evidente. Questo parametro influirà solo sui risultati del geocodificatore, senza limitarli completamente. Per ulteriori informazioni, consulta la sezione Bias del viewport di seguito.
• language: la lingua in cui restituire i risultati.
  • Consulta l'elenco delle lingue supportate. Google aggiorna spesso le lingue supportate, pertanto questo elenco potrebbe non essere esaustivo.
  • Se language non viene fornito, il geocodificatore tenta di utilizzare la lingua preferita specificata nell'Accept-Language header o la lingua nativa del dominio da cui viene inviata la richiesta.
  • Il geocodificatore fa del suo meglio per fornire un indirizzo stradale ben leggibile sia per l'utente sia per i residenti. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in un script leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo vengono restituiti tutti nella stessa lingua, che viene scelta dal primo componente.
  • Se un nome non è disponibile nella lingua preferita, il geocodificatore utilizza la corrispondenza più simile.
  • La lingua preferita ha una piccola influenza sull'insieme di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Il geocodificatore interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni per i tipi di strade o i sinonimi che possono essere validi in una lingua, ma non in un'altra. Ad esempio, utca e tér sono sinonimi di strada e piazza, rispettivamente, in ungherese.
• region: il codice regione, specificato come valore di due caratteri di un ccTLD ("dominio di primo livello"). Questo parametro influisce solo su alcuni risultati del geocodificatore, senza limitarli completamente. Per maggiori informazioni, consulta Bias di regione di seguito. Il parametro può anche influire sui risultati in base alla legge vigente.
• components: un filtro dei componenti composto da elementi separate da una barra verticale (|). Il filtro dei componenti è obbligatorio se la richiesta non include un valore address. Ogni elemento del filtro dei componenti è composto da un component:value accoppiano e limita completamente i risultati dal geocodificatore. Di seguito sono riportate ulteriori informazioni sul filtro dei componenti.
• extra_computations: utilizza questo parametro per specificare le seguenti funzionalità aggiuntive nella risposta:
  • ADDRESS_DESCRIPTORS - Vedi descrittori dell'indirizzo per ulteriori dettagli.
  • BUILDING_AND_ENTRANCES: per maggiori dettagli, consulta la sezione su ingressi e contorni degli edifici.
  Per abilitare più di queste funzionalità per la stessa richiesta API, includi il parametro 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 mostra l'utilizzo del flag JSON output:

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

Questa richiesta mostra l'utilizzo del flag XML output:

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

Seleziona le schede di seguito per visualizzare le risposte JSON e XML di esempio.

{
    "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"
}

<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>

Codici di stato

Il campo "status" all'interno dell'oggetto della risposta di geocodifica contiene lo stato della richiesta e potrebbe contenere informazioni di debug per aiutarti a capire perché il geocoding non funziona. Il campo "status" può contenere i seguenti valori:

• "OK" indica che non si sono verificati errori; l'indirizzo è stato analizzato correttamente e almeno un codice geografico è stato restituito.
• "ZERO_RESULTS" indica che il geocodice è riuscito, ma non ha restituito risultati. Ciò può verificarsi se al geocodificatore è stato passato un address inesistente.
• OVER_DAILY_LIMIT indica una delle seguenti condizioni:
  • La chiave API è mancante o non valida.
  • La fatturazione non è stata attivata sul tuo account.
  • È stato superato un limite di utilizzo 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 quota.
• "REQUEST_DENIED" indica che la tua richiesta è stata rifiutata.
• "INVALID_REQUEST" indica in genere che la query (address, components o latlng) mancante.
• "UNKNOWN_ERROR" indica che non è stato possibile elaborare la richiesta 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 informazioni più dettagliate sui motivi alla base del codice di stato specificato.

Risultati

Quando il geocodificatore restituisce risultati, li inserisce in un array results (JSON). Anche se il geocodificatore non restituisce risultati (ad esempio se l'indirizzo non esiste), restituisce un array results vuoto. (le risposte XML sono costituite da zero o più elementi <result>).

Un risultato tipico contiene i seguenti campi:

• L'array types[] indica il tipo dell'array restituito o il risultato finale. Questo array contiene un insieme di zero o più tag che identificano il tipo di elemento restituito nel risultato. Ad esempio, un codice geografico di "Chicago" restituisce "località", che indica che "Chicago" è una città, e restituisce anche "politico", che indica che si tratta di un'entità politica. I 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 è equivalente all'indirizzo postale. Tieni presente che alcuni paesi, come il Regno Unito, non consentono la distribuzione di indirizzi postali veri a causa di limitazioni relative alle licenze.

  L'indirizzo formattato è composto logicamente da uno o più componenti dell'indirizzo. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è 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 del componente dell'indirizzo. Consulta l'elenco dei tipi supportati.
  • long_name è la descrizione completa del testo o il nome del componente dell'indirizzo restituito dal geocodificatore.
  • short_name è un nome testuale abbreviato per l'indirizzo , se disponibile. Ad esempio, un componente dell'indirizzo per lo stato dell'Alaska potrebbe avere un long_name di "Alaska" e un short_name di "AK" utilizzando l'abbreviazione postale di 2 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 invariato tra le 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 all'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 geocodificato della latitudine e della longitudine. Per le normali ricerche di indirizzi, 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 codice geografico preciso per il quale sono disponibili informazioni sulla posizione precise 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). I risultati interpolati vengono generalmente restituiti quando i codici geografici dei tetti non sono disponibili per un indirizzo.
    • "GEOMETRIC_CENTER" indica che il risultato restituito è il centro geometrico 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 del risultato restituito, specificata come due valori latitudine,longitudine che definiscono southwest e northeast il angolo della scatola delimitante dell'area visibile. In genere, la visualizzazione viene utilizzata per inquadrare un risultato quando viene mostrato a un utente.
  • bounds (restituito facoltativamente) memorizza la scatola delimitante che può contenere completamente il risultato restituito. Tieni presente che questi limiti potrebbero non corrispondere area visibile consigliata. Ad esempio, San Francisco include le isole Farallon, che tecnicamente fanno parte della città, ma probabilmente non dovrebbero essere restituite nell'area visibile.
• plus_code (vedi Open Location Code e plus code) è un riferimento di posizione codificato, ricavato dalle coordinate di latitudine e longitudine, che rappresenta un'area: 1/8000 di grado per 1/8000 di grado (circa 14 m x 14 m all'equatore) o più piccola. I Plus Code possono essere utilizzati 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 codice Plus, questo è 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.
  Se disponibile, l'API restituisce sia il codice globale sia il codice composto. Tuttavia, se il risultato si trova in una località remota (ad esempio, un oceano o un deserto) potrebbe essere restituito un codice globale.

• partial_match indica che il geocodificatore non ha restituito una corrispondenza esatta per la richiesta originale, anche se è stato in grado di trovare una corrispondenza per parte dell'indirizzo richiesto. Ti consigliamo di esaminare la richiesta originale per verificare la presenza di errori ortografici e/o di un indirizzo incompleto.

  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 un componente dell'indirizzo scritto male, il servizio di geocodifica potrebbe suggerire un indirizzo alternativo. Anche i suggerimenti attivati in questo modo verranno contrassegnati come parziali corrispondono.

• place_id è un identificatore univoco che può essere utilizzato con altre API di Google. Ad esempio, puoi usa place_id in un Richiesta di API Places per ottenere i dettagli di un'attività locale, come numero di telefono, orari di apertura, recensioni e altro ancora. Consulta la panoramica dell'ID luogo.

Tipi di indirizzi e tipi di componenti dell'indirizzo

L'array types[] nel risultato indica 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 essere di più tipi. Questi tipi possono essere considerati "tag". Ad esempio, molte città sono contrassegnate con il tipo political e locality.

I seguenti tipi sono supportati e restituiti dal geocodificatore in entrambi i campi array di tipo di indirizzo e di componente di indirizzo:

• street_address indica un indirizzo stradale preciso.
• route indica un percorso denominato (ad esempio "US 101").
• intersection indica un incrocio importante, in genere di due strade principali.
• political indica un'entità politica. In genere, questo tipo indica un poligono di qualche amministrazione civile.
• country indica l'entità politica nazionale ed è tipicamente il tipo di ordine più elevato restituito dal geocodificatore.
• administrative_area_level_1 indica un'entità civile di primo ordine al di sotto del livello del paese. Negli Stati Uniti, questi livelli amministrativi sono gli stati. Non tutte le nazioni mostrano questi a livello amministrativo. Nella maggior parte dei casi, i nomi brevi di administrative_area_level_1 corrispondono quasi esattamente alle suddivisioni ISO 3166-2 e ad altri elenchi molto diffusi. Tuttavia, non è garantito, in quanto i risultati del nostro geocodificamento si basano su una serie di indicatori e dati sulla posizione.
• administrative_area_level_2 indica un'autorità civile di secondo ordine inferiore a quella del paese. Negli Stati Uniti, questi livelli amministrativi sono le contee. Non tutte le nazioni mostrano questi a livello amministrativo.
• administrative_area_level_3 indica un'entità civile di terzo ordine al di sotto del livello di paese. Questo tipo indica una suddivisione civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
• administrative_area_level_4 indica una persona giuridica civile di quarto ordine al di sotto del livello di paese. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
• administrative_area_level_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 una suddivisione 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 un'entità politica costituita come città o paese.
• sublocality indica una persona giuridica di primo ordine sotto una località. Per alcune località potrebbe essere visualizzato uno dei tipi aggiuntivi: sublocality_level_1 a sublocality_level_5. Ogni livello di località secondaria è un'entità civile. Numeri più grandi indicano una minore geografica specifica.
• neighborhood indica un quartiere denominato
• premise indica una località denominata, di solito un edificio o insieme di edifici con un nome comune
• subpremise indica un'entità di primo ordine sotto una sede rinominata, solitamente un singolo edificio all'interno di una raccolta di edifici con un nome comune
• plus_code indica un riferimento alla posizione codificato, ricavato dalla latitudine e dalla 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 la spedizione della posta tradizionale 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 è esaustivo ed è soggetto a modifiche.

• floor indica il piano dell'indirizzo di un edificio.
• establishment indica in genere un luogo che non è stato ancora classificato.
• landmark indica un luogo nelle vicinanze utilizzato come riferimento per agevolare la navigazione.
• point_of_interest indica un punto d'interesse con nome.
• parking indica un parcheggio o un'area di parcheggio.
• post_box indica una casella postale specifica.
• postal_town indica un raggruppamento di aree geografiche, ad esempio locality e sublocality, utilizzato 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 e transit_station indica la posizione di un autobus, di un treno o di un pubblico fermata di trasporto pubblico.

Bias dell'area visibile

In una richiesta di geocodifica, puoi indicare al servizio di geocodifica di dare la preferenza ai risultati all'interno di un determinato viewport (espresso come una casella delimitante). 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 di questa area delimitata utilizzando un carattere barra verticale (|) per separare le coordinate.

Ad esempio, un codice geografico per "Washington" restituisce in genere lo stato americano di Washington:

Richiesta:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY

Risposta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            },
            "location" : {
               "lat" : 47.7510741,
               "lng" : -120.7401385
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            }
         },
         "place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
         "types" : [ "administrative_area_level_1", "political" ]
      }
   ],
   "status" : "OK"
}

Tuttavia, l'aggiunta di un argomento bounds che definisce un riquadro di delimitazione intorno alla parte nord-orientale degli Stati Uniti fa sì che questo codice geografico restituisca la città di Washington DC:

Richiesta:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY

Risposta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "Washington",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "District of Columbia",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "DC",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, DC, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            },
            "location" : {
               "lat" : 38.9071923,
               "lng" : -77.03687069999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            }
         },
         "place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Differenziazione della regione

In una richiesta di geocodifica, puoi 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 ai codici ISO 3166-1, con alcune eccezioni notevoli. 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 sbilanciati per ogni dominio in cui è stata lanciata ufficialmente l'applicazione principale di Google Maps. 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&region=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"
}

Filtraggio 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 per un filtro dei componenti, la risposta conterrà un campo partial_match.

I valori components che possono essere filtrati includono:

• postal_code corrisponde a postal_code e postal_code_prefix.
• country corrisponde a un nome di paese o a un codice paese di due lettere ISO 3166-1. L'API segue lo standard ISO per la definizione dei paesi e il filtraggio funziona al meglio se si utilizza il codice ISO corrispondente del paese.

I seguenti components possono essere utilizzati per influenzare i risultati, ma non verranno applicati:

• route corrisponde al nome lungo o breve di un percorso.
• locality partite contro locality e Tipi di sublocality.
• administrative_area corrisponde a tutti i livelli administrative_area.

Note sul filtro dei componenti:

• Non ripetere questi filtri dei componenti nelle richieste, altrimenti l'API restituirà Invalid_request: country, postal_code, route
• Se la richiesta contiene filtri dei componenti ripetuti, l'API li valuta i filtri come AND, non OR.
• I risultati sono coerenti con quelli di Google Maps, che a volte genera risposte ZERO_RESULTS inaspettate. L'utilizzo di Place Autocomplete potrebbe fornire risultati migliori in alcuni casi d'uso. Per saperne di più, vedi questo Domande frequenti.
• Per ogni componente dell'indirizzo, specificalo nel parametro address o in un filtro components, ma non in entrambi. Specificare gli stessi valori in entrambi possono generare ZERO_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 esegui il geocoding di un indirizzo completo, il parametro address è obbligatorio se la richiesta contiene i nomi e i numeri degli edifici.

Richiesta:

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

Risposta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annankatu",
               "short_name" : "Annankatu",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsinki",
               "short_name" : "HKI",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00101",
               "short_name" : "00101",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annankatu, 00101 Helsinki, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}