Geocodifica dei luoghi

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 univoco un luogo nel database di Google Places e su Google Maps. Recuperare gli ID luogo quando codifichi geograficamente un indirizzo. Puoi anche recuperare un ID luogo da molte altre API, ad esempio Place Details (New), Text Search (New) e Nearby Search (New).

Richieste di geocodifica dei luoghi

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

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

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

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:

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

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 dei luoghi:

  • https://www.googleapis.com/auth/maps-platform.geocode — Utilizza con tutti gli endpoint dell'API Geocoding.
  • https://www.googleapis.com/auth/maps-platform.geocode.place — Utilizza solo con GeocodePlace per la geocodifica dei luoghi.

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 Utilizzare OAuth.

Risposte alla geocodifica dei luoghi

Il geocoding del luogo restituisce un oggetto GeocodeResult che rappresenta il luogo corrispondente all'ID luogo.

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 cui vuoi ottenere l'indirizzo leggibile. L'ID luogo è un identificatore univoco che può essere utilizzato con altre API di Google. Ad esempio, puoi utilizzare 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, 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 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 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.