Richiesta e risposta di geocodifica inversa (ricerca di indirizzi)

Sviluppatori dello Spazio economico europeo (SEE)

Il termine geocodifica in genere si riferisce alla conversione di un indirizzo leggibile in una posizione su una mappa. La procedura opposta, ovvero la traduzione di una posizione sulla mappa in un indirizzo leggibile, è nota come geocodifica inversa.

Richieste di geocodifica inversa

Parametri obbligatori

  • latlng: le coordinate di latitudine e longitudine che specificano la posizione per cui 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

Questi sono 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, quindi questo elenco potrebbe non essere esaustivo.
    • Se language non viene fornito, il geocoder tenta di utilizzare la lingua preferita specificata nell'intestazione Accept-Language o la lingua nativa del dominio da cui viene inviata la richiesta.
    • Il geocoder fa del suo meglio per fornire un indirizzo stradale leggibile sia per l'utente sia per gli abitanti del luogo. Per raggiungere questo obiettivo, restituisce gli indirizzi stradali nella lingua locale, traslitterati in un sistema di scrittura 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ù vicina.
  • region: il codice regione, specificato come valore di due caratteri ccTLD ("dominio di primo livello"). Il parametro può influire anche sui risultati in base alla legge vigente.
  • result_type: un filtro di uno o più tipi di indirizzo, separati da una barra verticale (|). Se il parametro contiene più tipi di indirizzo, l'API restituisce tutti gli indirizzi che corrispondono a uno qualsiasi dei tipi. Una nota sul trattamento: il parametro result_type non limita la ricerca ai tipi di indirizzo specificati. result_type funge da filtro post-ricerca: l'API recupera tutti i risultati per latlng specificato, quindi scarta quelli che non corrispondono ai tipi di indirizzo specificati. Sono supportati i seguenti valori:

    Tipi di indirizzo e tipi di componenti dell'indirizzo

    L'array types nel corpo GeocodeResult della risposta indica il tipo di indirizzo. Esempi di tipi di indirizzo includono un indirizzo stradale, un paese o un'entità politica. L'array types nel campo AddressComponents del corpo GeocodeResult indica il tipo di ogni parte dell'indirizzo. Alcuni esempi sono il numero civico o il paese.

    Gli indirizzi possono avere più tipi. I tipi possono essere considerati "tag". Ad esempio, molte città sono taggate con i tipi political e locality.

    I seguenti tipi sono supportati e restituiti sia negli array di tipi di indirizzo sia in quelli di componenti di indirizzo:

    Tipo di indirizzo Descrizione
    street_address Un indirizzo preciso.
    route Un percorso denominato (ad esempio "US 101").
    intersection Un incrocio importante, di solito tra due strade principali.
    political Un'entità politica. In genere, questo tipo indica un poligono di un'amministrazione civile.
    country L'entità politica nazionale, in genere il tipo di ordine più elevato restituito dal geocodificatore.
    administrative_area_level_1 Una divisione amministrativa principale al di sotto del livello nazionale. 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 administrative_area_level_1 corrispondono strettamente alle suddivisioni ISO 3166-2 e ad altri elenchi ampiamente diffusi; tuttavia, ciò non è garantito, in quanto i nostri risultati di geocodifica si basano su una serie di indicatori e dati sulla posizione.
    administrative_area_level_2 Un'entità civile di secondo ordine al di sotto del livello nazionale. Negli Stati Uniti, questi livelli amministrativi sono le contee. Non tutti i paesi presentano questi livelli amministrativi.
    administrative_area_level_3 Un'entità civile di terzo ordine al di sotto del livello nazionale. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
    administrative_area_level_4 Un'entità civile di quarto ordine al di sotto del livello nazionale. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
    administrative_area_level_5 Un'entità civile di quinto ordine inferiore al livello nazionale. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
    administrative_area_level_6 Un'entità civile di sesto ordine al di sotto del livello nazionale. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
    administrative_area_level_7 Un'entità civile di settimo ordine al di sotto del livello nazionale. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
    colloquial_area Un nome alternativo comunemente utilizzato per l'entità.
    locality Un'entità politica di una città o di un comune costituita in società.
    sublocality Una divisione amministrativa principale sotto una località. Per alcune località potrebbe essere visualizzato uno dei tipi aggiuntivi: sublocality_level_1 - sublocality_level_5. Ogni livello di località secondaria è un'entità civile. Numeri più grandi indicano un'area geografica più piccola.
    neighborhood Un quartiere con nome.
    premise Una località denominata, solitamente un edificio o un insieme di edifici con un nome comune.
    subpremise Un'entità indirizzabile al di sotto del livello dell'edificio, ad esempio un appartamento, un'unità o una suite.
    plus_code Un riferimento alla 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 un nome). Per ulteriori dettagli, visita la pagina https://plus.codes.
    postal_code Un codice postale utilizzato per la spedizione della posta tradizionale di un paese.
    natural_feature Un elemento naturale prominente.
    airport Un aeroporto.
    park Un parco con nome.
    point_of_interest Un punto d'interesse con nome. In genere, questi "POI" sono entità locali importanti che non rientrano facilmente in un'altra categoria, ad esempio "Empire State Building" o "Torre Eiffel".

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

  • 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 che corrispondono a uno qualsiasi dei tipi. Una nota sul trattamento: il parametro location_type non limita la ricerca ai tipi di località specificati. ma funge da filtro post-ricerca: l'API recupera tutti i risultati per il latlng specificato, quindi scarta quelli che non corrispondono ai tipi di località specificati.location_type 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 stradale.
    • "RANGE_INTERPOLATED" restituisce solo gli indirizzi che riflettono un'approssimazione (di solito su una strada) interpolata tra due punti precisi (ad esempio incroci). Un intervallo interpolato in genere indica che i geocodici del tetto 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 a quelli 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 denominare geograficamente una località. Ad esempio, quando viene geocodificato un punto nella città di Chicago, il punto geocodificato può essere indicato come indirizzo stradale, come città (Chicago), come stato (Illinois) o come paese (Stati Uniti). Tutti sono "indirizzi" per il geocodificatore. Il geocodificatore inverso restituisce uno qualsiasi di questi tipi come risultati validi.

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

