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 con un tipo specifico di indirizzo, utilizza il parametro types.

Richiesta di geocodifica inversa

Una richiesta di geocoding inverso è una richiesta HTTP GET. Puoi specificare la posizione come stringa non strutturata:

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

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

https://geocode.googleapis.com/v4/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:

Trasmetti una stringa di località non strutturata

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

https://geocode.googleapis.com/v4/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/v4/geocode/location/37.4225508,-122.0846338"

Trasmetti una posizione strutturata

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

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

Utilizza 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 i metodi 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 generale https://www.googleapis.com/auth/cloud-platform per tutti i metodi dell'API Geocoding. Questo ambito è utile durante lo sviluppo, ma non in produzione, perché è un ambito generale che consente l'accesso a tutti i metodi.

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

Risposta di geocodifica inversa

La geocodifica inversa restituisce un oggetto GeocodeLocationResponse che contiene:

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

    Le risposte dell'API Geocoding includono array types in due posizioni principali all'interno di GeocodeResult:

    1. GeocodeResult.types: questo array indica il tipo o i tipi complessivi del risultato. I valori possibili sono tratti dalle tabelle A e B nella pagina Tipi di luoghi (nuovo).
    2. GeocodeResult.addressComponents[].types: ogni componente dell'indirizzo ha un array types che indica il tipo di quella parte specifica dell'indirizzo. Questi valori sono tratti dalla tabella Tipi di indirizzo e tipi di componenti di indirizzo nella pagina Tipi di luogo (nuovo).

    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 geocodificatore. Il geocodificatore inverso restituisce uno qualsiasi di questi tipi come risultati validi.

  • Il campo plusCode, di tipo PlusCode, contiene il plus code che approssima al 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.

    Nota: l'API non restituisce sempre i Plus Code.

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 la posizione in cui vuoi trovare 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 geocodificatore 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 di un codice CLDR di due caratteri. Non esiste un valore predefinito. La maggior parte dei codici CLDR sono identici ai codici ISO 3166-1.

    Quando esegui la geocodifica di 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 posizione 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 query 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/v4/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. I valori possibili sono tratti dalla tabella Tipi di indirizzo e tipi di componenti di indirizzo nella pagina Tipi di luogo (nuovo). Se specifichi più parametri types, l'API restituisce tutti gli indirizzi che corrispondono a uno qualsiasi 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/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

  • FieldMask

    Crea una maschera del campo di risposta per specificare i campi da restituire nella risposta. Passa la maschera del campo di risposta al metodo utilizzando il parametro URL $fields o fields oppure utilizzando l'intestazione HTTP X-Goog-FieldMask. Ad esempio, la richiesta riportata di seguito restituirà solo i campi placeID della risposta.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
    La risposta è: 
    {
  "results": [
    {
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
    },
    {
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
    },
    {
      "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
    },
    {
      "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
    },
    ...
  ]
}

    Per ulteriori dettagli, consulta Scegliere i campi da restituire.