Richiesta e risposta di geocodifica inversa (ricerca di indirizzi)

Il termine geocodifica si riferisce in genere alla traduzione di un indirizzo in formato leggibile da una persona in una posizione su una mappa. Il processo opposto, ovvero la traduzione di una posizione sulla mappa in un indirizzo leggibile, è noto come geocodifica inversa.

Richieste di geocodifica inversa

Parametri obbligatori

  • latlng: le coordinate di latitudine e longitudine che specificano la posizione per la quale vuoi l'indirizzo più vicino e leggibile.
  • key: la chiave API della tua applicazione. Questa chiave identifica la tua applicazione ai fini della gestione delle quote. 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. Google aggiorna spesso le lingue supportate, pertanto questo elenco potrebbe non essere esaustivo.
    • Se language non viene fornito, il geocodificatore tenta di utilizzare la lingua preferita specificata nell'Accept-Language header o la lingua nativa del dominio da cui viene inviata la richiesta.
    • Il geocodificatore fa del suo meglio per fornire un indirizzo stradale ben leggibile sia per l'utente sia per le persone del posto. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in un script leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo vengono restituiti tutti nella stessa lingua, che viene scelta dal primo componente.
    • Se un nome non è disponibile nella lingua preferita, il geocodificatore utilizza la corrispondenza più simile.
  • region: il codice regione, specificato come valore di due caratteri di un ccTLD ("dominio di primo livello"). Il parametro può anche influire sui risultati in base alla legge vigente.
  • result_type: un filtro di uno o più tipi di indirizzi, separati da una barra verticale (|). Se il parametro contiene più tipi di indirizzi, l'API restituisce tutti gli indirizzi che corrispondono a uno dei tipi. Una nota sull'elaborazione: il parametro result_type non limita la ricerca ai tipi di indirizzi specificati. ma come un result_type agisce come filtro post-ricerca: l'API recupera tutti i risultati per il result_type specificato, quindi elimina quelli che non corrispondono ai tipi di indirizzo specificati. I seguenti valori sono supportati:
      latlng
    • street_address indica un indirizzo stradale preciso.
    • route indica un percorso denominato (ad esempio "US 101").
    • intersection indica un incrocio importante, di solito di 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 ed è tipicamente 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 del paese. Negli Stati Uniti, questi livelli amministrativi sono gli stati. Non tutti i paesi presentano questi livelli amministrativi. Nella maggior parte dei casi, i nomi brevi di administrative_area_level_1 corrispondono quasi esattamente alle suddivisioni ISO 3166-2 e ad altri elenchi molto diffusi. Tuttavia, non è garantito, in quanto i risultati del nostro geocoding si basano su una serie di indicatori e dati sulla posizione.
    • administrative_area_level_2 indica un'entità civile di secondo ordine al di sotto del livello del paese. Negli Stati Uniti, questi livelli amministrativi sono le contee. Non tutti i paesi presentano questi livelli amministrativi.
    • administrative_area_level_3 indica un'entità civile di terzo ordine al di sotto del livello di paese. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
    • administrative_area_level_4 indica una persona giuridica civile di quarto ordine al di sotto del livello di paese. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
    • administrative_area_level_5 indica un'entità civile di quinto ordine al di sotto del livello di paese. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
    • administrative_area_level_6 indica un'entità civile di sesto ordine al di sotto del livello del paese. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
    • administrative_area_level_7 indica un'entità civile di settimo ordine al di sotto del livello di paese. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
    • colloquial_area indica un nome alternativo di uso comune per l'entità.
    • locality indica un'entità politica costituita come città o paese.
    • sublocality indica un'entità civile di primo ordine al di sotto di una località. Per alcune località potrebbe essere visualizzato uno dei seguenti tipi aggiuntivi: sublocality_level_1 a sublocality_level_5. Ogni livello di sottolocalità è un'entità civile. 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 una raccolta di edifici con un nome comune.
    • subpremise indica un'entità indirizzabile al di sotto del livello della struttura, ad esempio un appartamento, un'unità o una suite.
    • plus_code indica un riferimento alla posizione codificato, ricavato da latitudine e longitudine. I Plus Code possono essere utilizzati al posto degli indirizzi 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 la spedizione della posta tradizionale all'interno del paese.
    • natural_feature indica una caratteristica naturale prominente.
    • airport indica un aeroporto.
    • park indica un parco denominato.
    • point_of_interest indica un punto d'interesse denominato. In genere, questi "PDV" sono entità locali di spicco che non rientrano facilmente in un'altra categoria, come "Empire State Building" o "Torre Eiffel".
  • location_type: un filtro di uno o più tipi di località, separati da una barra verticale (|). Se il parametro contiene più tipi di località, l'API restituisce tutti gli indirizzi corrispondenti a uno dei tipi. Una nota sull'elaborazione: il parametro location_type non limita la ricerca ai tipi di località specificati. Al contrario, location_type funge da filtro post-ricerca: l'API recupera tutti i risultati per il location_type specificato, quindi elimina quelli che non corrispondono ai tipi di località specificati.latlng Sono supportati i seguenti valori:
    • "ROOFTOP" restituisce solo gli indirizzi per i quali Google dispone di informazioni sulla posizione precise fino al numero civico.
    • "RANGE_INTERPOLATED" restituisce solo gli indirizzi che riflettono un'approssimazione (di solito su una strada) interpolata tra due punti precisi (ad esempio incroci). In genere, un intervallo interpolato indica che i codici geografici dei tetti non sono disponibili per un indirizzo.
    • "GEOMETRIC_CENTER" restituisce solo i centri geometrici di una località, ad esempio una polilinea (ad esempio una strada) o un poligono (regione).
    • "APPROXIMATE" restituisce solo gli indirizzi caratterizzati come approssimativi.
  • extra_computations: utilizza questo parametro per specificare le seguenti funzionalità aggiuntive nella risposta: Per attivare più di queste funzionalità per la stessa richiesta API, includi il parametro extra_computations nella richiesta per ogni funzionalità, ad esempio: 
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

