Richiesta di geocodifica e risposta

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Risorse richieste:

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

HTTPS è obbligatorio per le richieste che utilizzano una chiave API.

Alcuni parametri sono obbligatori, altri invece sono facoltativi. Come avviene negli URL, i parametri sono separati utilizzando la 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:

  • address: l'indirizzo o il plus code che vuoi geocodificare. Specifica gli indirizzi in base al formato utilizzato dal servizio postale nazionale del paese in questione. Evita di aggiungere elementi dell'indirizzo, come i nomi dell'attività e i numeri dell'unità, dell'interno o del piano. Gli elementi dell'indirizzo devono essere delimitati da spazi (mostrati qui come escape dell'URL in %20):
    address=24%20Sussex%20Drive%20Ottawa%20ON
    Formatta i plus code come mostrato qui (il segno più viene preceduto dall'URL all'URL %2B e gli spazi sono sottoposti all'escape dell'URL al valore %20):
    • global code è un prefisso di 4 caratteri e di un codice locale di 6 o più caratteri (849VCWC8+R9 è 849VCWC8%2BR9).
    • compound code è 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: 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 nel filtro dei componenti è costituito da una coppia component:value e limita completamente i risultati del 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.

Consulta le Domande frequenti per ulteriori indicazioni.

Parametri facoltativi in una richiesta di geocodifica:

  • bounds: il riquadro di delimitazione dell'area visibile all'interno del quale eseguire la differenziazione dei risultati geografici in modo più evidente. Questo parametro influenza solo i risultati del geocodificatore, non quelli completamente limitati. Per ulteriori informazioni, consulta la sezione Differenziazione dell'area visibile riportata di seguito.
  • language: la lingua in cui restituire i risultati.
    • Consulta l'elenco delle lingue supportate. Poiché Google aggiorna spesso le lingue supportate, questo elenco potrebbe non essere esaustivo.
    • Se language non viene fornito, 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 proprio meglio per fornire un indirizzo leggibile sia per l'utente che per i locali. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, che vengono traslitterati in uno script leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti degli indirizzi 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 di restituzione. Il geocodificatore interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni dei tipi di strade o sinonimi che possono essere validi in una lingua ma non in un'altra. Ad esempio, utca e tér sono sinonimi di strada e quadrato rispettivamente in ungherese.
  • region: il codice della regione, specificato come valore di due caratteri ccTLD ("dominio di primo livello"). Questo parametro influenza solo i risultati del geocodificatore, non quelli completamente limitati. (per saperne di più, consulta Differenziazione per regione di seguito).
  • components: filtro dei componenti con elementi separati da una barra verticale (|). Il filtro dei componenti è obbligatorio se la richiesta non include address. Ogni elemento nel filtro dei componenti è costituito da una coppia component:value e limita completamente i risultati del geocodificatore. Scopri di più sul filtro dei componenti di seguito.

Risposte

Le risposte di geocodifica vengono restituite nel formato indicato dal flag output nella richiesta URL o in formato JSON per impostazione predefinita.

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

Questa richiesta dimostra 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 l'utilizzo del flag XML output:

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

Seleziona le schede di seguito per vedere esempi di risposte in formato JSON e XML.

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 su indirizzi geocodificati e dati geometrici.

In genere, viene restituita solo una 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 <GeocodeResponse> e da due elementi di primo livello:

  • <status> contiene metadati nella richiesta. Consulta i codici di stato riportati di seguito.
  • Zero o più elementi <result>, ciascuno contenente un singolo insieme di informazioni geolocalizzate e sull'indirizzo.

La risposta XML è notevolmente più lunga rispetto alla 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 strutture XML richiede attenzione, per fare riferimento a nodi ed elementi adeguati. Consulta Analizzare XML con XPath per alcuni pattern di progettazione consigliati per l'elaborazione di output.

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

Codici di stato

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

  • "OK" indica che non si sono verificati errori; l'indirizzo è stato analizzato correttamente e almeno un codice geografico è stato restituito.
  • "ZERO_RESULTS" indica che il codice geografico è riuscito, ma non ha restituito risultati. Ciò può accadere se al geocodificatore viene trasmesso un elemento address inesistente.
  • OVER_DAILY_LIMIT indica una delle seguenti condizioni:
    • La chiave API manca o non è valida.
    • La fatturazione non è stata attivata sul tuo account.
    • È stato superato un limite di utilizzo autoimpostato.
    • Il metodo di pagamento indicato non è più valido (ad esempio, una carta di credito è scaduta).

    Consulta le Domande frequenti su Maps per scoprire come risolvere questo problema.

  • "OVER_QUERY_LIMIT" indica che hai superato la tua 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 non è stato possibile elaborare la richiesta a causa di un errore del server. Se decidi di riprovare, 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 di risposta Geocoding. Questo campo contiene informazioni più dettagliate sui motivi per cui il 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 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 funzionalità restituita nel risultato. Ad esempio, un codice geografico di "Chicago" restituisce "località" che indica che "Chicago" è una città e restituisce anche "politica" che indica che si tratta di un'entità politica. I componenti potrebbero avere una matrice vuota quando non sono presenti tipi noti per il componente dell'indirizzo. Se necessario, l'API potrebbe aggiungere nuovi valori di tipo. Per ulteriori informazioni, consulta Tipi di indirizzi e componenti degli indirizzi.
  • formatted_address è una stringa contenente l'indirizzo leggibile di questa località.

    Spesso si tratta dell'indirizzo postale. Tieni presente che alcuni paesi, come il Regno Unito, non consentono la distribuzione di indirizzi postali reali a causa di limitazioni delle licenze.

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

    Non analizzare l'indirizzo formattato in modo programmatico. Utilizza invece 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.

    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 Geocoder.
    • short_name è un nome abbreviato per il componente dell'indirizzo, se disponibile. Ad esempio, un componente indirizzo per lo stato dell'Alaska potrebbe avere long_name "Alaska" e short_name "AK" utilizzando l'abbreviazione postale di 2 lettere.

    Prendi nota dei seguenti fatti relativi all'array di address_components[]:

    • La matrice dei componenti dell'indirizzo può contenere più componenti di formatted_address.
    • L'array non include necessariamente tutte le entità politiche che contengono un indirizzo, ad eccezione di quelle incluse nell'elemento formatted_address. Per recuperare tutte le entità politiche che contengono un indirizzo specifico, devi utilizzare la geocodifica inversa, passando la latitudine/longitudine dell'indirizzo come parametro della 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 nella matrice. Il tipo del componente può cambiare. Potresti non trovare un determinato componente in una risposta successiva.

    Per gestire l'array dei 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 tutte le 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 la latitudine geocodificata e il valore longitudine. 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 codice geografico preciso per il quale disponiamo di informazioni sulla posizione precise fino alla precisione dell'indirizzo.
      • "RANGE_INTERPOLATED" indica che il risultato restituito riflette un'approssimazione (generalmente su una strada) interpolata tra due punti precisi (come incroci). I risultati interpolati vengono generalmente restituiti quando i codici geografici panoramici non sono disponibili per un indirizzo.
      • "GEOMETRIC_CENTER" indica che il risultato restituito è il centro geometrico di un risultato, ad esempio una polilinea (ad esempio una strada) o un poligono (area geografica).
      • "APPROXIMATE" indica che il risultato restituito è approssimativo.
    • viewport contiene l'area visibile consigliata per visualizzare il risultato restituito, specificato come 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 mostra a un utente.
    • bounds (restituito facoltativamente) archivia il riquadro di delimitazione che può contenere completamente il risultato restituito. Tieni presente che questi limiti potrebbero non corrispondere alla visualizzazione consigliata. Ad esempio, San Francisco include le isole Farallon, che sono tecnicamente parte della città, ma probabilmente non devono essere restituite nell'area visibile.
  • plus_code (vedi Apri Codice di località e più codici) è un riferimento di località codificato, derivato da coordinate di latitudine e longitudine, che rappresentano un'area: 1/8000 di grado per 1/8000 di grado (circa 14 x 14 m all'equatore) o inferiore. È possibile utilizzare i Plus Code per sostituire gli indirizzi in luoghi in cui non esistono indirizzi (dove gli edifici non sono numerati o le strade non hanno un nome). L'API non restituisce sempre plus code.

    Quando il servizio restituisce un Plus Code, questo viene formattato come un codice globale e un 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 sei o più caratteri con una posizione esplicita (CWC8+R9, Mountain View, CA, USA). Non analizzare questi contenuti in modo programmatico.
    Laddove disponibili, l'API restituisce sia il codice globale che 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 l'eventuale presenza di errori ortografici e/o un indirizzo incompleto.

    Nella maggior parte dei casi, le corrispondenze parziali si verificano per gli indirizzi che non esistono nella località trasmessa nella richiesta. Le corrispondenze parziali possono essere restituite anche quando una richiesta corrisponde a due o più sedi nella stessa località. Ad esempio, "Hillpar St, Bristol, Regno Unito" restituirà una corrispondenza parziale sia per Henri Street che per Henrietta Street. Tieni presente che se una richiesta include un componente dell'indirizzo con errori ortografici, il servizio di geocodifica potrebbe suggerire un indirizzo alternativo. Anche i suggerimenti attivati in questo modo verranno contrassegnati come parziali.

  • place_id è un identificatore univoco che può essere utilizzato con altre API di Google. Ad esempio, potete utilizzare place_id in una richiesta API Places per ottenere dettagli su un'attività locale, come numero di telefono, orario di apertura, recensioni degli utenti e altro ancora. Consulta la panoramica sull'ID luogo.

