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); oppure
• xml indica l'output in XML

HTTPS è obbligatorio.

Nota: gli URL devono essere codificati correttamente per essere validi e avere un limite di 16.384 caratteri per tutti i servizi web. Tieni presente questo limite quando crei gli URL. Tieni presente che anche browser, proxy e server diversi possono avere limiti di caratteri degli URL diversi.

Alcuni parametri sono obbligatori, mentre altri sono facoltativi. Come standard negli URL, i parametri vengono separati utilizzando la e commerciale (&).

Il resto della pagina descrive la geocodifica e la geocodifica inversa separatamente, poiché sono disponibili parametri diversi per ogni tipo di richiesta.

Parametri di geocodifica (ricerca di latitudine/longitudine)

Tutti i caratteri riservati (ad esempio il segno più "+") devono essere codificati come URL.

Parametri obbligatori in una richiesta di geocodifica:

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

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

  Formato più codici come mostrato qui (i segni più contengono caratteri di escape per l'URL in %2B e gli spazi vengono sottoposti a escape per gli URL in %20):
  • Il codice globale è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9 è 849VCWC8%2BR9).
  • Il codice composto è un codice locale di almeno 6 caratteri con una posizione esplicita (CWC8+R9 Mountain View, CA, USA è CWC8%2BR9%20Mountain%20View%20CA%20USA).
  
  --OR--
  components: un filtro dei componenti con elementi separati da una barra verticale (|). Il filtro dei componenti è accettato anche come parametro facoltativo, se viene fornito un address. Ogni elemento nel filtro dei componenti è costituito da una coppia component:value e limita completamente i risultati provenienti dal geocodificatore. Scopri di più sul filtro dei componenti di seguito.
• key: la chiave API della tua applicazione. Questa chiave identifica l'applicazione ai fini della gestione della quota. Scopri come ottenere una chiave.

Per ulteriori indicazioni, consulta le Domande frequenti.

Parametri facoltativi in una richiesta di geocodifica:

• bounds: il riquadro di delimitazione dell'area visibile all'interno del quale eseguire la differenziazione per geocodificare i risultati in modo più evidente. Questo parametro influenza solo i risultati del geocodificatore, non le restringono completamente. Per ulteriori informazioni, consulta la sezione Differenziazione dell'area visibile di seguito.
• language: la lingua in cui restituire i risultati.
  • Consulta l'elenco delle lingue supportate. Google aggiorna spesso le lingue supportate, pertanto questo elenco potrebbe non essere esaustivo.
  • Se language non viene specificato, il geocodificatore tenta di utilizzare la lingua preferita specificata nell'intestazione Accept-Language o la lingua nativa del dominio da cui viene inviata la richiesta.
  • Il geocodificatore fa del suo meglio per fornire un indirizzo che sia leggibile sia per l'utente che per i residenti. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitte in uno script leggibile dall'utente se necessario, osservando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo vengono tutti restituiti nella stessa lingua, che viene 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 geocodificatore interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni dei tipi di strada o i sinonimi che possono essere validi in una lingua, ma non in un'altra. Ad esempio, utca e tér sono sinonimi per strada e quadrato rispettivamente in ungherese.
• region: il codice regione specificato come valore a due caratteri ccTLD ("dominio di primo livello"). Questo parametro influenza solo i risultati del geocodificatore, ma non le restringono completamente. Per ulteriori informazioni, consulta la sezione Differenziazione per regione di seguito. Il parametro può anche influire sui risultati in base alla legge vigente.
• components: un filtro dei componenti con elementi separati da una barra verticale (|). Il filtro dei componenti è obbligatorio se la richiesta non include un address. Ogni elemento nel filtro dei componenti è costituito da una coppia component:value e limita completamente i risultati provenienti dal geocodificatore. Scopri di più sul filtro dei componenti di seguito.

Risposte

Le risposte di geocodifica vengono restituite nel formato indicato dal flag output all'interno della richiesta dell'URL, oppure in formato JSON per impostazione predefinita.

In questo esempio, l'API Geocoding richiede una risposta json per una query sull'ID luogo "ChIJeRpOeF67j4AR9ydy_PIzPuM". L'ID luogo è relativo all'edificio all'indirizzo 1600 Amphitheatre Parkway, Mountain View, CA.

I codici Plus sono riferimenti di posizione con codifica rettangolare e derivati dalle coordinate di latitudine e longitudine. Le richieste con indirizzi completi, ad esempio "1600 Amphitheatre Parkway, Mountain View, CA", potrebbero non restituire un plus code se il risultato è un edificio o un'area, perché questi risultati in genere contengono più regioni Plus Code.

