Geocodificare un luogo

Sviluppatori dello Spazio economico europeo (SEE)

La geocodifica dei luoghi ti consente di recuperare un indirizzo da un ID luogo.

Gli ID luogo identificano in modo unico un luogo nel database di Google Places e su Google Maps. Recupera gli ID luogo quando esegui la geocodifica di un indirizzo. Puoi anche recuperare un ID luogo da molte altre API, come Place Details (New), Ricerca testuale (New) e Nearby Search (New).

Richieste di geocodifica dei luoghi

Una richiesta di geocodifica di un luogo è una richiesta HTTP GET nel seguente formato:

https://geocode.googleapis.com/v4/geocode/places/PLACE_ID

Dove PLACE_ID contiene l'ID luogo della località di interesse.

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:

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

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 da utilizzare con la geocodifica dei luoghi:

  • 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.place - Da utilizzare solo con GeocodePlace per la geocodifica dei luoghi.

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.

Risposte di geocodifica dei luoghi

La geocodifica dei luoghi restituisce un oggetto GeocodeResult che rappresenta il luogo corrispondente all'ID 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.

L'oggetto JSON completo ha il seguente formato:

{
  "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "location": {
    "latitude": 37.4220541,
    "longitude": -122.08532419999999
  },
  "granularity": "ROOFTOP",
  "viewport": {
    "low": {
      "latitude": 37.4209489697085,
      "longitude": -122.08846930000001
    },
    "high": {
      "latitude": 37.4236469302915,
      "longitude": -122.0829156
    }
  },
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  "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"
  ]
}

Parametri obbligatori

  • place: l'ID luogo del luogo per il quale vuoi ottenere l'indirizzo leggibile. L'ID luogo è un identificatore univoco che può essere utilizzato con altre API di Google. Ad esempio, puoi utilizzare il placeID restituito dall'API Roads per ottenere l'indirizzo di un punto agganciato. Per saperne di più sugli ID luogo, consulta ID luogo.

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.

  • 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 il campo formattedAddress della risposta.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: formattedAddress' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    La risposta è: 
    {
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA"
}

    Per maggiori dettagli, consulta Scegli i campi da restituire.