Tipi di indirizzi e tipi di componenti degli indirizzi

L'array types[] nel risultato indica il tipo di indirizzo. Alcuni tipi di indirizzi sono un indirizzo, un paese o un'entità politica. È presente anche un array types[] in address_components[], 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 nell'array del tipo di indirizzo che in quello di componenti degli indirizzi:

  • street_address indica un indirizzo esatto.
  • route indica un percorso denominato (ad es. "US 101").
  • intersection indica un incrocio principale, generalmente di due strade principali.
  • political indica un'entità politica. Di solito, questo tipo indica un poligono di un'amministrazione civile.
  • country indica l'entità politica nazionale ed è in genere il tipo di ordine più elevato restituito dal Geocoder.
  • administrative_area_level_1 indica una persona giuridica del primo ordine al di sotto del livello paese. All'interno degli Stati Uniti, questi livelli amministrativi sono stati. Non tutte le nazioni mostrano questi livelli amministrativi. Nella maggior parte dei casi, i nomi brevi di admin_area_level_1 corrisponderanno molto meglio alle suddivisioni ISO 3166-2 e ad altri elenchi diffusi; tuttavia, questo non è garantito in quanto i nostri risultati di geocodifica si basano su una serie di indicatori e dati sulla posizione.
  • administrative_area_level_2 indica una persona giuridica di secondo ordine al di sotto del livello paese. All'interno degli Stati Uniti, questi livelli amministrativi sono contee. Non tutte le nazioni mostrano questi livelli amministrativi.
  • administrative_area_level_3 indica una persona giuridica terzo ordine al di sotto del livello paese. Questo tipo indica una piccola divisione civile. Non tutte le nazioni mostrano questi livelli amministrativi.
  • administrative_area_level_4 indica una persona giuridica di quarto ordine al di sotto del livello paese. Questo tipo indica una piccola divisione civile. Non tutte le nazioni mostrano questi livelli amministrativi.
  • administrative_area_level_5 indica una persona giuridica del quinto ordine al di sotto del livello paese. Questo tipo indica una piccola divisione civile. Non tutte le nazioni mostrano questi livelli amministrativi.
  • administrative_area_level_6 indica una entità civile del sesto ordine al di sotto del livello paese. Questo tipo indica una piccola divisione civile. Non tutte le nazioni mostrano questi livelli amministrativi.
  • administrative_area_level_7 indica una persona giuridica del settimo ordine sotto il livello nazionale. Questo tipo indica una piccola divisione civile. Non tutte le nazioni mostrano questi livelli amministrativi.
  • colloquial_area indica un nome alternativo di uso comune per l'entità.
  • locality indica un'entità politica di una città
  • sublocality indica un'entità civile del primo ordine sotto una località. Per alcune località potresti ricevere uno dei seguenti tipi aggiuntivi: da sublocality_level_1 a sublocality_level_5. Ogni livello locale è un'entità civile. I numeri più grandi indicano un'area geografica più piccola.
  • neighborhood indica un quartiere denominato
  • premise indica una località denominata, di solito un edificio o una serie di edifici con un nome comune
  • subpremise indica un'entità del primo ordine sotto una località denominata, in genere un edificio singolare all'interno di una raccolta di edifici con un nome comune
  • plus_code indica un riferimento a una località codificata, derivato da latitudine e longitudine. I Plus Code possono essere utilizzati come sostituzione degli indirizzi per i luoghi in cui non esistono (dove gli edifici non sono numerati o le strade non hanno un nome). Per informazioni dettagliate, visita la pagina https://plus.codes.
  • postal_code indica un codice postale utilizzato per indirizzare la posta all'interno del paese.
  • natural_feature indica una caratteristica naturale in evidenza.
  • airport indica un aeroporto.
  • park indica un parco denominato.
  • point_of_interest indica un punto d'interesse denominato. In genere, questi "PDI" sono entità locali importanti che non rientrano facilmente in un'altra categoria, come "Empire State Building" o "Eiffel Tower".

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