Di seguito è riportato l'elenco completo dei valori di 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ù esatto è in genere il risultato più in evidenza, come in questo caso. Se vuoi trovare un tipo specifico di indirizzo, consulta la sezione seguente sulla limitazione dei risultati per tipo. Per questo motivo, la posizione dei risultati l'uno rispetto all'altro può variare.

Geocodifica inversa filtrata per tipo

Il seguente esempio 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 geocoding inverso.

Risposte di geocodifica inversa

Il formato della risposta di geocodifica inversa è lo stesso della risposta di geocodifica. Consulta la sezione Risposte di geocodifica. Di seguito sono riportati i codici di stato possibili in una risposta di geocoding inverso.

Codici di stato della geocodifica inversa

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

  • "OK" indica che non si sono verificati errori ed è stato restituito almeno un indirizzo.
  • "ZERO_RESULTS" indica che il geocoding inverso è riuscito, ma non ha restituito risultati. Ciò può verificarsi se al geocodificatore è stato trasmesso un latlng in una località remota.
  • "OVER_QUERY_LIMIT" indica che hai superato la tua quota.
  • "REQUEST_DENIED" indica che la richiesta è stata rifiutata. Probabilmente perché la richiesta include un parametro result_type o location_type, ma non include una chiave API.
  • "INVALID_REQUEST" in genere indica uno dei seguenti problemi:
    • Manca la query (address, components o latlng).
    • È stato fornito un result_type o un location_type non valido.
  • "UNKNOWN_ERROR" indica che la richiesta non è stato possibile elaborarla a causa di un errore del server. La richiesta potrebbe andare a buon fine se riprovi.

Inversione della geocodifica dei plus code

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