Richiesta e risposta di geocodifica inversa (ricerca di indirizzi)

Il termine geocodifica si riferisce generalmente alla traduzione di un indirizzo leggibile in una località su una mappa. Il processo di trascrizione della posizione su una 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 cui vuoi l'indirizzo leggibile più vicino.
  • key: la chiave API della tua applicazione. Questa chiave identifica l'applicazione ai fini della gestione della quota. Scopri come ottenere una chiave.

Parametri facoltativi

Ecco 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 il criterio 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 leggibile sia per l'utente che per i locali. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, se necessario, trascritta in uno script leggibile dall'utente, 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 il nome non è disponibile nella lingua preferita, il geocodificatore utilizza la corrispondenza più vicina.
  • region: il codice della regione, specificato come valore di due caratteri ccTLD ("dominio di primo livello"). Il parametro può inoltre influire sui risultati in base alla legge vigente.
  • result_type: filtro di uno o più tipi di indirizzo, 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. Nota sull'elaborazione: il parametro result_type non limita la ricerca ai tipi di indirizzo specificati. Piuttosto, result_type agisce da filtro post-ricerca: l'API recupera tutti i risultati per il valore latlng specificato, quindi scarta i risultati che non corrispondono ai tipi di indirizzo specificati. Sono supportati i seguenti valori:
    • street_address indica un indirizzo esatto.
    • route indica un percorso denominato (ad esempio "US 101").
    • intersection indica un incrocio principale, generalmente di due strade principali.
    • political indica un'entità politica. In genere, questo tipo indica un poligono di una qualche amministrazione civile.
    • country indica l'entità politica nazionale ed è in genere il tipo di ordine più alto restituito dal Geocoder.
    • administrative_area_level_1 indica una persona giuridica del primo ordine al di sotto del livello nazionale. All'interno degli Stati Uniti, questi livelli amministrativi sono stati definiti come stati. Non tutti i paesi presentano questi livelli amministrativi. Nella maggior parte dei casi, i nomi brevi di admin_area_level_1 corrisponderanno molto meglio alle suddivisioni ISO 3166-2 e ad altri elenchi 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 indica una persona giuridica del secondo ordine al di sotto del livello nazionale. Negli Stati Uniti, questi livelli amministrativi sono contee. Non tutti i paesi presentano questi livelli amministrativi.
    • administrative_area_level_3 indica una persona giuridica del terzo ordine al di sotto del livello nazionale. Questo tipo indica una divisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
    • administrative_area_level_4 indica una persona giuridica del quarto ordine al di sotto del livello nazionale. Questo tipo indica una divisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
    • administrative_area_level_5 indica una persona giuridica del quinto ordine al di sotto del livello nazionale. Questo tipo indica una divisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
    • administrative_area_level_6 indica una persona giuridica del sesto ordine al di sotto del livello nazionale. Questo tipo indica una divisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
    • administrative_area_level_7 indica una persona giuridica del settimo ordine al di sotto del livello nazionale. Questo tipo indica una divisione 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 da una città o da un'altra città.
    • sublocality indica una entità civile del primo ordine in una località. Per alcune località potrebbero essere presenti uno dei seguenti tipi aggiuntivi: da sublocality_level_1 a sublocality_level_5. Ogni livello di periferica è un'entità civile. I numeri più grandi indicano un'area geografica più piccola.
    • neighborhood indica un quartiere denominato
    • premise indica una posizione denominata, in genere un edificio o una raccolta di edifici con un nome comune
    • subpremise indica un'entità del primo ordine sotto una località denominata, in genere un edificio singolare all'interno di una raccolta di edifici con un nome comune
    • plus_code indica un riferimento località codificato, derivato dalla latitudine e dalla longitudine. I plus code possono essere utilizzati per sostituire gli indirizzi in luoghi in cui non esistono (gli edifici non sono numerati o le strade non hanno un nome). Per informazioni dettagliate, consulta https://plus.codes.
    • postal_code indica un codice postale utilizzato per indirizzare la posta all'interno del paese.
    • natural_feature indica una caratteristica naturale ben visibile.
    • airport indica un aeroporto.
    • park indica un parco denominato.
    • point_of_interest indica un punto di interesse denominato. In genere, questi "PDI" sono entità locali di spicco che non si adattano facilmente ad altre categorie, come "Empire State Building" o "Torre Eiffel".
  • location_type: 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 dei tipi. Nota sull'elaborazione: il parametro location_type non limita la ricerca ai tipi di località specificati. Piuttosto, location_type agisce da filtro post-ricerca: l'API recupera tutti i risultati per il valore latlng specificato, quindi scarta i risultati che non corrispondono ai tipi di località 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 rappresentano un'approssimazione (generalmente su una strada) interpolati tra due punti precisi (ad esempio un incrocio). Un intervallo interpolato in genere indica che i codici geografici panoramici non sono disponibili per un indirizzo.
    • "GEOMETRIC_CENTER" restituisce solo i centri geometrici di una posizione, come una polilinea (ad esempio una strada) o un poligono (area geografica).
    • "APPROXIMATE" restituisce solo gli indirizzi che sono indicati 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 di filtro è accettabile, l'API restituisce ZERO_RESULTS.

Esempio di geocodifica inversa

La seguente query contiene il valore di latitudine/longitudine di una località a 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 un punto di geocodifica è presente nella città di Chicago, il punto geocodificato potrebbe essere indicato come un indirizzo, come la città (Chicago), come stato (Illinois) o come paese (Stati Uniti). Sono tutti "indirizzi" per il geocodificatore. Il geocodificatore inverso restituisce uno qualsiasi di questi tipi di risultati validi.

Il geocodificatore inverso corrisponde agli enti politici (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 tipi diversi di indirizzi, dall'indirizzo più specifico a entità politiche meno specifiche, come quartieri, città, contee e stati. In genere, l'indirizzo più esatto è il risultato più in evidenza, in questo caso. Se vuoi abbinare un tipo di indirizzo specifico, consulta la sezione seguente su come limitare i risultati in base al tipo. Per questo motivo, la posizione dei risultati può essere diversa.

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 la geocodifica inversa.

Inverti risposte geocodificate

Il formato della risposta di geocodifica inversa è la stessa della risposta di 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 di geocodifica inversa

Il campo "status" all'interno dell'oggetto di risposta Geocoding contiene lo stato della richiesta e potrebbe contenere informazioni di debug per aiutarti a individuare il motivo per cui 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 ha avuto esito positivo, ma non ha restituito risultati. Questo può succedere 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. È possibile che la richiesta includa un parametro result_type o location_type, ma non una chiave API.
  • "INVALID_REQUEST" in genere indica una delle seguenti opzioni:
    • 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 provi di nuovo, la richiesta potrebbe avere esito positivo.

Plus code geocodificati

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