Geocodificare un indirizzo

La geocodifica traduce un indirizzo in una posizione su una mappa. Quando codifichi geograficamente un indirizzo, la risposta contiene:

• ID posizione della sede
• Coordinate di latitudine e longitudine della posizione
• Plus Code del luogo
• Dettagli dell'indirizzo espansi

Richiesta di geocodifica

Una richiesta di geocodifica è una richiesta HTTP GET. Puoi specificare l'indirizzo come stringa non strutturata:

https://geocode.googleapis.com/v4beta/geocode/address/ADDRESS_STRING

oppure come un insieme strutturato di componenti dell'indirizzo rappresentati dai parametri di query:

https://geocode.googleapis.com/v4beta/geocode/address?STRUCTURED_ADDRESS

In genere, utilizzi il formato strutturato quando elabori i componenti dell'indirizzo acquisiti in un modulo HTML.

Trasmetti tutti gli altri parametri come parametri URL o, per parametri come la chiave API e la maschera del campo, nelle intestazioni come parte della richiesta GET.

Trasmetti una stringa di indirizzo non strutturata

Un indirizzo non strutturato è un indirizzo formattato come stringa o Plus Code. Ad esempio, il seguente esempio passa la stringa dell'indirizzo codificata nell'URL "1600 Amphitheatre Parkway, Mountain View, CA":

https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY

Tieni presente che il carattere "+" nell'URL viene convertito in uno spazio.

Puoi anche effettuare la richiesta utilizzando un comando curl:

curl -H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

Gli indirizzi possono contenere molti tipi di caratteri speciali. Ad esempio, una "/" come in "7/1 King St, Concord West". Codifica URL di "/" come %2F:

https://geocode.googleapis.com/v4beta/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

Un altro esempio comune è il carattere "#", come in "9500 W Bryn Mawr Ave #650, Rosemont". Codifica URL di "#" come %2FE:

https://geocode.googleapis.com/v4beta/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

Nell'esempio successivo, specifichi una stringa di indirizzo non strutturata come Plus Code 849VCWC8+R4. Assicurati di codificare l'URL del carattere "+" come %2B:

https://geocode.googleapis.com/v4beta/geocode/address/849VCWC8%2BR4?key=API_KEY

Trasmetti un indirizzo strutturato

Specifica un indirizzo strutturato utilizzando il parametro di query address, di tipo PostalAddress. L'oggetto PostalAddress ti consente di specificare alcuni o tutti i componenti dell'indirizzo nella richiesta come singoli parametri di query.

Ad esempio, per specificare solo il codice postale dell'indirizzo che utilizzi PostalAddress.postalCode:

https://geocode.googleapis.com/v4beta/geocode/address?address.postalCode=01062&key=API_KEY

Per specificare più componenti dell'indirizzo, ad esempio per i componenti dell'indirizzo acquisiti in un modulo HTML, utilizza più parametri di query:

https://geocode.googleapis.com/v4beta/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View&address.administrativeArea=CA&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 diretta:

• https://www.googleapis.com/auth/maps-platform.geocode — Utilizza con tutti gli endpoint dell'API Geocoding.
• https://www.googleapis.com/auth/maps-platform.geocode.address — Utilizza solo con GeocodeAddress per il geocoding diretto.

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 la sezione Utilizza OAuth.

Risposta di geocodifica

La geocodifica restituisce un oggetto GeocodeAddressResponse che contiene l'array results di oggetti GeocodeResult. Ogni oggetto GeocodeResult rappresenta un singolo luogo.

L'oggetto JSON completo ha il seguente formato:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "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"
        },
        ...
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCWC8+R4",
        "compoundCode": "CWC8+R4 Mountain View, CA, USA"
      }
    }
  ]
}

Parametri obbligatori

• address: la via o il Plus Code che vuoi geocodificare. Specifica gli indirizzi in conformità al formato utilizzato dal servizio postale nazionale del paese interessato. Evita elementi aggiuntivi dell'indirizzo, come nomi di attività e numeri di unità, suite o piano. Gli elementi dell'indirizzo devono essere delimitati da spazi con codifica URL %20. Ad esempio, passa l'indirizzo "24 Sussex Drive Ottawa ON" come:

  24%20Sussex%20Drive%20Ottawa%20ON

  Formatta i Plus Code come mostrato di seguito. I segni più sono codificati come %2B e gli spazi sono codificati come %20:
  • Un codice globale è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri. Ad esempio, codifica "849VCWC8+R9" come 849VCWC8%2BR9.
  • Un codice composto è un codice locale di almeno sei caratteri con una posizione esplicita. Ad esempio, codifica "CWC8+R9 Mountain View, CA, USA" come CWC8%2BR9%20Mountain%20View%20CA%20USA.

