Geocodifica invertita una località

Sviluppatori dello Spazio economico europeo (SEE)

La geocodifica inversa traduce una posizione sulla mappa in un indirizzo leggibile. Rappresenti la posizione sulla mappa con le coordinate di latitudine e longitudine della posizione.

Quando esegui la geocodifica inversa di una località, la risposta contiene:

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 è generalmente il primo risultato. Se vuoi trovare corrispondenze per un tipo specifico di indirizzo, utilizza il parametro types.

Richiesta di geocodifica inversa

Una richiesta di geocodifica inversa è una richiesta HTTP GET. Puoi specificare la località come stringa non strutturata:

https://geocode.googleapis.com/v4beta/geocode/location/LATITUDE,LONGITUDE

oppure come un insieme strutturato di coordinate di latitudine e longitudine rappresentate dai parametri di query:

https://geocode.googleapis.com/v4beta/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

In genere, utilizzi il formato strutturato quando elabori i componenti di località acquisiti in un modulo HTML.

Trasmetti tutti gli altri parametri come parametri URL o, per parametri come la chiave API o la maschera di campo, nelle intestazioni come parte della richiesta GET. Ad esempio:

Passare una stringa di località non strutturata

Una posizione non strutturata è una posizione formattata come stringa separata da virgole di coordinate di latitudine e longitudine:

https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?key=API_KEY

Oppure in un comando curl:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338"

Trasmettere una posizione strutturata

Specifica la località strutturata utilizzando il parametro di query location, di tipo LatLng. L'oggetto LatLng ti consente di specificare latitudine e longitudine come parametri di query separati:

https://geocode.googleapis.com/v4beta/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

Utilizzare OAuth per effettuare una richiesta

L'API Geocoding v4 supporta OAuth 2.0 per l'autenticazione. Per utilizzare OAuth con l'API Geocoding, al token OAuth deve essere assegnato l'ambito corretto. L'API Geocoding supporta i seguenti ambiti per l'utilizzo con la geocodifica inversa:

  • https://www.googleapis.com/auth/maps-platform.geocode — Utilizza con tutti gli endpoint dell'API Geocoding.
  • https://www.googleapis.com/auth/maps-platform.geocode.location — Utilizza solo con GeocodeLocation per la geocodifica inversa.

Inoltre, puoi utilizzare l'ambito https://www.googleapis.com/auth/cloud-platform generale per tutti gli endpoint dell'API Geocoding. Questo ambito è utile durante lo sviluppo, ma non per la produzione, perché è un ambito generale che consente l'accesso a tutti gli endpoint.

Per ulteriori informazioni ed esempi, consulta la sezione Utilizzare OAuth.

Risposta di geocodifica inversa

La geocodifica inversa restituisce un oggetto GeocodeLocationResponse che contiene:

  • L'array results di oggetti GeocodeResult che rappresenta il luogo.

    Il geocodificatore inverso restituisce più di un risultato nell'array results. I risultati 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 geocoder. Il geocodificatore inverso restituisce uno qualsiasi di questi tipi come risultati validi.

  • Il campo plusCode, di tipo PlusCode, contiene il plus code che approssima meglio la latitudine e la longitudine nella richiesta. Inoltre, ogni elemento dell'array results contiene un plus code. La distanza tra il plus code decodificato e il punto della richiesta è inferiore a 10 metri.

L'oggetto JSON completo ha il seguente formato:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "establishment",
        "point_of_interest"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

Parametri obbligatori

  • località

    Le coordinate di latitudine e longitudine che specificano dove vuoi l'indirizzo più vicino e leggibile.

Parametri facoltativi

  • languageCode

    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 languageCode non viene fornito, l'API utilizza en come valore predefinito. Se specifichi un codice lingua non valido, l'API restituisce un errore INVALID_ARGUMENT.
    • L'API 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, l'API utilizza la corrispondenza più vicina.
    • La lingua preferita ha una piccola influenza sull'insieme di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Il geocoder interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni per i tipi di strade o i sinonimi che potrebbero essere validi in una lingua ma non in un'altra.

  • regionCode

    Il codice regione come valore CLDR di due caratteri. Non esiste un valore predefinito. La maggior parte dei codici CLDR sono identici ai codici ISO 3166-1.

    Quando geocodifichi un indirizzo, geocodifica diretta, questo parametro può influenzare, ma non limitare completamente, i risultati del servizio alla regione specificata. Quando esegui la geocodifica di una località o di un luogo, geocodifica inversa o geocodifica di un luogo, questo parametro può essere utilizzato per formattare l'indirizzo. In tutti i casi, questo parametro può influire sui risultati in base alla legge vigente.

  • granularità

    Una o più granularità della località, specificate come parametri di ricerca separati, come definito da Granularity. Se specifichi più parametri granularity, l'API restituisce tutti gli indirizzi che corrispondono a una delle granularità.

    Il parametro granularity non limita la ricerca alle granularità di località specificate. granularity funge da filtro post-ricerca. L'API recupera tutti i risultati per il location specificato, quindi scarta quelli che non corrispondono ai livelli di granularità della località specificati.

    Se specifichi sia types che granularity, l'API restituisce solo i risultati che corrispondono a entrambi. Ad esempio:

    https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

  • tipi

    Uno o più tipi di indirizzo, specificati come parametri di query separati. Se specifichi più parametri types, l'API restituisce tutti gli indirizzi che corrispondono a uno dei tipi.

    Il parametro types non limita la ricerca ai tipi di indirizzo specificati. types funge da filtro post-ricerca. L'API recupera tutti i risultati per la località specificata, quindi scarta quelli che non corrispondono ai tipi di indirizzo specificati.

    Se specifichi sia types che granularity, l'API restituisce solo i risultati che corrispondono a entrambi. Ad esempio:

    https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

    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).