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 types parametro.

Richiesta di geocodifica inversa

Una richiesta di geocodifica inversa è una richiesta GET HTTP. Puoi specificare la località 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 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.

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

Trasmetti una stringa di località non strutturata

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

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 località strutturata

Specifica la località 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 : 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 GeocodeLocationResponse oggetto che contiene:

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

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

    1. GeocodeResult.types: questo array indica il tipo o i tipi generali del risultato. I valori possibili sono quelli riportati nella Tabella A e nella Tabella B della pagina Tipi di luoghi (nuovo).
    2. GeocodeResult.addressComponents[].types: ogni componente dell'indirizzo ha un types array che indica il tipo di quella parte specifica dell'indirizzo. Questi valori sono tratti dalla tabella Tipi di indirizzi e tipi di componenti dell'indirizzo nella pagina Tipi di luoghi (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 si esegue la geocodifica di 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). Per il geocodificatore, tutti questi sono "indirizzi" . 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'results array contiene un Plus Code. La distanza tra il Plus Code decodificato e il punto di 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 ti interessa 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, quindi questo elenco potrebbe non essere esaustivo.
    • Se non viene fornito languageCode, l'API utilizza per impostazione predefinita en. 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 i residenti. Per raggiungere questo obiettivo, restituisce gli indirizzi stradali nella lingua locale, traslitterati in uno script 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 del 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 normale, 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 luoghi, questo parametro può essere utilizzato per formattare l'indirizzo. In tutti i casi, questo parametro può influire sui risultati in base alla legge applicabile.

  • granularità

    Una o più granularità di 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à di località specificate. Al contrario, granularity funge da filtro post-ricerca. L'API recupera tutti i risultati per la location specificata, quindi scarta quelli che non corrispondono alle granularità di 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 indirizzi, specificati come parametri di query separati. I valori possibili sono quelli riportati nella tabella Tipi di indirizzi e tipi di componenti dell'indirizzo nella pagina Tipi di luoghi (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 al tipo o ai tipi di indirizzi specificati. Al contrario, types funge da filtro post-ricerca. L'API recupera tutti i risultati per la località specificata, quindi scarta quelli che non corrispondono al tipo o ai tipi di indirizzi 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. Trasmetti la maschera dei campi 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 la sezione Scegliere i campi da restituire.