Oltre a quanto riportato sopra, i componenti dell'indirizzo potrebbero includere anche le tipologie elencate di seguito. Questo elenco non è completo ed è soggetto a modifiche.

  • floor indica il piano dell'indirizzo di un edificio.
  • establishment in genere indica 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 denominato.
  • parking indica un parcheggio o una struttura con parcheggio.
  • post_box indica una casella postale specifica.
  • postal_town indica un raggruppamento di aree geografiche, ad esempio locality e sublocality, utilizzate per gli indirizzi postali di alcuni paesi.
  • room indica la stanza di un indirizzo dell'edificio.
  • street_number indica il numero esatto della via.
  • bus_station, train_station e transit_station indicano la posizione di una fermata di autobus, treno o trasporto pubblico.

Differenziazione dell'area visibile

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

Ad esempio, un codice geografico 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 definisca un riquadro di delimitazione intorno alla parte nord-orientale degli Stati Uniti determina il ritorno alla 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 della regione

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

I risultati della geocodifica possono essere influenzati da ogni dominio in cui l'applicazione Google Maps principale è stata lanciata ufficialmente. Tieni presente che la differenziazione 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 codice geografico per "Toledo" restituisce questo risultato, poiché il dominio predefinito per l'API Geocoding è impostato su United States. 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 di indirizzi limitati a un'area specifica. Puoi specificare la limitazione utilizzando il filtro components. Un filtro consiste in un elenco di component:value coppie separate da una barra verticale (|). I valori dei filtri supportano gli stessi metodi di correzione ortografica e di corrispondenza parziale di altre richieste di geocodifica. Se il geocodificatore 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 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 i filtri funzionano meglio quando viene utilizzato il codice ISO corrispondente del paese.

