La geocodifica traduce un indirizzo in una posizione su una mappa. Quando geocodifichi un indirizzo, la risposta contiene:
- ID posizione della località
- Le coordinate di latitudine e longitudine della località
- Plus Code della località
- I dettagli dell'indirizzo espansi
Richiesta di geocodifica
Una richiesta di geocodifica è una richiesta GET HTTP. Puoi specificare l'indirizzo come stringa non strutturata:
https://geocode.googleapis.com/v4/geocode/address/ADDRESS_STRING
Oppure come un insieme strutturato di componenti dell'indirizzo rappresentati da parametri di query:
https://geocode.googleapis.com/v4/geocode/address?STRUCTURED_ADDRESS
In genere, utilizzi il formato strutturato quando elabori i componenti dell'indirizzo acquisiti in un modulo HTML.
Passa tutti gli altri parametri come parametri URL o, per parametri come la chiave API e la maschera dei campi, 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. La geocodifica degli indirizzi non risolve le coordinate di latitudine e longitudine o altre stringhe non strutturate che non rappresentano un indirizzo o un Plus Code. Le richieste che utilizzano queste stringhe non sono supportate e potrebbero generare risposte di errore o un comportamento non specificato. Di seguito sono riportati alcuni esempi di query non supportate:
| Tipo di query | Esempio |
|---|---|
| Coordinate di latitudine e longitudine. Utilizza invece la geocodifica inversa. | "37.422131,-122.084801" |
| Troppi concetti o vincoli, ad esempio i nomi di più luoghi, strade o città in una singola query | "Market Street San Francisco San Jose Airport" |
| Elementi dell'indirizzo postale non rappresentati su Google Maps |
"C/O John Smith 123 Main Street" "P.O. Box 13 San Francisco" |
| Nomi di attività, catene o categorie combinati con località in cui queste entità non sono disponibili | "Tesco near Dallas, Texas" |
| Query ambigue con più interpretazioni | "Charger drop-off" |
| Nomi storici non più in uso | "Middlesex United Kingdom" |
| Elementi o intenti non geospaziali | "How many boats are in Ventura Harbor?" |
| Nomi non ufficiali o personalizzati |
"The Jenga" "The Helter Skelter" |
Ad esempio, la seguente stringa di query passa la stringa di indirizzo con codifica URL "1600 Amphitheatre Parkway, Mountain View, CA":
https://geocode.googleapis.com/v4/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/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
Gli indirizzi possono contenere molti tipi di caratteri speciali. Ad esempio, un "/" come in "7/1 King St, Concord West". Codifica l'URL "/" come %2F:
https://geocode.googleapis.com/v4/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 l'URL "#" come %2FE:
https://geocode.googleapis.com/v4/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/v4/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, utilizza PostalAddress.postalCode:
https://geocode.googleapis.com/v4/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/v4/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 normale:
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.address: da utilizzare solo conGeocodeAddressper la geocodifica normale.
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
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. Nota: la geocodifica degli indirizzi non risolve le coordinate di latitudine e longitudine o altre stringhe non strutturate che non rappresentano un indirizzo o un Plus Code. Per maggiori dettagli ed esempi di query non supportate, vedi Trasmetti una stringa di indirizzo non strutturata. 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
%2Be gli spazi con URL%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.
- Un codice globale è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri. Ad esempio, codifica "849VCWC8+R9" come
Parametri facoltativi
locationBias
Specifica un'area di ricerca come
Viewport. Questa località funge da distorsione, il che significa che risultati intorno alla località specificata possono essere restituiti, inclusi i 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'area visibile è considerata 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 viene invertito (l'area visibile attraversa la linea di longitudine di 180 gradi). - Se
low.longitude= -180 gradi ehigh.longitude= 180 gradi, l'area visibile include tutte le longitudini. - Se
low.longitude= 180 gradi ehigh.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'area visibile 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 - Se
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
languageCodenon viene fornito, l'API utilizza come valore predefinitoen. Se specifichi un codice lingua non valido, l'API restituisce un erroreINVALID_ARGUMENT. - L'API fa del suo meglio per fornire un indirizzo leggibile sia per l'utente sia per i residenti. Per raggiungere questo obiettivo, restituisce gli indirizzi 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 di 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 normale, questo parametro può influenzare, ma non limitare completamente, i risultati del servizio alla regione specificata. Quando geocodifichi una località o un luogo, geocodifica inversa o geocodifica del luogo, questo parametro può essere utilizzato per formattare l'indirizzo. In tutti i casi, questo parametro può influire sui risultati in base alla legge applicabile.
-
FieldMask
Crea una maschera dei campi di risposta per specificare i campi da restituire nella risposta. Passa la maschera dei campi di risposta al metodo utilizzando il parametro URL
$fieldsofields, oppure utilizzando l'intestazione HTTPX-Goog-FieldMask. Ad esempio, la richiesta riportata di seguito restituirà solo il campoplaceIDdella 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/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
{ "results": [ { "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc" } ] }
Per maggiori dettagli, vedi Scegliere i campi da restituire.
Differenziazione della 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/v4/geocode/address/Washington?key=API_KEY
La risposta ha il seguente 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 questa geocodifica restituisca solo la città di Washington, D.C.:
https://geocode.googleapis.com/v4/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 della regione
In una richiesta di geocodifica, puoi indicare al servizio di geocodifica di restituire risultati con distorsione verso una regione specifica utilizzando il parametro regionCode. Questo parametro accetta un
valore di codice CLDR di due caratteri che specifica la distorsione della regione. La maggior parte dei codici CLDR sono identici ai codici ISO 3166-1.
Non esiste un valore predefinito per regionCode. Ad esempio, una geocodifica per "Toledo" restituisce risultati per gli Stati Uniti e per la Spagna:
https://geocode.googleapis.com/v4/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/v4/geocode/address/Toledo?regionCode=es&key=API_KEY