Geocodifica invertita una località

Sviluppatori dello Spazio economico europeo (SEE)

La geocodifica inversa traduce una posizione sulla mappa in un indirizzo leggibile. La posizione sulla mappa è rappresentata dalle coordinate di latitudine e longitudine della località.

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

Questa API restituisce diversi tipi di indirizzi, dall'indirizzo stradale più specifico alle entità politiche meno specifiche come quartieri, città, contee e stati. L'indirizzo più preciso è in genere il primo risultato. Se vuoi trovare 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/v4/geocode/location/LATITUDE,LONGITUDE

In alternativa, come insieme strutturato di coordinate di latitudine e longitudine rappresentate da 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 della località acquisiti in un modulo HTML.

Passa 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 di coordinate di latitudine e longitudine separate da virgole:

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

In alternativa, 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 località strutturata

Specifica la località strutturata utilizzando il parametro di query location, di tipo LatLng. L'oggetto LatLng 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 - Da utilizzare con tutti i metodi dell'API Geocoding.
  • https://www.googleapis.com/auth/maps-platform.geocode.location - Da utilizzare 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 i tipi complessivi del risultato. I valori possibili sono tratti dai tipi di luoghi utilizzati dall'API Places. Per saperne di più, consulta Tipi di luoghi nelle tabelle A e B.
    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 indirizzi e componenti degli indirizzi utilizzata dall'API Places.

    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 esegui la geocodifica di un punto nella città di Chicago, il punto geocodificato può essere indicato come via, città (Chicago), stato (Illinois) o paese (Stati Uniti). Tutti questi sono "indirizzi" per il geocodificatore. Il geocodificatore inverso restituisce uno di questi tipi come risultato valido.

  • Il campo plusCode, di tipo PlusCode, contiene il Plus Code che meglio approssima 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 dove vuoi l'indirizzo leggibile più vicino.

Parametri facoltativi

  • languageCode

    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 languageCode non viene fornito, l'API utilizza per impostazione predefinita la lingua e lo script locali della località. Se specifichi un codice lingua non valido, l'API restituisce un errore INVALID_ARGUMENT.
    • L'API fa del suo meglio per fornire un indirizzo leggibile sia per l'utente sia per le persone del posto. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in un alfabeto leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo vengono restituiti tutti nella stessa lingua, che viene 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 del codice CLDR di due caratteri. Non esiste un valore predefinito. La maggior parte dei codici CLDR è identica ai codici ISO 3166-1.

    Quando esegui la geocodifica di un indirizzo, ovvero la 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, la geocodifica inversa o la geocodifica dei luoghi, 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 qualsiasi delle granularità.

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

    Se specifichi sia types sia 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 indirizzi e tipi di componenti degli indirizzi nella pagina Tipi di luoghi (nuova). 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. Invece, types funge da filtro post-ricerca. L'API recupera tutti i risultati per la località specificata, quindi ignora i risultati che non corrispondono ai tipi di indirizzo specificati.

    Se specifichi sia types sia 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 dei campi di risposta per specificare i campi da restituire nella risposta. Passa la maschera di campo della risposta al metodo utilizzando il parametro URL $fields o fields oppure l'intestazione HTTP X-Goog-FieldMask. Ad esempio, la richiesta seguente 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 maggiori dettagli, consulta Scegli i campi da restituire.