Richiesta e risposta di geocodifica inversa (ricerca di indirizzi)

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

Inverti richieste di geocodifica

Parametri obbligatori

  • latlng: le coordinate di latitudine e longitudine che specificano la posizione per la quale vuoi l'indirizzo leggibile più vicino.
  • key: chiave API dell'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. 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'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 civico leggibile sia per l'utente sia per la gente del posto. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in uno script leggibile dall'utente se necessario, osservando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo vengono restituiti 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 a due caratteri 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 qualsiasi di questi tipi. Nota sull'elaborazione: il parametro result_type non restrict la ricerca ai tipi di indirizzi specificati. Piuttosto, result_type agisce come filtro post-ricerca: l'API recupera tutti i risultati per l'elemento latlng specificato, quindi ignora quelli che non corrispondono ai tipi di indirizzo specificati. Sono supportati i seguenti valori:
    • street_address indica un indirizzo preciso.
    • route indica un percorso denominato (ad esempio "US 101").
    • intersection indica un incrocio principale, di solito composto da due strade principali.
    • political indica un'entità politica. Di solito, questo tipo indica un poligono di alcune amministrazioni civili.
    • country indica l'entità politica nazionale ed è in genere il tipo di ordine più elevato restituito dal geocodificatore.
    • administrative_area_level_1 indica una persona giuridica civile di primo ordine 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 Administration_area_level_1 corrisponderanno molto alle suddivisioni ISO 3166-2 e ad altri elenchi ampiamente diffusi. Tuttavia, questo non è garantito poiché i nostri risultati di geocodifica si basano su una varietà di indicatori e dati sulla posizione.
    • administrative_area_level_2 indica una persona giuridica civile di secondo ordine al di sotto del livello nazionale. All'interno degli Stati Uniti, questi livelli amministrativi sono contee. Non tutti i paesi presentano questi livelli amministrativi.
    • administrative_area_level_3 indica una persona giuridica civile di terzo ordine al di sotto del livello del paese. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
    • administrative_area_level_4 indica una persona giuridica civile di quarto ordine al di sotto del livello del paese. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
    • administrative_area_level_5 indica una persona giuridica di quinto ordine al di sotto del livello nazionale. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
    • administrative_area_level_6 indica una persona giuridica civile di sesto ordine al di sotto del livello nazionale. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
    • administrative_area_level_7 indica una persona giuridica civile di settimo ordine al di sotto del livello nazionale. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
    • colloquial_area indica un nome alternativo di uso comune per l'entità.
    • locality indica una città o un'entità politica incorporata in una città.
    • sublocality indica una persona giuridica di primo ordine sotto una località. Per alcune località potrebbe essere disponibile uno dei seguenti tipi: da sublocality_level_1 a sublocality_level_5. Ogni livello di circoscrizione è un'entità civile. Numeri più grandi indicano un'area geografica più piccola.
    • neighborhood indica un quartiere denominato
    • premise indica una posizione denominata, di solito un edificio o un insieme di edifici con un nome comune
    • subpremise indica un'entità di primo ordine sotto una località denominata, di solito un singolo edificio all'interno di una raccolta di edifici con un nome comune
    • plus_code indica un riferimento a una località codificato, derivato da latitudine e longitudine. I plus code possono essere utilizzati in sostituzione degli indirizzi stradali in luoghi in cui non sono presenti (in cui gli edifici non sono numerati o le strade non hanno nomi). Per maggiori dettagli, visita la pagina https://plus.codes.
    • postal_code indica un codice postale utilizzato per 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 d'interesse con nome. In genere, questi "PDI" sono entità locali di spicco che non rientrano facilmente in un'altra categoria, come ad esempio "Empire State Building" o "Torre Eiffel".
  • location_type: un filtro di uno o più tipi di località, separate da una barra verticale (|). Se il parametro contiene più tipi di località, l'API restituisce tutti gli indirizzi che corrispondono a uno qualsiasi di questi tipi. Nota sull'elaborazione: il parametro location_type non restrict la ricerca ai tipi di località specificati. Piuttosto, location_type agisce come filtro post-ricerca: l'API recupera tutti i risultati per l'elemento latlng specificato, quindi ignora quelli 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 precise con una precisione all'indirizzo.
    • "RANGE_INTERPOLATED" restituisce solo gli indirizzi che riflettono un'approssimazione (di solito su una strada) interpolata tra due punti precisi (come gli incroci). Un intervallo interpolato in genere indica che i codici geografici del tetto non sono disponibili per un indirizzo civico.
    • "GEOMETRIC_CENTER" restituisce solo i centri geometrici di una località, come una polilinea (ad es. una strada) o un poligono (regione).
    • "APPROXIMATE" restituisce solo gli indirizzi che sono caratterizzati come approssimativi.
  • extra_computations: l'unico valore consentito per questo parametro è ADDRESS_DESCRIPTORS. Vedi i descrittori degli indirizzi per maggiori dettagli.

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 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 di "formatted_address" non sono solo indirizzi postali, ma un modo per assegnare un nome geografico a una località. Ad esempio, durante la geocodifica di un punto della città di Chicago, il punto geocodificato può essere indicato come un indirizzo stradale, come la città (Chicago), come stato (Illinois) o come paese (Stati Uniti). Tutti sono "indirizzi" del geocodificatore. Il geocodificatore inverso restituisce uno 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 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 più specifico a entità politiche meno specifiche come quartieri, città, contee e stati. Il risultato più evidente è generalmente l'indirizzo più esatto, come in questo caso. Se vuoi trovare una corrispondenza con un tipo specifico di indirizzo, consulta la sezione riportata di seguito su come limitare i risultati per tipo. Per questo motivo, la posizione dei risultati rispetto all'altra può variare.

Geocodifica inversa filtrata per tipo

L'esempio seguente filtra gli indirizzi restituiti per includere solo quelli con tipo di località ROOFTOP e 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 le risposte di geocodifica

Il formato della risposta di geocodifica inversa è uguale a quello 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.

Inverti codici di stato di geocodifica

Il campo "status" nell'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 ed è stato restituito almeno un indirizzo.
  • "ZERO_RESULTS" indica che la geocodifica inversa è riuscita, ma non ha restituito risultati. Questo 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. Forse perché la richiesta include un parametro result_type o location_type, ma non include una chiave API.
  • "INVALID_REQUEST" indica in genere una delle seguenti condizioni:
    • 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. Riprova.

Plus Code di geocodifica invertita

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