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 all'API Geocoding ha il seguente formato:

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

dove outputFormat può essere uno dei seguenti valori:

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

Per le richieste che utilizzano una chiave API è necessario HTTPS.

Alcuni parametri sono obbligatori, mentre altri sono facoltativi. Come avviene per gli URL, i parametri sono separati utilizzando la e commerciale (&).

Il resto di questa pagina descrive la geocodifica e la codifica geografica 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. Dovresti evitare elementi aggiuntivi dell'indirizzo, come il nome dell'attività e il numero di interno, interno o interno. Gli elementi dell'indirizzo devono essere delimitati da spazi (mostrati qui come escape tramite URL in %20):
    address=24%20Sussex%20Drive%20Ottawa%20ON
    Formato dei Plus Code come mostrato qui (più gli indicatori devono contenere caratteri di escape in %2B e gli spazi devono contenere caratteri di escape in %20):
    • Il codice globale è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9 è 849VCWC8%2BR9).
    • compound code è un codice locale di almeno 6 caratteri con 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 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. Leggi ulteriori informazioni 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 bias i risultati di geocodifica sono più evidenti. Questo parametro influisce solo sui risultati del geocodificatore, non limitandoli. Per ulteriori informazioni, consulta la sezione Basamento dell'area visibile 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 cerca di fornire un indirizzo che sia leggibile sia per l'utente sia per i locali. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in uno script leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. Tutti i componenti dell'indirizzo vengono restituiti nella stessa lingua, scelta dal primo componente.
    • Se un nome non è disponibile nella lingua preferita, il geocodificatore utilizza la corrispondenza più simile.
    • Il linguaggio preferito ha una piccola influenza sul set di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Il geocodificatore interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni per i tipi di 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 quadrata rispettivamente in ungherese.
  • region: il codice della regione, specificato come valore di due caratteri ccTLD ("dominio di primo livello"). Questo parametro influisce solo sui risultati del geocodificatore, non limitandoli completamente. Per ulteriori informazioni, consulta la sezione Differenziazione per area geografica 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. Leggi ulteriori informazioni sul filtro dei componenti di seguito.

Risposte

Le risposte di geocodifica vengono restituite nel formato indicato dal flag output nel percorso della richiesta dell'URL.

In questo esempio, l'API Geocoding richiede una risposta json per una query sull'ID luogo "ChIJeRpOeF67j4AR9ydy_PIzPuM", che è il luogo_ID dell'edificio al 1600 Amphitheatre Parkway, Mountain View, CA.

Questa richiesta dimostra l'utilizzo 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 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 geometriche e sull'indirizzo geocodificate.

In genere, viene restituita solo una voce nell'array di "results" per le ricerche di indirizzi,anche se il geocodificatore può restituire diversi risultati quando le query relative agli 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>

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

  • <status> contiene metadati nella richiesta. Consulta Codici di stato di seguito.
  • Zero o più elementi <result>, ognuno dei quali contiene un singolo set di informazioni geometriche e di indirizzi geocodificati.

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 attenzione, per cui devi fare riferimento ai nodi e agli elementi appropriati. Consulta Analisi di XML con XPath per alcuni pattern di progettazione consigliati per l'elaborazione degli output.

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

Codici di stato

Il campo "status" all'interno dell'oggetto di risposta Geocoding contiene lo stato della richiesta e 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 è stato restituito almeno un codice geografico.
  • "ZERO_RESULTS" indica che la geocodifica è riuscita, ma non ha restituito risultati. Questo può verificarsi se al geocodificatore viene trasmesso un elemento address inesistente.
  • OVER_DAILY_LIMIT indica uno dei seguenti elementi:
    • La chiave API non è presente o non è valida.
    • La fatturazione non è stata attivata nel tuo account.
    • È stato superato un limite di utilizzo autoimposta.
    • Il metodo di pagamento fornito non è più valido (ad es. una carta di credito è scaduta).

    Per informazioni su come risolvere il problema, consulta le domande frequenti su Maps.

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

Messaggi di errore

