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 JavaScript Object Notation (JSON); oppure
  • xml indica un output in XML

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

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

Il resto della pagina descrive separatamente la geocodifica e la geocodifica inversa, in quanto 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 interessato. È consigliabile evitare elementi aggiuntivi relativi all'indirizzo, come nomi di attività e numeri di unità, suite o piano. Gli elementi dell'indirizzo devono essere delimitati da spazi (mostrati qui come caratteri di escape dell'URL in %20):
    address=24%20Sussex%20Drive%20Ottawa%20ON
    Formato e codici aggiuntivi come mostrato qui (i segni più vengono preceduti da caratteri di escape negli URL in %2B e gli spazi vengono preceduti da URL di escape 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 elemento 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: 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 polarizzare i risultati geocodificati in modo più evidente. Questo parametro influenzerà solo i risultati del geocodificatore, ma non limiterà completamente i risultati. 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 completo.
    • 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 suo meglio per fornire un indirizzo che sia leggibile sia per l'utente sia per le persone del posto. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in un testo 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 per tipi di strade, o i sinonimi che potrebbero essere validi in una lingua ma non in un'altra. Ad esempio, utca e tér sono sinonimi rispettivamente di strada e quadrato in ungherese.
  • region: il codice regione, specificato come valore a due caratteri ccTLD ("dominio di primo livello"). Questo parametro influenzerà solo i risultati del geocodificatore, ma non li limiterà completamente. Per ulteriori informazioni, consulta la sezione Differenziazione delle regioni di seguito. Il parametro può influire sui risultati anche in base alla legge vigente.
  • components: un filtro dei componenti con elementi separati da una barra verticale (|). Il filtro dei componenti è obbligatorio se la richiesta non include 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 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.

Questa richiesta mostra l'utilizzo del flag output JSON:

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

Questa richiesta dimostra l'utilizzo del flag output XML:

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

Seleziona le schede di seguito 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 può 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 la sezione Codici di stato di seguito.
  • Zero o più elementi <result>, ciascuno contenente un singolo set di informazioni sugli indirizzi geocodificati e 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 strutture XML richiede un po' di attenzione, in modo da poter fare riferimento a nodi ed elementi appropriati. Consulta Analisi di XML con XPath per alcuni pattern di progettazione consigliati per l'elaborazione dell'output.

  • I risultati XML sono 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 non gli elementi <result> in XML, ad esempio.

Codici di stato

Il campo "status" all'interno dell'oggetto di risposta Geocoding contiene lo stato della richiesta e potrebbe contenere informazioni di debug che consentono di individuare il motivo per cui 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 alcun risultato. Questo può accadere se al geocodificatore è stato trasmesso un codice address inesistente.
  • OVER_DAILY_LIMIT indica una delle seguenti condizioni:
    • Chiave API mancante o non valida.
    • La fatturazione non è stata attivata 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 quota.
  • "REQUEST_DENIED" indica che la tua richiesta è stata rifiutata.
  • "INVALID_REQUEST" in genere indica 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 andare a buon fine.

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 Geocodifica. Questo campo contiene informazioni più dettagliate sui motivi alla base del codice di stato specificato.

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 di risultato restituito. Questo array contiene un insieme di zero o più tag che identificano il tipo di funzionalità restituito nel risultato. Ad esempio, un codice geografico 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 quando non esistono tipi noti per quel componente di indirizzo. L'API potrebbe aggiungere nuovi valori di tipo secondo necessità. Per saperne di più, vedi Tipi di indirizzo e componenti degli indirizzi.
  • formatted_address è una stringa contenente l'indirizzo leggibile di questa sede.

    Spesso questo indirizzo corrisponde all'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 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 USA).

    Non analizzare l'indirizzo formattato in modo programmatico. Devi invece utilizzare i singoli componenti dell'indirizzo, che la risposta dell'API include in aggiunta al campo 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 dell'indirizzo. Consulta l'elenco dei tipi supportati.
    • long_name è la descrizione di testo completa o il nome del componente dell'indirizzo come restituito dal geocodificatore.
    • short_name è un nome testuale abbreviato per il componente dell'indirizzo, se disponibile. Ad esempio, un componente dell'indirizzo per lo stato dell'Alaska può avere long_name di "Alaska" e short_name di "AK" utilizzando l'abbreviazione postale a due lettere.

    Tieni presente le seguenti informazioni relative all'array address_components[]:

    • L'array di componenti degli indirizzi 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, 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 posizione nell'array. Il tipo di componente può cambiare. In una risposta successiva potrebbe mancare un componente specifico.

    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 il valore di latitudine e longitudine geocodificate. Per le normali ricerche di indirizzi, questo campo è in genere il più importante.
    • location_type memorizza dati aggiuntivi sulla località specificata. Attualmente sono supportati i seguenti valori:

      • "ROOFTOP" indica che il risultato restituito è un codice geografico preciso per il quale disponiamo di informazioni sulla posizione accurate in base 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 (regione).
      • "APPROXIMATE" indica che il risultato restituito è approssimativo.
    • viewport contiene l'area visibile consigliata per visualizzare il risultato restituito, con due valori di latitudine e longitudine che definiscono l'angolo 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 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 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 m 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 sono presenti (ovvero dove gli edifici non sono numerati o le strade non hanno nomi). 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 una parte dell'indirizzo richiesto. Ti consigliamo di esaminare la richiesta originale per verificare la presenza di errori ortografici e/o un indirizzo incompleto.

    Nella maggior parte dei casi, le corrispondenze parziali si verificano 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 dell'API Places per ottenere i dettagli di un'attività locale, come il numero di telefono, l'orario di apertura, le recensioni degli utenti e altro ancora. Vedi la panoramica su 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[] è presente anche un array types[], che indica il tipo di ogni parte dell'indirizzo. Alcuni esempi sono il numero civico o il paese. Di seguito è riportato un elenco completo dei tipi. Gli indirizzi possono 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 nelle matrici di tipo indirizzo e tipo di componente indirizzo:

  • street_address indica un indirizzo preciso.
  • route indica una route con nome (ad esempio "US 101").
  • intersection indica un incrocio principale, in genere due strade principali.
  • political indica un'entità politica. In genere, questo tipo indica un poligono di un'amministrazione civile.
  • country indica l'entità politica nazionale e rappresenta in genere il tipo di ordine più elevato restituito dal geocodificatore.
  • administrative_area_level_1 indica un'entità civile di primo ordine al di sotto del livello di paese. Negli Stati Uniti, questi livelli amministrativi sono stati. Non tutte le nazioni presentano questi livelli amministrativi. Nella maggior parte dei casi, i nomi brevi amministrativi_area_level_1 corrisponderanno strettamente alle suddivisioni ISO 3166-2 e ad altri elenchi diffusi; tuttavia, ciò non è garantito perché i nostri risultati di geocodifica si basano su una varietà di segnali e dati sulla posizione.
  • administrative_area_level_2 indica un'entità civile di secondo ordine inferiore al livello di paese. Negli Stati Uniti, questi livelli amministrativi sono contee. Non tutte le nazioni presentano questi livelli amministrativi.
  • administrative_area_level_3 indica un'entità civile di terzo ordine inferiore al livello di paese. 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 inferiore al paese. 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 inferiore al paese. Questo tipo indica una divisione civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
  • administrative_area_level_6 indica un'entità civile di sesto ordine inferiore al paese. Questo tipo indica una divisione civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
  • administrative_area_level_7 indica un'entità civile di settimo ordine inferiore al paese. 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 un comune incorporato.
  • 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 rappresenta un'entità 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à di primo ordine sotto una località con nome, in genere un singolo edificio all'interno di un insieme di edifici con un nome comune.
  • plus_code indica un riferimento della posizione codificato, 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 nomi). Vedi https://plus.codes per i dettagli.
  • postal_code indica un codice postale utilizzato per l'invio della posta all'interno del 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 un'altra categoria, come "Empire State Building" o "Torre Eiffel".

Un elenco di tipi vuoto indica che non esistono tipi noti per il componente dell'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 in genere indica un luogo che non è stato ancora 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.
  • post_box indica una casella postale specifica.
  • postal_town indica un raggruppamento di aree geografiche, come locality e sublocality, utilizzato per gli indirizzi postali in alcuni paesi.
  • room indica la stanza dell'indirizzo di un edificio.
  • street_number indica il numero civico esatto.
  • bus_station, train_station e transit_station 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 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, imposta 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.

Ad esempio, un geocodificato per "Washington" in genere restituisce lo stato di Washington:

Richiesta:

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

Risposta:

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

Tuttavia, l'aggiunta di un argomento bounds che definisce un riquadro di delimitazione intorno alla parte nordorientale 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 con bias in una determinata regione utilizzando il parametro region. Questo parametro utilizza un argomento ccTLD (dominio di primo livello per il codice paese) che specifica la differenziazione 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 di geocodifica possono essere differenziati per ogni dominio in cui è stata lanciata ufficialmente l'applicazione principale di Google Maps. 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 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 restrizione 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 del 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.

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 corrispondenze con i tipi locality e sublocality.
  • administrative_area corrisponde a tutti i livelli di administrative_area.

Note sui filtri 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 di componenti ripetuti, l'API li valuta come AND, non OR.
  • I risultati sono coerenti con Google Maps, che a volte restituisce 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 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 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 geocodifica 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 creare query valide senza il parametro dell'indirizzo utilizzando il filtro components. (quando geocodifica 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"
}