Parametri facoltativi

• locationBias

  Specifica un'area di ricerca come Viewport. Questa località funge da bias, il che significa che possono essere restituiti risultati intorno alla località specificata, inclusi risultati vicini ma al di fuori dell'area.

  Specifica la regione come area visibile rettangolare. Un rettangolo è un'area visibile di latitudine e longitudine, rappresentata da due punti basso e alto diagonalmente opposti. Il punto più basso indica l'angolo sud-ovest del rettangolo, mentre il punto più alto rappresenta l'angolo nord-est del rettangolo.

  Un viewport è considerato una regione chiusa, il che significa che include il relativo confine. I limiti di latitudine devono essere compresi tra -90 e 90 gradi inclusi e i limiti di longitudine devono essere compresi tra -180 e 180 gradi inclusi:

  • Se low = high, l'area visibile è costituita da un singolo punto.
  • Se low.longitude > high.longitude, l'intervallo di longitudine è invertito (l'area visibile attraversa la linea di longitudine di 180 gradi).
  • Se low.longitude = -180 gradi e high.longitude = 180 gradi, l'area visibile include tutte le longitudini.
  • Se low.longitude = 180 gradi e high.longitude = -180 gradi, l'intervallo di longitudine è vuoto.
  • Se low.latitude > high.latitude, l'intervallo di latitudine è vuoto.

  Sia il valore di base che il valore finale devono essere compilati e la casella rappresentata non può essere vuota. Un'area visibile vuota genera un errore.

  Ad esempio, questa stringa di query definisce un riquadro che racchiude completamente New York City:

  ?locationBias.rectangle.low.latitude=40.477398&locationBias.rectangle.low.longitude=-74.259087&locationBias.rectangle.high.latitude=40.91618&locationBias.rectangle.high.longitude=-73.70018

• 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 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.

Bias di località

Utilizza il parametro locationBias per indicare al servizio di geocodifica di preferire i risultati all'interno di una determinata area visibile (espressa come riquadro di selezione). Il parametro locationBias definisce le coordinate di latitudine/longitudine degli angoli sud-ovest e nord-est di questo riquadro di delimitazione.

Ad esempio, una richiesta di geocodifica per l'indirizzo "Washington" può restituire risultati per Washington, D.C. e per lo stato di Washington negli Stati Uniti:

https://geocode.googleapis.com/v4beta/geocode/address/Washington?key=API_KEY

La risposta è nel formato:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "location": {
        "latitude": 38.9071923,
        "longitude": -77.0368707
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "bounds": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "formattedAddress": "Washington, DC, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "Washington",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "location": {
        "latitude": 47.7510741,
        "longitude": -120.7401386
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024945,
          "longitude": -116.91607109999998
        }
      },
      "bounds": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024442,
          "longitude": -116.91607109999998
        }
      },
      "formattedAddress": "Washington, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "WA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
      ...
      ],
      "types": [
        "administrative_area_level_1",
        "political"
      ]
    }
  ]
}

Tuttavia, l'aggiunta di un parametro locationBias che definisce un riquadro di delimitazione intorno alla parte nord-est degli Stati Uniti fa sì che questo geocodice restituisca solo la città di Washington, D.C.:

https://geocode.googleapis.com/v4beta/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72&locationBias.rectangle.high.latitude=43.39&locationBias.rectangle.high.longitude=-65.90&key=API_KEY

Differenziazione delle regioni

In una richiesta di geocodifica, puoi indicare al servizio di geocodifica di restituire risultati orientati a una determinata regione utilizzando il parametro regionCode. Questo parametro accetta un valore di codice CLDR di due caratteri che specifica la distorsione regionale. La maggior parte dei codici CLDR sono identici ai codici ISO 3166-1.

Non esiste un valore predefinito per regionCode. Ad esempio, un geocodice per "Toledo" restituisce risultati per gli Stati Uniti e per la Spagna:

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?key=API_KEY

Risposta:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "location": {
        "latitude": 41.652805199999996,
        "longitude": -83.5378674
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "bounds": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "formattedAddress": "Toledo, OH, USA",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM",
      "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM",
      "location": {
        "latitude": 39.8628296,
        "longitude": -4.0273067
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "bounds": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "formattedAddress": "Toledo, España",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "administrative_area_level_4",
            "political"
          ],
          "languageCode": "es"
        },
        ...
      ],
      "types": [
        "administrative_area_level_4",
        "political"
      ]
    },
    ...
  ]
}

Una richiesta di geocodifica per "Toledo" con regionCode=es (Spagna) restituisce solo risultati dalla Spagna:

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?regionCode=es&key=API_KEY