Quando il geocodificatore restituisce un codice di stato diverso da OK, potrebbe essere presente un campo aggiuntivo error_message nell'oggetto della risposta Geocoding. Questo campo contiene informazioni più dettagliate sui motivi per cui è stato specificato il codice di stato.

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 elemento geografico "Chicago" restituisce "località" che indica che "Chicago" è una città e restituisce "politico" che indica un'entità politica.
  • formatted_address è una stringa contenente l'indirizzo leggibile di questa località.

    Spesso questo indirizzo è equivalente all'indirizzo postale. Tieni presente che alcuni paesi, come il Regno Unito, non consentono la distribuzione di indirizzi postali reali 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" (il percorso), "New York" (la città) e "NY" (lo stato americano).

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

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

    Ciascun 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 completa del testo o il nome del componente dell'indirizzo restituito dal Geocoder.
    • short_name è un nome testuale abbreviato per il componente dell'indirizzo, se disponibile. Ad esempio, un componente indirizzo per lo stato dell'Alaska può avere una classe long_name di "Alaska" e un short_name di "AK" utilizzando l'abbreviazione postale di due lettere.

    Osserva le seguenti informazioni sull'array di address_components[]:

    • L'array dei componenti indirizzo può contenere più componenti di formatted_address.
    • L'array non include necessariamente tutte le entità politiche che contengono un indirizzo, oltre a quelle incluse in 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 alla richiesta.
    • Non è garantito che il formato della risposta rimanga invariato tra le richieste. In particolare, il numero di address_components varia in base all'indirizzo richiesto e può cambiare nel tempo per lo stesso indirizzo. Un componente può cambiare la posizione nell'array. Il tipo del componente può cambiare. Un determinato componente potrebbe mancare in una risposta successiva.

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

  • postcode_localities[] è un array che indica 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, la longitudine geocodificata. 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 è una geocodifica esatta per cui 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 (come incroci). In genere, i risultati interpolati vengono 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 l'angolo di southwest e northeast del riquadro di delimitazione dell'area visibile. In genere, l'area visibile viene utilizzata per inquadrare un risultato quando viene mostrato a un utente.
    • (Facoltativo) bounds archivia il riquadro di delimitazione che può contenere completamente il risultato restituito. Tieni presente che questi limiti potrebbero non corrispondere all'area visibile 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 località e più codici) è un riferimento di posizione codificato, derivato da coordinate di latitudine e longitudine, che rappresenta un'area: 1/8000 di grado per 1/8000 di grado (circa 14 m x 14 m dall'equatore) o inferiore. I Plus Code possono essere utilizzati in sostituzione degli indirizzi in luoghi in cui non esistono (dove gli edifici non sono numerati o i nomi delle strade).

    Il Plus Code è formattato come un codice globale e un codice composto:

    • global_code è un prefisso di 4 caratteri e un codice locale di 6 caratteri o più (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.
    In genere, vengono restituiti 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 era in grado di corrispondere a parte dell'indirizzo richiesto. Ti consigliamo di esaminare la richiesta originale 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à specificata 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 Henry Street che per Henrietta Street. Tieni presente che se una richiesta include un componente indirizzo errato, il servizio di geocodifica potrebbe suggerire un indirizzo alternativo. Anche i suggerimenti attivati in questo modo verranno contrassegnati come corrispondenze parziali.

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

Tipi di indirizzo e componenti di indirizzo

L'array types[] nel risultato indica il tipo di indirizzo. Alcuni tipi di indirizzi sono un indirizzo, un paese o un'entità politica. C'è anche un array types[] in address_components[], che indica il tipo di ciascuna 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 taggate con il tipo political e locality.

I seguenti tipi sono supportati e restituiti dal geocodificatore sia negli array di tipi di indirizzo che di tipo di componenti dell'indirizzo:

  • street_address indica un indirizzo preciso.
  • route indica un percorso denominato (ad es. "101 US").
  • intersection indica un incrocio principale, generalmente composto da due strade principali.
  • political indica un'entità politica. Di solito, questo tipo indica un poligono di qualche amministrazione civile.
  • country indica l'entità politica nazionale e in genere è il tipo di ordine più elevato restituito dal Geocoder.
  • administrative_area_level_1 indica un'entità civile di primo ordine al di sotto del paese. All'interno degli Stati Uniti, questi livelli amministrativi sono stati. Non tutti i paesi espongono questi livelli amministrativi. Nella maggior parte dei casi, i nomi brevi di admin_area_level_1 corrisponderanno strettamente alle suddivisioni ISO 3166-2 e ad altri elenchi diffusi; tuttavia, ciò non è garantito in quanto i risultati della geocodifica si basano su una serie di indicatori e dati sulla posizione.
  • administrative_area_level_2 indica un'entità civile del secondo ordine sotto il livello del paese. All'interno degli Stati Uniti, questi livelli amministrativi sono contee. Non tutti i paesi espongono questi livelli amministrativi.
  • administrative_area_level_3 indica un'entità civile del terzo ordine sotto il livello del paese. Questo tipo indica una circoscrizione civile secondaria. Non tutti i paesi espongono questi livelli amministrativi.
  • administrative_area_level_4 indica un'entità civile del quarto ordine sotto il livello del paese. Questo tipo indica una circoscrizione civile secondaria. Non tutti i paesi espongono questi livelli amministrativi.
  • administrative_area_level_5 indica un'entità civile di quinto ordine al di sotto del livello paese. Questo tipo indica una circoscrizione civile secondaria. Non tutti i paesi espongono questi livelli amministrativi.
  • administrative_area_level_6 indica un'entità civile del sesto ordine al di sotto del livello del paese. Questo tipo indica una circoscrizione civile secondaria. Non tutti i paesi espongono questi livelli amministrativi.
  • administrative_area_level_7 indica un'entità civile del settimo ordine sotto il livello del paese. Questo tipo indica una circoscrizione civile secondaria. Non tutti i paesi espongono questi livelli amministrativi.
  • colloquial_area indica un nome alternativo di uso comune per l'entità.
  • locality indica un'entità politica costituita in città.
  • sublocality indica una persona giuridica 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'entità civile. I numeri più grandi indicano un'area geografica più piccola.
  • neighborhood indica un quartiere denominato
  • premise indica una località denominata, in genere un edificio o una serie di edifici con un nome comune
  • subpremise indica un'entità di primo ordine sotto una località denominata, in genere un singolo edificio 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 in sostituzione degli indirizzi stradali in luoghi in cui non esistono (dove gli edifici non sono numerati o le strade non hanno un nome). Per maggiori dettagli, 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 di interesse denominato. In genere, questi "PDI" sono entità locali di spicco che non si adattano facilmente a un'altra categoria, come "Empire State Building" o "Eiffel Tower".

Un elenco vuoto dei tipi indica che non ci sono tipi noti per il particolare componente indirizzo, ad esempio Lieu-dit in Francia.

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

  • floor indica il piano dell'indirizzo di un edificio.
  • establishment in genere indica un luogo non ancora classificato.
  • landmark indica un luogo vicino che viene utilizzato come riferimento per agevolare la navigazione.
  • point_of_interest indica un punto di interesse denominato.
  • parking indica un parcheggio o una struttura per il parcheggio.
  • post_box indica una casella postale specifica.
  • postal_town indica un raggruppamento di aree geografiche, come locality e sublocality, utilizzate per gli indirizzi postali in 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.

bias 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). Puoi farlo nell'URL della richiesta impostando il parametro bounds.

Il parametro bounds definisce le coordinate di latitudine/longitudine degli angoli sud-ovest e nord-est di questo riquadro di 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 definisce un riquadro di delimitazione nella parte nord-orientale degli Stati Uniti fa sì che questo codice geografico restituisca la città di Washington, D.C.:

Richiesta:

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

Risposta:

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

Differenziazione per regione

In una richiesta di geocodifica, puoi indicare al servizio di geocodifica di restituire i risultati suddivisi 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à del "Regno Unito di Gran Bretagna e Irlanda del Nord").

I risultati di geocodifica possono essere di parte per ciascun dominio in cui è stata lanciata ufficialmente l'applicazione Google Maps principale. Tieni presente che solo i bias preferiscono 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 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 di "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 a indirizzi limitati a un'area specifica. Puoi specificare la restrizione utilizzando il filtro components. Un filtro consiste in 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 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 è possibile filtrare 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 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 a locality e sublocality.
  • administrative_area corrisponde a tutti i livelli di administrative_area.

Note sul filtro dei componenti:

  • Non ripetere questi filtri dei componenti nelle richieste; in caso contrario l'API restituirà Invalid_request: country, postal_code, route
  • Se la richiesta contiene filtri componenti ripetuti, l'API valuta tali 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 può offrire 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 entrambi. Se specifichi gli stessi valori in entrambi, potrebbe essere visualizzato ZERO_RESULTS.

Un codice geografico per "High St, Hastings" con components=country:GB restituisce un risultato ad Hastings, in Inghilterra, anziché a 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à di "Santa Cruz" con components=country:ES restituisce Santa Cruz de Tenerife alle Isole Canarie, in 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 dell'indirizzo 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"
}