Questa richiesta mostra l'uso del flag JSON output:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

Questa richiesta dimostra che si utilizza il flag XML output:

https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

Seleziona le schede qui sotto 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"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4224428,
                    "lng": -122.0842467
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4239627802915,
                        "lng": -122.0829089197085
                    },
                    "southwest": {
                        "lat": 37.4212648197085,
                        "lng": -122.0856068802915
                    }
                }
            },
            "place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
            "plus_code": {
                "compound_code": "CWC8+X8 Mountain View, CA",
                "global_code": "849VCWC8+X8"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

Tieni presente che la risposta JSON contiene due elementi principali:

• "status" contiene metadati nella richiesta. Consulta la sezione Codici di stato di seguito.
• "results" contiene un array di informazioni sugli indirizzi geocodificati e informazioni sulla geometria.

In genere, viene restituita una sola voce nell'array "results" per le ricerche di indirizzi,anche se il geocodificatore potrebbe restituire diversi risultati quando le query sugli indirizzi sono ambigue.

XML

<GeocodeResponse>
    <status>OK</status>
    <result>
        <type>street_address</type>
        <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
        <address_component>
            <long_name>1600</long_name>
            <short_name>1600</short_name>
            <type>street_number</type>
        </address_component>
        <address_component>
            <long_name>Amphitheatre Parkway</long_name>
            <short_name>Amphitheatre Pkwy</short_name>
            <type>route</type>
        </address_component>
        <address_component>
            <long_name>Mountain View</long_name>
            <short_name>Mountain View</short_name>
            <type>locality</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>Santa Clara County</long_name>
            <short_name>Santa Clara County</short_name>
            <type>administrative_area_level_2</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>California</long_name>
            <short_name>CA</short_name>
            <type>administrative_area_level_1</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>United States</long_name>
            <short_name>US</short_name>
            <type>country</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>94043</long_name>
            <short_name>94043</short_name>
            <type>postal_code</type>
        </address_component>
        <geometry>
            <location>
                <lat>37.4224428</lat>
                <lng>-122.0842467</lng>
            </location>
            <location_type>ROOFTOP</location_type>
            <viewport>
                <southwest>
                    <lat>37.4212648</lat>
                    <lng>-122.0856069</lng>
                </southwest>
                <northeast>
                    <lat>37.4239628</lat>
                    <lng>-122.0829089</lng>
                </northeast>
            </viewport>
        </geometry>
        <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id>
        <plus_code>
            <global_code>849VCWC8+X8</global_code>
            <compound_code>CWC8+X8 Mountain View, CA</compound_code>
        </plus_code>
    </result>
</GeocodeResponse>

Tieni presente che la risposta XML è composta da un singolo elemento <GeocodeResponse> e da due elementi di primo livello:

• <status> contiene metadati nella richiesta. Consulta la sezione Codici di stato di seguito.
• Zero o più elementi <result>, ciascuno contenente un singolo insieme di informazioni sugli indirizzi geocodificati e informazioni sulla geometria.

La risposta XML è notevolmente più lunga della risposta JSON. Per questo motivo, ti consigliamo di utilizzare json come flag di output preferito, a meno che il tuo servizio non richieda xml per qualche motivo. Inoltre, l'elaborazione di alberi XML richiede un po' di attenzione, in modo da fare riferimento a nodi ed elementi corretti. Consulta Analisi di XML con XPath per alcuni pattern di progettazione consigliati per l'elaborazione dell'output.

La parte restante della documentazione utilizza la sintassi JSON. Nella maggior parte dei casi, il formato dell'output non è importante ai fini dell'illustrazione di concetti o nomi dei campi nella documentazione. Tuttavia, tieni presente le seguenti piccole differenze:

• I risultati XML vengono aggregati in un elemento <GeocodeResponse> principale.
• JSON indica le voci con più elementi tramite array plurali (types), mentre XML le denota utilizzando più elementi singolari (<type>).
• Gli elementi vuoti vengono indicati tramite array vuoti in JSON, ma dall'assenza di questi elementi nel file XML. Una risposta che non genera risultati restituirà un array results vuoto in JSON, ma ad esempio nessun elemento <result> nel file XML.

Codici di stato

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

• "OK" indica che non si sono verificati errori; l'indirizzo è stato analizzato correttamente e è stato restituito almeno un geocodice.
• "ZERO_RESULTS" indica che il geocodice è riuscito, ma non ha restituito alcun risultato. Questo può accadere se al geocodificatore è stato trasmesso un valore address inesistente.
• OVER_DAILY_LIMIT indica una delle seguenti condizioni:
  • 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 su Maps per scoprire come risolvere questo problema.

• "OVER_QUERY_LIMIT" indica che hai superato la tua quota.
• "REQUEST_DENIED" indica che la richiesta è stata rifiutata.
• "INVALID_REQUEST" indica in genere che la query (address, components o latlng) non è presente.
• "UNKNOWN_ERROR" indica che non è stato possibile elaborare la richiesta a causa di un errore del server. Se riprovi, la richiesta potrebbe riuscire.

Messaggi di errore

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

Nota: non è garantito che questo campo sia sempre presente e i suoi contenuti sono soggetti a modifiche.

Risultati

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

Un risultato tipico contiene i seguenti campi:

• L'array types[] indica il tipo del risultato restituito. Questo array contiene un insieme di zero o più tag che identificano il tipo di caratteristica restituito nel risultato. Ad esempio, un geocodice di "Chicago" restituisce "Località", che indica che "Chicago" è una città, e "politica", che indica che si tratta di un'entità politica. I componenti potrebbero avere un array di tipi vuoto se non esistono tipi noti per il componente dell'indirizzo. L'API potrebbe aggiungere nuovi valori di tipo in base alle esigenze. Per saperne di più, vedi Tipi di indirizzo e componenti dell'indirizzo.
• formatted_address è una stringa contenente l'indirizzo leggibile di questa località.

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

  L'indirizzo formattato è logicamente composto da uno o più componenti dell'indirizzo. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è costituito 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 contiene in genere i seguenti campi:

  • types[] è un array che indica il tipo del componente indirizzo. Consulta l'elenco dei tipi supportati.
  • long_name è la descrizione testuale o il nome completo del componente indirizzo, come restituito dal geocodificatore.
  • short_name è un nome testuale abbreviato per il componente indirizzo, se disponibile. Ad esempio, un componente dell'indirizzo per lo stato dell'Alaska può avere un long_name di "Alaska" e un short_name di "AK" utilizzando l'abbreviazione postale a due lettere.

  Tieni presente quanto segue relativo all'array address_components[]:

  • L'array di componenti dell'indirizzo può contenere più componenti rispetto a formatted_address.
  • L'array non include necessariamente tutte le entità politiche che contengono un indirizzo, escluse quelle incluse in formatted_address. Per recuperare tutte le entità politiche che contengono un indirizzo specifico, devi utilizzare la geocodifica inversa, trasmettendo 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 la posizione nell'array. Il tipo di componente può cambiare. Un componente specifico potrebbe essere mancante 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. È presente solo quando il risultato è un codice postale che contiene più località.
• geometry contiene le seguenti informazioni:
  • location contiene i valori di latitudine e longitudine geocodificati. Per le normali ricerche di indirizzi, questo campo è in genere il più importante.

  • location_type memorizza dati aggiuntivi sulla località specificata. Al momento 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.
    • "RANGE_INTERPOLATED" indica che il risultato restituito riflette un'approssimazione (di solito su una strada) interpolata tra due punti precisi (ad esempio gli incroci). I risultati interpolati vengono generalmente restituiti quando i codici geografici sui tetti non sono disponibili per un indirizzo.
    • "GEOMETRIC_CENTER" indica che il risultato restituito è il centro geometrico di un risultato come una polilinea (ad esempio una strada) o un poligono (una regione).
    • "APPROXIMATE" indica che il risultato restituito è approssimativo.
  • viewport contiene l'area visibile consigliata per visualizzare il risultato restituito, specificato con due valori di latitudine e longitudine che definiscono gli angoli southwest e northeast del riquadro di delimitazione dell'area visibile. In genere, l'area visibile viene utilizzata per inquadrare un risultato quando lo viene mostrato a un utente.
  • bounds (facoltativamente restituito) archivia il riquadro di delimitazione, che può contenere per intero il risultato restituito. Tieni presente che questi limiti potrebbero non corrispondere all'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 località codificato, derivato dalle coordinate di latitudine e longitudine, che rappresenta un'area: 1/8000° di grado per 1/8000° di grado (circa 14 x 14 m all'equatore) o inferiore. I plus code possono essere utilizzati in sostituzione degli indirizzi stradali in luoghi in cui gli indirizzi non 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 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.
  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), può essere restituito solo il codice globale.

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

  Le corrispondenze parziali si verificano più spesso per indirizzi che non esistono all'interno della località indicata 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 errato, il servizio di geocodifica potrebbe suggerire un indirizzo alternativo. Anche i suggerimenti attivati in questo modo verranno contrassegnati come corrispondenza parziale.

• place_id è un identificatore univoco che può essere utilizzato con altre API di Google. Ad esempio, puoi utilizzare place_id in una richiesta di API Places per ottenere i dettagli di un'attività locale, come il numero di telefono, gli orari di apertura, le recensioni degli utenti e altro ancora. Vedi la panoramica dell'ID luogo.

Tipi di indirizzi e tipi di componenti degli indirizzi

L'array types[] nel risultato indica il tipo di indirizzo. Esempi di tipi di indirizzi includono una via, un paese o un'entità politica. In address_components[] è anche presente un array types[], che indica il tipo di ogni parte dell'indirizzo. Alcuni esempi sono il numero civico o il paese. (Di seguito è riportato un elenco completo dei tipi). Gli indirizzi possono avere più tipi. I tipi possono essere considerati "tag". Ad esempio, molte città sono codificate con il tipo political e locality.

I seguenti tipi sono supportati e restituiti dal geocodificatore sia negli array del tipo di indirizzo che del tipo di componente indirizzo:

• street_address indica un indirizzo preciso.
• route indica un percorso denominato (ad es. "US 101").
• intersection indica un incrocio principale, di solito due strade principali.
• political indica un'entità politica. In genere, questo tipo indica un poligono con un'amministrazione civile.
• country indica l'entità politica nazionale e di solito è il tipo di ordine più elevato restituito dal geocodificatore.
• administrative_area_level_1 indica un ente civile di primo ordine al di sotto del livello nazionale. Negli Stati Uniti, questi livelli amministrativi sono gli stati. Non tutte le nazioni presentano questi livelli amministrativi. Nella maggior parte dei casi, i nomi brevi dell'area amministrativa_area_level_1 corrisponderanno molto alle suddivisioni ISO 3166-2 e ad altri elenchi ampiamente diffusi; tuttavia, ciò non è garantito perché i risultati della geocodifica si basano su una varietà di segnali e dati sulla posizione.
• administrative_area_level_2 indica un ente civile di secondo ordine sotto il livello nazionale. Negli Stati Uniti, questi livelli amministrativi sono contee. Non tutte le nazioni presentano questi livelli amministrativi.
• administrative_area_level_3 indica un ente civile di terzo ordine al di sotto del livello nazionale. Questo tipo indica una divisione civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
• administrative_area_level_4 indica un'entità civile di quarto ordine sotto il livello nazionale. Questo tipo indica una divisione civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
• administrative_area_level_5 indica un'entità civile di quinto ordine sotto il livello nazionale. Questo tipo indica una divisione civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
• administrative_area_level_6 indica un ente civile di sesto ordine sotto il livello nazionale. Questo tipo indica una divisione civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
• administrative_area_level_7 indica un ente civile di settimo ordine sotto il livello nazionale. Questo tipo indica una divisione 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 di una città o di una città incorporata.
• sublocality indica un'entità civile di primo ordine sotto una località. Per alcune località potrebbe essere disponibile uno dei seguenti tipi aggiuntivi: da sublocality_level_1 a sublocality_level_5. Ogni livello di circoscrizione è un ente civile. I numeri più grandi indicano un'area geografica più piccola.
• neighborhood indica un quartiere denominato
• premise indica una località con nome, in genere un edificio o un insieme di edifici con un nome comune.
• subpremise indica un'entità del primo ordine sotto una località denominata, di solito un singolo edificio all'interno di un insieme di edifici con un nome comune.
• plus_code indica un riferimento di posizione codificato, derivato da latitudine e longitudine. I plus code possono essere utilizzati in sostituzione degli indirizzi stradali in luoghi in cui non sono presenti (dove gli edifici non sono numerati o le strade non hanno nomi). Per maggiori dettagli, visita la pagina https://plus.codes.
• postal_code indica un codice postale utilizzato per la spedizione della posta nel paese.
• natural_feature indica un elemento 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 importanti che non rientrano facilmente in altre categorie, ad esempio "Empire State Building" o "Torre Eiffel".

Un elenco di tipi vuoto indica che non esistono tipi noti per il componente indirizzo specifico, ad esempio Lieu-dit in Francia.

Oltre a quanto sopra, i componenti dell'indirizzo possono includere i tipi qui elencati. Questo elenco non è completo ed è soggetto a modifiche.

• floor indica il piano dell'indirizzo di un edificio.
• establishment indica in genere un luogo che non è ancora stato classificato.
• 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, ad esempio locality e sublocality, utilizzato per gli indirizzi postali in alcuni paesi.
• room indica la stanza nell'indirizzo di un edificio.
• street_number indica il numero civico preciso.
• bus_station, train_station e transit_station indicano la posizione di una fermata di autobus, treno o trasporto pubblico.

Nota: non è garantito che l'API Geocoding restituisca alcun componente particolare per un indirizzo all'interno del nostro set di dati. Ciò che può essere considerato come una città, ad esempio Brooklyn, può non apparire come località, ma come un altro componente, in questo caso sublocality_level_1. I componenti specifici restituiti sono soggetti a modifica senza preavviso. Progetta il tuo codice in modo che sia flessibile se stai tentando di estrarre componenti degli indirizzi dalla risposta.

Differenziazione dell'area visibile

In una richiesta di geocodifica, puoi indicare al servizio di geocodifica di preferire i risultati all'interno di una determinata area visibile (espressa come riquadro di delimitazione). Per farlo, all'interno dell'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 delimitazione utilizzando una barra verticale (|) per separare le coordinate.

Nota: questa operazione aggiunge un solo bias ai risultati all'interno dell'area visibile e non garantisce che tutti o alcuni risultati saranno contenuti nell'area visibile. L'endpoint Autocomplete dell'API Places in genere è più adatto per query ambigue e può limitare i risultati a un'area specifica. L'articolo sulle best practice per la geocodifica fornisce alcune indicazioni su quale endpoint API è più adatto a ogni caso d'uso.

Ad esempio, un geocodice per "Washington" in genere restituisce lo stato di Washington negli Stati Uniti:

Richiesta:

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

Risposta:

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

Tuttavia, l'aggiunta di un argomento bounds che definisce un riquadro di delimitazione intorno alla parte nord-est degli Stati Uniti determina che questo geocodice restituisce la città di Washington, D.C.:

Richiesta:

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

Risposta:

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

Differenziazione per regione

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

I risultati della geocodifica possono essere differenziati per ogni dominio in cui l'applicazione principale di Google Maps è stata lanciata ufficialmente. Tieni presente che la differenziazione preferisce solo i risultati per un dominio specifico; se sono presenti 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 Geocoding, l'API Geocoding può restituire risultati relativi agli 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 del filtro supportano gli stessi metodi di correzione ortografica e di corrispondenza parziale delle altre richieste di geocodifica. Se il geocodificatore trova una corrispondenza parziale per un filtro di componente, la risposta conterrà un campo partial_match.

Gli components che possono essere filtrati includono:

• postal_code corrisponde a postal_code e postal_code_prefix.
• country corrisponde al nome di un paese o a un codice paese ISO 3166-1 di due lettere. L'API segue lo standard ISO per la definizione dei paesi e il filtro funziona meglio quando si utilizza il codice ISO corrispondente del paese.
  Nota: se ricevi risultati imprevisti con un codice paese, verifica di utilizzare un codice che includa i paesi, i territori dipendenti e le aree di interesse geografico speciali che intendi utilizzare. Puoi trovare informazioni sul codice su Wikipedia: Elenco dei codici paese ISO 3166 o sulla piattaforma di navigazione online ISO.

L'elemento components seguente potrebbe essere usato per influenzare i risultati, ma non verrà applicato:

• route corrisponde al nome lungo o breve di un percorso.
• locality corrispondenze rispetto ai tipi locality e sublocality.
• administrative_area corrisponde a tutti i administrative_area livelli.

Note sull'applicazione di filtri ai componenti:

• Non ripetere questi filtri dei componenti nelle richieste, altrimenti l'API restituirà Invalid_request: country, postal_code, route
• Se la richiesta contiene filtri di componenti ripetuti, l'API li valuta come AND, non come OR.
• I risultati sono coerenti con Google Maps, che a volte fornisce risposte ZERO_RESULTS impreviste. L'utilizzo di Place Autocomplete può fornire risultati migliori in alcuni casi d'uso. Per scoprire di più, consulta queste domande frequenti.
• Per ciascun componente dell'indirizzo, specificalo nel parametro address o in un filtro components, ma non in entrambi. Se specifichi gli stessi valori in entrambi, potresti ottenere ZERO_RESULTS.

Un codice geografico per "High St, Hastings" con components=country:GB restituisce un risultato ad Hastings, in Inghilterra, anziché ad 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 restituisce Santa Cruz de Tenerife nelle Isole Canarie, Spagna.

Richiesta:

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

Risposta:

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

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

Richiesta:

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

Risposta:

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

Puoi eseguire query valide senza il parametro indirizzo utilizzando il filtro components. (Durante la geocodifica di un indirizzo completo, il parametro address è obbligatorio se la richiesta contiene i nomi e i 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"
}