Richiesta di geocodifica e risposta

Richiesta

Una richiesta dell'API Geocoding ha il seguente formato:

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

dove outputFormat può essere uno dei seguenti valori:

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

È richiesto HTTPS.

Alcuni parametri sono obbligatori, mentre altri sono facoltativi. Come di consueto negli URL, i parametri sono separati dal carattere e commerciale (&).

Il resto di questa 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:

• key: la chiave API della tua applicazione. Questa chiave identifica la tua applicazione ai fini della gestione delle quote. Scopri come ottenere una chiave.

• Devi specificare address o components o entrambi in una richiesta:

  • address: l'indirizzo o il plus code che vuoi geocodificare. Specifica gli indirizzi in conformità al formato utilizzato dal servizio postale nazionale del paese interessato. Evita elementi aggiuntivi dell'indirizzo, come nomi di attività e numeri di unità, suite o piano. Gli elementi dell'indirizzo devono essere delimitati da spazi (mostrati qui con escape URL %20):

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

    Formatta i plus code come mostrato qui (i segni più vengono codificati come URL in %2B e gli spazi vengono codificati come URL in %20):
    • Il codice globale è un codice dell'area geografica di 4 caratteri e un codice locale di 6 o più caratteri (849VCWC8+R9 è 849VCWC8%2BR9).
    • Il codice composto è un codice locale di 6 o più caratteri con una posizione esplicita (CWC8+R9 Mountain View, CA, USA è CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • 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 address. Ogni elemento del filtro dei componenti è costituito da una coppia component:value e limita completamente i risultati del geocodificatore. Scopri di più sul filtraggio dei componenti di seguito.

Per ulteriori indicazioni, consulta le Domande frequenti.

Parametri facoltativi in una richiesta di geocodifica:

• bounds: il rettangolo di selezione dell'area visibile all'interno del quale dare maggiore risalto ai risultati di geocodifica. Questo parametro influirà solo sui risultati del geocodificatore, non li limiterà completamente. Per maggiori informazioni, vedi Bias della visualizzazione di seguito.
• language: la lingua in cui restituire i risultati.
  • Consulta l'elenco delle lingue supportate. Google aggiorna spesso le lingue supportate, quindi questo elenco potrebbe non essere esaustivo.
  • Se language non viene fornito, il geocoder tenta di utilizzare la lingua preferita specificata nell'intestazione Accept-Language o la lingua nativa del dominio da cui viene inviata la richiesta.
  • Il geocoder fa del suo meglio per fornire un indirizzo stradale leggibile sia per l'utente sia per gli abitanti del luogo. Per raggiungere questo obiettivo, restituisce gli indirizzi stradali nella lingua locale, traslitterati in un sistema di scrittura leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. Tutti i componenti dell'indirizzo vengono restituiti nella stessa lingua, scelta dal primo componente.
  • Se un nome non è disponibile nella lingua preferita, il geocodificatore utilizza la corrispondenza più vicina.
  • La lingua preferita ha una piccola influenza sull'insieme di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Il geocoder interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni per i tipi di strade o i sinonimi che potrebbero essere validi in una lingua ma non in un'altra. Ad esempio, utca e tér sono sinonimi di strada e piazza rispettivamente in ungherese.
• region: il codice regione, specificato come valore di due caratteri ccTLD ("dominio di primo livello"). Questo parametro influirà solo sui risultati del geocodificatore, non li limiterà completamente. Per saperne di più, consulta la sezione Bias regionale di seguito. Il parametro può influire sui risultati anche in base alla legge vigente.
• components: un filtro dei componenti con elementi separati da una barra verticale (|). Il filtro dei componenti è obbligatorio se la richiesta non include un address. Ogni elemento del filtro dei componenti è costituito da una coppia component:value e limita completamente i risultati del geocoder. Scopri di più sul filtraggio dei componenti di seguito.
• extra_computations: utilizza questo parametro per specificare le seguenti funzionalità aggiuntive nella risposta:
  • ADDRESS_DESCRIPTORS: vedi descrittori di indirizzo per maggiori dettagli.
  • BUILDING_AND_ENTRANCES: consulta la sezione Ingressi e contorni degli edifici per maggiori dettagli.
  Per attivare più di queste funzionalità per la stessa richiesta API, includi il parametro extra_computations nella richiesta per ogni funzionalità, ad esempio:

  extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

Risposte

Le risposte di geocoding vengono restituite nel formato indicato dal flag output all'interno della richiesta 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 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 di risposta del geocoding contiene lo stato della richiesta e può 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 ed è stato restituito almeno un geocodice.
• "ZERO_RESULTS" indica che il geocodice è stato creato correttamente, ma non ha restituito risultati. Ciò può verificarsi se al geocodificatore è stato trasmesso un address inesistente.
• OVER_DAILY_LIMIT indica una delle seguenti opzioni:
  • La chiave API è mancante o non valida.
  • La fatturazione non è stata abilitata sul tuo account.
  • È stato superato un limite di utilizzo autoimposto.
  • Il metodo di pagamento fornito non è più valido (ad esempio, una carta di credito è scaduta).

  Consulta le domande frequenti di Maps per scoprire come risolvere il problema.

• "OVER_QUERY_LIMIT" indica che hai superato la quota.
• "REQUEST_DENIED" indica che la tua richiesta è stata rifiutata.
• "INVALID_REQUEST" in genere indica che la query (address, components o latlng) è mancante.
• "UNKNOWN_ERROR" indica che la richiesta non è stato possibile elaborarla a causa di un errore del server. La richiesta potrebbe andare a buon fine se riprovi.

Messaggi di errore

Quando il geocoder restituisce un codice di stato diverso da OK, potrebbe essere presente un campo error_message aggiuntivo all'interno dell'oggetto della risposta di geocodifica. Questo campo contiene informazioni più dettagliate sui motivi alla base del codice di stato fornito.

Risultati

Quando il geocoder restituisce i risultati, li inserisce in un array (JSON) results. Anche se il geocoder non restituisce risultati (ad esempio se l'indirizzo non esiste), restituisce comunque 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 del risultato restituito. Questo array contiene un insieme di zero o più tag che identificano il tipo di funzionalità restituita nel risultato. Ad esempio, un geocodice di "Chicago" restituisce "locality", che indica che "Chicago" è una città, e anche "political" che indica che è un'entità politica. I componenti potrebbero avere un array types vuoto quando non sono presenti tipi noti per quel componente dell'indirizzo. L'API potrebbe aggiungere nuovi valori di tipo in base alle necessità. Per saperne di più, consulta Tipi di indirizzo e componenti dell'indirizzo.
• formatted_address è una stringa contenente l'indirizzo leggibile di questa posizione.

  Spesso questo indirizzo equivale all'indirizzo postale. Tieni presente che alcuni paesi, come il Regno Unito, non consentono la distribuzione di indirizzi postali reali a causa di limitazioni di licenza.

  L'indirizzo formattato è composto logicamente da uno o più componenti dell'indirizzo. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è composto dai seguenti componenti: "111" (il numero civico), "8th Avenue" (la strada), "New York" (la città) e "NY" (lo stato degli Stati Uniti).

  Non analizzare l'indirizzo formattato in modo programmatico. Devi invece utilizzare i singoli componenti dell'indirizzo, che la risposta dell'API include oltre al campo dell'indirizzo formattato.

• address_components[] è un array contenente i componenti separati applicabili a questo indirizzo.

  Ogni componente dell'indirizzo in genere 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 o il nome completo del componente dell'indirizzo restituito dal geocodificatore.
  • short_name è un nome testuale abbreviato per il componente dell'indirizzo, se disponibile. Ad esempio, un componente di indirizzo per lo stato dell'Alaska potrebbe avere un long_name di "Alaska" e un short_name di "AK" utilizzando l'abbreviazione postale di due lettere.

  Tieni presente quanto segue in merito all'array address_components[]:

  • L'array di componenti dell'indirizzo può contenere più componenti di formatted_address.
  • L'array non include necessariamente tutte le entità politiche che contengono un indirizzo, a parte quelle incluse in formatted_address. Per recuperare tutte le entità politiche che contengono un indirizzo specifico, devi utilizzare il geocoding inverso, passando la latitudine/longitudine dell'indirizzo come parametro alla richiesta.
  • Non è garantito che il formato della risposta rimanga lo stesso tra le richieste. In particolare, il numero di address_components varia 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 non essere presente in una risposta successiva.

  Per gestire l'array di componenti, devi analizzare la risposta e selezionare i valori appropriati tramite le espressioni. Consulta la guida all' analisi di una risposta.

• postcode_localities[] è un array che indica fino a 100 località contenute in un codice postale. Questo campo è 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 geocodificato. Per le normali ricerche di indirizzi, questo campo è in genere il più importante.

  • location_type memorizza dati aggiuntivi sulla località specificata. Attualmente sono supportati i seguenti valori:

    • "ROOFTOP" indica che il risultato restituito è un geocodice preciso per il quale disponiamo di informazioni sulla posizione accurate fino alla precisione dell'indirizzo stradale.
    • "RANGE_INTERPOLATED" indica che il risultato restituito riflette un'approssimazione (di solito su una strada) interpolata tra due punti precisi (ad esempio incroci). I risultati interpolati vengono generalmente restituiti quando i geocodici del tetto non sono disponibili per un indirizzo stradale.
    • "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.
  • viewport contiene l'area visibile consigliata per visualizzare il risultato restituito, specificata come due valori di latitudine e longitudine che definiscono l'angolo southwest e northeast del riquadro di selezione dell'area visibile. In genere, il viewport viene utilizzato per inquadrare un risultato quando viene visualizzato a un utente.
  • bounds (restituito facoltativamente) memorizza il riquadro di selezione che può contenere completamente il risultato restituito. Tieni presente che questi limiti potrebbero non corrispondere alla finestra consigliata. (Ad esempio, San Francisco include le isole Farallon, che tecnicamente fanno parte della città, ma probabilmente non devono essere restituite nella finestra.)
• plus_code (vedi Open Location Code e plus code) è un riferimento codificato a una posizione, 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 più piccola. I Plus Code possono essere utilizzati in sostituzione degli indirizzi stradali in luoghi in cui gli indirizzi non esistono (dove gli edifici non sono numerati o le strade non hanno un nome). L'API non restituisce sempre i plus code.

  Quando il servizio restituisce un plus code, questo viene formattato come codice globale e codice composto:

  • global_code è un prefisso di 4 caratteri e un codice locale di 6 o più caratteri (849VCWC8+R9).
  • compound_code è un codice locale di almeno 6 caratteri con una posizione esplicita (CWC8+R9, Mountain View, CA, USA). Non analizzare questo contenuto in modo programmatico.
  Se disponibili, l'API restituisce sia il codice globale sia il codice composto. Tuttavia, se il risultato si trova in una posizione remota (ad esempio, un oceano o un deserto), potrebbe essere restituito solo il codice globale.

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

  Le corrispondenze parziali si verificano più spesso per gli indirizzi stradali che non esistono all'interno della località che trasmetti nella richiesta. Le corrispondenze parziali possono essere restituite anche quando una richiesta corrisponde a due o più località nella stessa località. Ad esempio, "Hillpar St, Bristol, UK" restituirà una corrispondenza parziale sia per Henry Street che per Henrietta Street. Tieni presente che se una richiesta include un componente dell'indirizzo scritto in modo errato, il servizio di geocoding potrebbe suggerire un indirizzo alternativo. I suggerimenti attivati in questo modo verranno contrassegnati anche come corrispondenza parziale.

• place_id è un identificatore univoco che può essere utilizzato con altre API di Google. Ad esempio, puoi utilizzare place_id in una richiesta dell'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 dell'ID luogo.

Tipi di indirizzo e tipi di componenti dell'indirizzo

L'array types nella risposta indica il tipo di indirizzo. Esempi di tipi di indirizzo includono un indirizzo stradale, un paese o un'entità politica. L'array types nel campo address_component indica il tipo di ogni parte dell'indirizzo. Alcuni esempi sono il numero civico o il paese.

Gli indirizzi possono avere più tipi. I tipi possono essere considerati "tag". Ad esempio, molte città sono taggate con i tipi political e locality.

I seguenti tipi sono supportati e restituiti sia negli array di tipi di indirizzo sia in quelli di componenti di indirizzo:

Un elenco vuoto di tipi indica che non esistono tipi noti per il particolare componente dell'indirizzo (ad esempio, Lieu-dit in Francia).

Oltre a quanto sopra, i componenti dell'indirizzo possono includere i tipi elencati di seguito.

Bias dell'area visibile

In una richiesta di geocodifica, puoi indicare al servizio di geocodifica di preferire i risultati all'interno di un determinato riquadro visibile (espresso come rettangolo di selezione). Puoi 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 questo riquadro di selezione utilizzando una barra verticale (|) per separare le coordinate.

Ad esempio, un geocodice per "Washington" in genere restituisce 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 geocodice restituisca la città di Washington, D.C.:

Richiesta:

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

Risposta:

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

Differenziazione delle regioni

In una richiesta di geocodifica, puoi indicare al servizio di geocodifica di restituire risultati orientati a una determinata regione utilizzando il parametro region. Questo parametro accetta un argomento ccTLD (dominio di primo livello con codice paese) che specifica la distorsione regionale. La maggior parte dei codici ccTLD sono identici ai codici ISO 3166-1, con alcune notevoli eccezioni. Ad esempio, il TLD specifico per paese del Regno Unito è "uk " (.co.uk), mentre il suo codice ISO 3166-1 è"gb " (tecnicamente per l'entità del "Regno Unito di Gran Bretagna e Irlanda del Nord").

I risultati della geocodifica possono essere distorti per ogni dominio in cui l'applicazione Google Maps principale viene lanciata ufficialmente. Tieni presente che la ponderazione preferisce solo i risultati per un dominio specifico; se esistono risultati più pertinenti al di fuori di questo dominio, potrebbero essere inclusi.

Ad esempio, un 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&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"
}

Filtro dei componenti

In una risposta di geocodifica, 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 geocoder trova una corrispondenza parziale per un filtro dei componenti, la risposta conterrà un campo partial_match.

I 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 ISO 3166-1 di due lettere. L'API segue lo standard ISO per la definizione dei paesi e il filtro funziona meglio quando viene utilizzato il codice ISO corrispondente del paese.

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 corrisponde a locality e tipi 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 come AND, non come OR.
• I risultati sono coerenti con Google Maps, che a volte produce risposte ZERO_RESULTS inaspettate. L'utilizzo di Place Autocomplete potrebbe fornire risultati migliori in alcuni casi d'uso. Per saperne di più, consulta queste domande frequenti.
• Per ogni componente dell'indirizzo, specificarlo nel parametro address o in un filtro components, ma non in entrambi. Se specifichi gli stessi valori in entrambi, potresti ottenere ZERO_RESULTS.

Un geocodice per "High St, Hastings" con components=country:GB restituisce un risultato a Hastings, in Inghilterra, anziché a Hastings-On-Hudson, negli Stati Uniti.

Richiesta:

https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY

Risposta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "High Street",
               "short_name" : "High St",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Hastings",
               "short_name" : "Hastings",
               "types" : [ "postal_town" ]
            },
            {
               "long_name" : "East Sussex",
               "short_name" : "East Sussex",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "England",
               "short_name" : "England",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United Kingdom",
               "short_name" : "GB",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "TN34 3EY",
               "short_name" : "TN34 3EY",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "High St, Hastings TN34 3EY, UK",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            },
            "location" : {
               "lat" : 50.85830319999999,
               "lng" : 0.5924594
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

Una richiesta di geocodifica per la località "Santa Cruz" con components=country:ES restituisce Santa Cruz de Tenerife nelle Isole Canarie, Spagna.

Richiesta:

https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY

Risposta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canary Islands",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            },
            "location" : {
               "lat" : 28.4636296,
               "lng" : -16.2518467
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            }
         },
         "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Il filtro dei componenti restituisce una risposta ZERO_RESULTS solo se fornisci filtri che si escludono a vicenda.

Richiesta:

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

Risposta:

{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

Puoi creare query valide senza il parametro dell'indirizzo utilizzando il filtro components. (Quando viene eseguito 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"
}