Il seguente components può essere utilizzato per influenzare i risultati, ma non verrà applicato:

  • route corrisponde al nome lungo o breve di un percorso.
  • locality corrisponde ai tipi locality e 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 ripetuti per i componenti, l'API valuta questi filtri come AND, non come OR.
  • I risultati sono coerenti con Google Maps, che a volte restituisce risposte ZERO_RESULTS impreviste. L'utilizzo di Place Autocomplete potrebbe fornire risultati migliori in alcuni casi d'uso. Per scoprire di più, consulta queste domande frequenti.
  • Per ogni componente dell'indirizzo, specificalo nel parametro address o in un filtro components, ma non in entrambi. Se specifichi gli stessi valori in entrambi, potresti generare ZERO_RESULTS.

Un codice geografico per "High St, Hastings" con components=country:GB restituisce un risultato ad Hastings, Inghilterra, anziché Hastings-On-Hudson, USA.

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 geocodificata per la località "Santa Cruz" con components=country:ES restituisce Santa Cruz de Tenerife nelle Isole Canarie, Spagna.

Richiesta:

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

Risposta:

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

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

Richiesta:

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

Risposta:

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

Puoi eseguire query valide senza il parametro address, utilizzando il filtro components. (Quando si utilizza la geocodifica 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"
}