Se sono presenti entrambi i filtri result_type e location_type, l'API restituisce solo i risultati che corrispondono sia ai valori result_type sia ai valori 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à di Brooklyn:

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 "formatted_address" non sono solo indirizzi postali, ma qualsiasi modo per assegnare un nome geografico a una località. Ad esempio, quando esegui la geocodifica di un punto nella città di Chicago, il punto geocodificato può essere indicato come indirizzo, come città (Chicago), come stato (Illinois) o come paese (Stati Uniti). Per il geocodificatore sono tutti "indirizzi". Il geocodificatore inverso restituisce qualsiasi di questi tipi come risultati validi.

Il geocodificatore inverso abbina 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.

{
   "plus_code" : {
      "compound_code" : "P27Q+MCM New York, NY, USA",
      "global_code" : "87G8P27Q+MCM"
   },
   "results" : [
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "street_address" ]
      },
      {
         "formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "premise" ]
      },
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "establishment", "point_of_interest" ]
      },
      {
         "formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "route" ]
      },
      {
         "formatted_address" : "P27Q+MC New York, NY, USA",
         ...
         "types" : [ "plus_code" ]
      },
      {
         "formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY 11211, USA",
         ...
         "types" : [ "postal_code" ]
      },
      {
         "formatted_address" : "Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Kings County, Brooklyn, NY, USA",
         ...
         "types" : [ "administrative_area_level_2", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY, USA",
         ...
         "types" : [ "political", "sublocality", "sublocality_level_1" ]
      },
      {
         "formatted_address" : "New York, NY, USA",
         ...
         "types" : [ "locality", "political" ]
      },
      {
         "formatted_address" : "New York, USA",
         ...
         "types" : [ "administrative_area_level_1", "political" ]
      },
      {
         "formatted_address" : "United States",
         ...
         "types" : [ "country", "political" ]
      }
   ],
   "status" : "OK"
}

Questa API restituisce diversi tipi di indirizzi, dall'indirizzo stradale più specifico a entità politiche meno specifiche come quartieri, città, contee e stati. L'indirizzo più preciso è in genere il risultato più in evidenza, come in questo caso. Se vuoi trovare una corrispondenza per un tipo specifico di indirizzo, consulta la sezione di seguito sulla limitazione dei risultati in base al tipo. Per questo motivo, la posizione dei risultati rispetto l'una all'altra può variare.

Geocodifica inversa filtrata per tipo

L'esempio seguente filtra gli indirizzi restituiti in modo da includere solo quelli con un tipo di località ROOFTOP e un tipo di 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 il geocodice inverso.

Risposte alla geocodifica inversa

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

Codici di stato della geocodifica inversa

Il campo "status" all'interno dell'oggetto della risposta di geocodifica contiene lo stato della richiesta e potrebbe contenere informazioni di debug per aiutarti a risalire al motivo per cui il geocodice inverso 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 il geocodifica inversa è riuscita, ma non ha restituito risultati. Ciò può accadere se al geocodificatore è stato passato un latlng in una posizione remota.
  • "OVER_QUERY_LIMIT" indica che hai superato la quota.
  • "REQUEST_DENIED" indica che la richiesta è stata rifiutata. È possibile che la richiesta includa un parametro result_type o location_type, ma non una chiave API.
  • "INVALID_REQUEST" indica in genere uno dei seguenti casi:
    • La query (address, components o latlng) non è presente.
    • È stato fornito 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. La richiesta potrebbe andare a buon fine se provi di nuovo.

Geocodifica inversa dei plus code

Il campo plus_code all'interno della risposta di geocodifica contiene un codice plus che approssima al meglio la latitudine e la longitudine richieste. Inoltre, nella maggior parte dei casi l'array di risultati JSON contiene un risultato di geocodifica completo con un tipo plus_code e un indirizzo contenente un codice plus. La distanza tra il codice Plus decodificato e il punto di richiesta è garantita essere inferiore a 10 metri.