Richiesta e risposta di geocodifica inversa (ricerca di indirizzi)

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

Il termine geocodifica si riferisce in genere alla traduzione di un indirizzo leggibile in una località su una mappa. La procedura per il contrario, che traduce una posizione sulla mappa in un indirizzo leggibile, è nota come geocodifica inversa.

Inverti richieste di geocodifica

Parametri obbligatori

  • latlng: i valori di latitudine e longitudine che specificano la posizione per cui vuoi ottenere l'indirizzo più simile e leggibile.
  • key: chiave API della tua applicazione. Questa chiave identifica l'applicazione ai fini della gestione della quota. Scopri come ottenere una chiave.

Parametri facoltativi

Di seguito sono riportati i parametri facoltativi che puoi includere in una richiesta di geocodifica inversa:

  • 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.
  • result_type: un filtro di uno o più tipi di indirizzo, separato da una barra verticale (|). Se il parametro contiene più tipi di indirizzi, l'API restituisce tutti gli indirizzi che corrispondono a uno qualsiasi dei tipi. Una nota sull'elaborazione: il parametro result_type non limita la ricerca ai tipi di indirizzi specificati. Piuttosto, result_type funge da filtro post-ricerca: l'API recupera tutti i risultati per il latlng specificato, quindi ignora i risultati che non corrispondono ai tipi di indirizzo specificati. I seguenti valori sono supportati:
    • street_address indica un indirizzo preciso.
    • route indica un percorso denominato (ad esempio "US 101").
    • 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, queste "principali" sono entità locali di spicco che non si adattano facilmente a un'altra categoria, come "Empire State Building" o "Eiffel Tower".
  • location_type: un filtro di uno o più tipi di località, separato da una barra verticale (|). Se il parametro contiene più tipi di località, l'API restituisce tutti gli indirizzi che corrispondono a uno qualsiasi dei tipi. Una nota sull'elaborazione: il parametro location_type non limita la ricerca ai tipi di località specificati. Piuttosto, location_type funge da filtro post-ricerca: l'API recupera tutti i risultati per il latlng specificato, quindi ignora i risultati che non corrispondono ai tipi di posizione specificati. Sono supportati i seguenti valori:
    • "ROOFTOP" restituisce solo gli indirizzi per i quali Google dispone di informazioni sulla posizione accurate fino alla precisione dell'indirizzo.
    • "RANGE_INTERPOLATED" restituisce solo gli indirizzi che riflettono un'approssimazione (generalmente su una strada) interpolati tra due punti esatti (ad esempio gli incroci). In genere, un intervallo interpolato indica che le codifiche panoramiche non sono disponibili per un indirizzo.
    • "GEOMETRIC_CENTER" restituisce solo i centri geometrici di un luogo, ad esempio una polilinea (ad esempio una strada) o un poligono (area geografica).
    • "APPROXIMATE" restituisce solo gli indirizzi che sono definiti come approssimativi.

Se sono presenti entrambi i filtri result_type e location_type, l'API restituisce solo i risultati che corrispondono ai valori result_type e location_type. Se nessuno dei valori del filtro è accettabile, l'API restituisce ZERO_RESULTS.

Esempio di geocodifica inversa

La seguente query contiene il valore di latitudine/longitudine per una località a Bologna:

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

La query precedente restituisce il seguente risultato:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional <code>results[]</code> ...

Tieni presente che il geocodificatore inverso ha restituito più di un risultato. I risultati di "formatted_address" non sono solo indirizzi postali, ma un modo geografico per assegnare un nome a una località. Ad esempio, quando geocodifica un punto nella città di Chicago, il punto geocodificato può essere contrassegnato come indirizzo, come città (Chicago), come stato (Illinois) o come paese (gli Stati Uniti). Tutti sono "indirizzi" al geocodificatore. Il geocodificatore inverso restituisce uno di questi tipi come risultati validi.

Il geocodificatore inverso corrisponde a entità politiche (paesi, province, città e quartieri), indirizzi e codici postali.

Di seguito è riportato l'elenco completo dei valori formatted_address restituiti dalla query precedente.

"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11249, USA",
"formatted_address" : "Bedford Av/Grand St, Brooklyn, NY 11211, USA",
"formatted_address" : "Brooklyn, NY 11211, USA",
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
"formatted_address" : "Brooklyn, NY, USA",
"formatted_address" : "New York, NY, USA",
"formatted_address" : "New York, USA",
"formatted_address" : "United States",

In genere, gli indirizzi vengono restituiti dal più specifico al meno specifico; l'indirizzo più esatto rappresenta il risultato più in evidenza, come in questo caso. Tieni presente che restituiamo diversi tipi di indirizzi, dagli indirizzi più specifici a entità politiche meno specifiche come quartieri, città, contee, stati e così via. Se vuoi trovare una corrispondenza per un tipo di indirizzo specifico, consulta la sezione seguente su come limitare i risultati per tipo.

Geocodifica inversa in base al tipo

Il seguente esempio filtra gli indirizzi restituiti in modo da includere solo quelli con un tipo di località ROOFTOP e un tipo indirizzo street_address.

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

Nota: questi filtri sono validi solo per la geocodifica inversa.

Inverti risposte geocodificate

Il formato della risposta di geocodifica inversa è la stessa della risposta di geocodifica. Consulta la sezione Risposte geocodificate. Di seguito sono riportati i codici di stato possibili in una risposta di geocodifica inversa.

Inverti codici di stato di geocodifica

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

  • "OK" indica che non si sono verificati errori e che è stato restituito almeno un indirizzo.
  • "ZERO_RESULTS" indica che la geocodifica inversa è riuscita, ma non ha restituito risultati. Questa situazione può verificarsi se il geocodificatore ha superato un latlng in una località remota.
  • "OVER_QUERY_LIMIT" indica che hai superato la quota.
  • "REQUEST_DENIED" indica che la richiesta è stata rifiutata. Probabilmente perché la richiesta include un parametro result_type o location_type, ma non una chiave API.
  • "INVALID_REQUEST" in genere indica uno dei seguenti elementi:
    • Manca la query (address, components o latlng).
    • È stato specificato un valore result_type o location_type non valido.
  • "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.

Plus Code geocodifica inversa

Il campo plus_code all'interno dell'oggetto di risposta Geocoding contiene un Plus Code che meglio si riferisce alla latitudine e alla longitudine della query. Inoltre, l'array dei risultati JSON conterrà nella maggior parte dei casi un risultato di geocodifica completo con tipo plus_code e indirizzo contenente un plus code. La distanza tra il plus code decodificato e il punto di richiesta è garantita per essere inferiore a 10 metri.