Panoramica
La geocodifica è il processo di conversione degli indirizzi (ad esempio "1600 Amphitheatre Parkway, Mountain View, CA") in coordinate geografiche (ad esempio latitudine 37.423021 e longitudine -122.083739), che puoi utilizzare per posizionare gli indicatori o la mappa.
La geocodifica inversa è il processo di conversione delle coordinate geografiche in un indirizzo leggibile (consulta Geocodifica inversa (ricerca di indirizzi)).
Puoi anche utilizzare il geocodificatore per trovare l'indirizzo di un determinato ID luogo.
L'API Maps JavaScript fornisce una classe Geocoder per la geocodifica e la geocodifica inversa in modo dinamico dall'input dell'utente. Se invece vuoi geocodificare indirizzi statici e noti, consulta il servizio web di geocodifica. Per confrontare Geocoder con altre API di Google Maps Platform per la ricerca con previsione del testo, la verifica dell'indirizzo postale o la ricerca del fuso orario, consulta Scegli l'API per indirizzi o coordinate corretta.
Inizia
Prima di utilizzare il servizio di geocodifica nell'API Maps JavaScript, assicurati che l'API Geocoding sia abilitata nella console Google Cloud, nello stesso progetto che hai configurato per l'API Maps JavaScript.
Per visualizzare l'elenco delle API abilitate:
- Vai alla console Google Cloud.
- Fai clic sul pulsante Seleziona un progetto, quindi seleziona lo stesso progetto che hai configurato per l'API Maps JavaScript e fai clic su Apri.
- Nell'elenco delle API nella Dashboard, cerca API Geocoding.
- Se vedi l'API nell'elenco, non devi fare altro. Se l'API non è presente nell'elenco, abilitala:
- Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Libreria. In alternativa, seleziona Raccolta dal menu a sinistra.
- Cerca l'API Geocoding, quindi selezionala dall'elenco dei risultati.
- Seleziona ABILITA. Al termine del processo, l'API Geocoding viene visualizzata nell'elenco delle API nella Dashboard.
Se la mappa non viene visualizzata o la console del browser registra un errore di chiave API o di attivazione, consulta Risoluzione dei problemi e Messaggi di errore.
Prezzi e norme
Prezzi
Per informazioni sui prezzi e sulle norme di utilizzo del servizio di geocoding JavaScript, consulta Utilizzo e fatturazione per l'API Geocoding.
Norme
L'utilizzo del servizio di geocodifica deve essere conforme alle norme per l'API Geocoding.
Richieste di geocodifica
L'accesso al servizio di geocodifica è asincrono e richiede una chiamata a un server esterno. Per questo motivo, il metodo geocode restituisce una promessa che viene risolta al completamento della richiesta. Una volta risolta, puoi utilizzare .then() o await per gestire la risposta.
Puoi accedere al servizio di geocodifica dell'API di Google Maps all'interno del tuo codice utilizzando l'oggetto costruttore google.maps.Geocoder. Il metodo Geocoder.geocode() avvia una richiesta al servizio di geocodifica, passandogli un oggetto letterale GeocoderRequest contenente i termini di input e un metodo di callback da eseguire alla ricezione della risposta.
L'oggetto letterale GeocoderRequest contiene i seguenti campi:
{ address: string, location: LatLng, placeId: string, bounds: LatLngBounds, componentRestrictions: GeocoderComponentRestrictions, region: string }
Parametri obbligatori: devi fornire uno, e solo uno, dei seguenti campi:
address: l'indirizzo che vuoi geocodificare.
o
location:LatLng(oLatLngLiteral) per cui vuoi ottenere l'indirizzo più vicino leggibile. Il geocodificatore esegue una geocodifica inversa. Per ulteriori informazioni, consulta Geocodifica inversa.
o
placeId: l'ID luogo del luogo per il quale vuoi ottenere l'indirizzo più vicino leggibile. Scopri di più sul recupero di un indirizzo per un ID luogo.
Parametri facoltativi:
bounds: l'areaLatLngBoundsall'interno della quale dare maggiore priorità ai risultati di geocodifica. Il parametroboundsinfluenzerà solo i risultati del geocodificatore, senza limitarli completamente. Per saperne di più sulla priorità dell'area visibile , consulta la sezione di seguito.componentRestrictions: utilizzato per limitare i risultati a un'area specifica. Per saperne di più sul filtro dei componenti, consulta la sezione di seguito.region: il codice della regione, specificato come sottotag di regione Unicode di due caratteri (non numerici). Nella maggior parte dei casi, questi tag vengono mappati direttamente ai valori di due caratteri dei ccTLD ("domini di primo livello") noti. Il parametroregioninfluenzerà solo i risultati del geocodificatore, non li limiterà completamente. Di seguito sono riportate ulteriori informazioni sulla distorsione del codice regione.extraComputations: l'unico valore consentito per questo parametro èADDRESS_DESCRIPTORS. Per maggiori dettagli, consulta la sezione Descrittori di indirizzi.fulfillOnZeroResults: soddisfa la promessa con uno stato ZERO_RESULT nella risposta. Questo potrebbe essere utile perché, anche con zero risultati di geocodifica, potrebbero essere restituiti altri campi a livello di risposta. Per maggiori dettagli, consulta Adempimento in caso di zero risultati.
Risposte di geocodifica
Il servizio di geocodifica richiede un metodo di callback da eseguire al momento del recupero dei risultati del geocodificatore. Questo callback deve passare due parametri per contenere
results e un codice status, in quest'ordine.
Risultati di geocodifica
L'oggetto GeocoderResult rappresenta un singolo risultato di geocodifica. Una richiesta di geocodifica può restituire più oggetti risultato:
results[]: { types[]: string, formatted_address: string, address_components[]: { short_name: string, long_name: string, postcode_localities[]: string, types[]: string }, partial_match: boolean, place_id: string, postcode_localities[]: string, geometry: { location: LatLng, location_type: GeocoderLocationType viewport: LatLngBounds, bounds: LatLngBounds } }
Questi campi sono spiegati di seguito:
types[]è un array che indica il tipo di indirizzo del risultato restituito. Questo array contiene un insieme di zero o più tag che identificano il tipo di elemento restituito nel risultato. Ad esempio, un geocodice di "Chicago" restituisce "locality", che indica che "Chicago" è una città, e restituisce anche "political", che indica che si tratta di un'entità politica. Scopri di più sui tipi di indirizzi e sui tipi di componenti degli indirizzi di seguito.formatted_addressè una stringa contenente l'indirizzo leggibile di questa località.Spesso questo indirizzo corrisponde all'indirizzo postale. Tieni presente che alcuni paesi, come il Regno Unito, non consentono la distribuzione di indirizzi postali reali a causa di limitazioni delle licenze.
L'indirizzo formattato è composto logicamente da uno o più componenti dell'indirizzo. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è composto dai seguenti componenti: "111" (il numero civico), "8th Avenue" (la strada), "New York" (la città) e "NY" (lo stato degli Stati Uniti).
Non analizzare l'indirizzo formattato in modo programmatico. Devi invece utilizzare i singoli componenti dell'indirizzo, che la risposta dell'API include oltre al campo dell'indirizzo formattato.
address_components[]è un array contenente i singoli componenti applicabili a questo indirizzo.Ogni componente dell'indirizzo contiene in genere i seguenti campi:
types[]è un array che indica il tipo del componente dell'indirizzo. Il componente dell'indirizzo potrebbe avere un array di tipi vuoto se non esistono tipi noti per quel componente dell'indirizzo. L'API potrebbe aggiungere nuovi valori di tipo in base alle esigenze. Per saperne di più, consulta Tipi di indirizzi e tipi di componenti degli indirizzi.long_nameè la descrizione testuale completa o il nome del componente dell'indirizzo restituito dal geocodificatore.short_nameè un nome testuale abbreviato per il componente dell'indirizzo, se disponibile. Ad esempio, un componente dell'indirizzo per lo stato dell'Alaska potrebbe avere unlong_name"Alaska" e unshort_name"AK" utilizzando l'abbreviazione postale di 2 lettere.
Tieni presente quanto segue sull'array
address_components[]:- L'array di componenti dell'indirizzo può contenere più componenti rispetto a
formatted_address. - L'array non include necessariamente tutte le entità politiche che contengono un indirizzo, ad eccezione di quelle incluse in
formatted_address. Per recuperare tutte le entità politiche che contengono un indirizzo specifico, devi utilizzare la geocodifica inversa, passando la latitudine/longitudine dell'indirizzo come parametro alla richiesta. - Non è garantito che il formato della risposta rimanga lo stesso tra le richieste. In particolare, il numero di
address_componentsvaria in base all'indirizzo richiesto e può cambiare nel tempo per lo stesso indirizzo. Un componente può cambiare posizione nell'array. Il tipo di componente può cambiare. Un determinato componente potrebbe non essere presente in una risposta successiva.
Scopri di più sui tipi di indirizzi e sui tipi di componenti degli indirizzi di seguito.
-
partial_matchindica che il geocodificatore non ha restituito una corrispondenza esatta per la richiesta originale, anche se è stato in grado di trovare una corrispondenza per parte dell'indirizzo richiesto. Ti consigliamo di esaminare la richiesta originale per verificare la presenza di errori ortografici e/o di un indirizzo incompleto.Le corrispondenze parziali si verificano più spesso per indirizzi che non esistono all'interno della località che passi nella richiesta. Le corrispondenze parziali possono essere restituite anche quando una richiesta corrisponde a due o più località nella stessa località. Ad esempio, "Hillpar St, Bristol, UK" restituirà una corrispondenza parziale sia per Henry Street sia per Henrietta Street. Tieni presente che se una richiesta include un componente dell'indirizzo con errori ortografici, il servizio di geocodifica potrebbe suggerire un indirizzo alternativo. I suggerimenti attivati in questo modo verranno contrassegnati anche come corrispondenza parziale.
place_idè un identificatore univoco di un luogo, che può essere utilizzato con altre API di Google. Ad esempio, puoi utilizzareplace_idcon la libreria dell'API Google Places per ottenere i dettagli di un'attività locale, come numero di telefono, orario di apertura, recensioni degli utenti e altro ancora. Consulta la panoramica degli ID luogo.postcode_localities[]è un array che indica tutte le località contenute in un codice postale ed è presente solo quando il risultato è un codice postale che contiene più località.geometrycontiene le seguenti informazioni:locationcontiene il valore di latitudine e longitudine geocodificato. Tieni presente che restituiamo questa località come oggettoLatLng, non come stringa formattata.location_typememorizza dati aggiuntivi sulla località specificata. Sono supportati i seguenti valori:ROOFTOPindica che il risultato restituito riflette un geocodice preciso.RANGE_INTERPOLATEDindica che il risultato restituito riflette un'approssimazione (di solito su una strada) interpolata tra due punti precisi (ad esempio incroci). I risultati interpolati vengono generalmente restituiti quando i codici geografici ROOFTOP non sono disponibili per una via.GEOMETRIC_CENTERindica che il risultato restituito è il centro geometrico di un risultato come una polilinea (ad esempio una strada) o un poligono (regione).APPROXIMATEindica che il risultato restituito è approssimativo.
viewportmemorizza l'area visibile consigliata per il risultato restituito.bounds(restituito facoltativamente) memorizza ilLatLngBoundsche può contenere completamente il risultato restituito. Tieni presente che questi limiti potrebbero non corrispondere all'area visibile consigliata. (Ad esempio, San Francisco include le Farallon Islands, che tecnicamente fanno parte della città, ma non devono essere restituite nell'area visibile).
Gli indirizzi vengono restituiti dal geocodificatore utilizzando l'impostazione della lingua preferita del browser o la lingua specificata durante il caricamento dell'API JavaScript utilizzando il parametro language. Per maggiori informazioni, consulta la sezione
Localizzazione.
Tipi di indirizzi e tipi di componenti degli indirizzi
L'array types[] in GeocoderResult nella risposta indica il tipo di indirizzo. Esempi di tipi di indirizzo includono un indirizzo, un paese o un'entità politica. L'array types in GeocoderAddressComponent indica il tipo di ogni parte dell'indirizzo. Alcuni esempi sono il numero civico o il paese.
Gli indirizzi possono avere più tipi. I tipi possono essere considerati "tag".
Ad esempio, molte città sono contrassegnate con i tipi political e locality.
I seguenti tipi sono supportati e restituiti negli array dei tipi di indirizzo e dei tipi di componenti dell'indirizzo:
| Tipo di indirizzo | Descrizione |
|---|---|
street_address |
Un indirizzo preciso. |
route |
Un percorso con nome (ad es. "US 101"). |
intersection |
Un incrocio importante, di solito tra due strade principali. |
political |
Un'entità politica. In genere, questo tipo indica un poligono di un'amministrazione civile. |
country |
L'entità politica nazionale, in genere il tipo di ordine più elevato restituito dal geocodificatore. |
administrative_area_level_1 |
Una divisione amministrativa principale al di sotto del livello paese. Negli Stati Uniti, questi livelli amministrativi sono gli stati. Non tutte le nazioni utilizzano questi livelli amministrativi. Nella maggior parte dei casi, i nomi brevi administrative_area_level_1 corrispondono esattamente alle suddivisioni ISO 3166-2 e ad altri elenchi ampiamente diffusi; tuttavia, questo non è garantito, poiché i nostri risultati di geocodifica si basano su una serie di indicatori e dati sulla posizione. |
administrative_area_level_2 |
Una divisione amministrativa di secondo livello al di sotto del livello paese. Negli Stati Uniti, questi livelli amministrativi sono le contee. Non tutte le nazioni utilizzano questi livelli amministrativi. |
administrative_area_level_3 |
Una divisione amministrativa di terzo livello al di sotto del livello paese. Questo tipo indica una divisione civile minore. Non tutte le nazioni utilizzano questi livelli amministrativi. |
administrative_area_level_4 |
Una divisione amministrativa di quarto livello al di sotto del livello paese. Questo tipo indica una divisione civile minore. Non tutte le nazioni utilizzano questi livelli amministrativi. |
administrative_area_level_5 |
Una divisione amministrativa di quinto livello al di sotto del livello paese. Questo tipo indica una divisione civile minore. Non tutte le nazioni utilizzano questi livelli amministrativi. |
administrative_area_level_6 |
Una divisione amministrativa di sesto livello al di sotto del livello paese. Questo tipo indica una divisione civile minore. Non tutte le nazioni utilizzano questi livelli amministrativi. |
administrative_area_level_7 |
Una divisione amministrativa di settimo livello al di sotto del livello paese. Questo tipo indica una divisione civile minore. Non tutte le nazioni utilizzano questi livelli amministrativi. |
colloquial_area |
Un nome alternativo comunemente utilizzato per l'entità. |
locality |
Un'entità politica di una città o di un comune incorporato. |
sublocality |
Una divisione amministrativa principale al di sotto di una località. Per alcune località, potresti ricevere uno dei tipi aggiuntivi: da sublocality_level_1 a sublocality_level_5. Ogni livello di località secondaria è un'entità civile. I numeri più grandi indicano un'area geografica più piccola. |
neighborhood |
Un quartiere con un nome. |
premise |
Una località con un nome, in genere un edificio o un insieme di edifici con un nome comune. |
subpremise |
Un'entità indirizzabile al di sotto del livello dell'edificio, ad esempio un appartamento, un'unità o una suite. |
plus_code |
Un riferimento di località codificato, derivato da latitudine e longitudine. I Plus Code possono essere utilizzati in sostituzione degli indirizzi nei luoghi in cui non esistono (dove gli edifici non sono numerati o le strade non hanno un nome). Per maggiori dettagli, visita la pagina https://plus.codes. |
postal_code |
Un codice postale utilizzato per la spedizione della posta tradizionale nel paese. |
natural_feature |
Un elemento naturale di rilievo. |
airport |
Un aeroporto. |
park |
Un parco con un nome. |
point_of_interest |
Un punto d'interesse con un nome. In genere, questi "PDI" sono entità locali importanti che non rientrano facilmente in un'altra categoria, come "Empire State Building" o "Torre Eiffel". |
Un elenco vuoto di tipi indica che non esistono tipi noti per il componente dell'indirizzo specifico (ad esempio, Lieu-dit in Francia).
Oltre a quanto sopra, i componenti dell'indirizzo possono includere i tipi riportati di seguito.
Nota: questo elenco non è esaustivo ed è soggetto a modifiche.
Oltre a quanto sopra, i componenti dell'indirizzo possono includere i tipi elencati di seguito.
| Tipo di componente dell'indirizzo | Descrizione |
|---|---|
floor |
Il piano di un indirizzo di un edificio. |
establishment |
In genere un luogo che non è stato ancora classificato. |
landmark |
Un luogo nelle vicinanze utilizzato come riferimento per facilitare la navigazione. |
point_of_interest |
Un punto d'interesse con un nome. |
parking |
Un parcheggio o una struttura per parcheggiare l'auto. |
post_box |
Una casella postale specifica. |
postal_town |
Un raggruppamento di aree geografiche, come locality e sublocality, utilizzato per gli indirizzi postali in alcuni paesi. |
room |
La stanza di un indirizzo di un edificio. |
street_number |
Il numero civico preciso. |
bus_station, train_station e transit_station |
La posizione di una fermata di autobus, treno o trasporto pubblico. |
Codici di stato
Il codice status potrebbe restituire uno dei seguenti valori:
"OK"indica che non si sono verificati errori; l'indirizzo è stato analizzato correttamente ed è stato restituito almeno un codice geografico."ZERO_RESULTS"indica che la geocodifica è andata a buon fine, ma non ha restituito risultati. Questo può accadere se al geocodificatore è stato passato unaddressinesistente."OVER_QUERY_LIMIT"indica che hai superato la quota."REQUEST_DENIED"indica che la tua richiesta è stata rifiutata. La pagina web non è autorizzata a utilizzare il geocodificatore."INVALID_REQUEST"indica in genere che la query (address,componentsolatlng) è mancante."UNKNOWN_ERROR"indica che non è stato possibile elaborare la richiesta a causa di un errore del server. La richiesta potrebbe andare a buon fine se riprovi."ERROR"indica che la richiesta è scaduta o che si è verificato un problema durante la comunicazione con i server di Google. La richiesta potrebbe andare a buon fine se riprovi.
Esempio di geocodifica
L'esempio seguente mostra la geocodifica di un indirizzo e il posizionamento di un indicatore in corrispondenza dei valori di latitudine e longitudine restituiti. Il risultato della geocodifica viene gestito utilizzando una promise. Fai clic in un punto qualsiasi della mappa per geocodificare l'indirizzo in quella posizione.
TypeScript
async function geocode(request: google.maps.GeocoderRequest) { clear(); const { LatLng } = await google.maps.importLibrary('core'); try { const response = await geocoder.geocode(request); const { results } = response; innerMap.setCenter(results[0].geometry.location); marker.position = new LatLng(results[0].geometry.location); mapElement.append(marker); responseDiv.style.display = 'block'; responsePre.innerText = JSON.stringify(response, null, 2); return results; } catch (e) { alert( 'Geocode was not successful for the following reason: ' + String(e) ); } }
JavaScript
async function geocode(request) { clear(); const { LatLng } = await google.maps.importLibrary('core'); try { const response = await geocoder.geocode(request); const { results } = response; innerMap.setCenter(results[0].geometry.location); marker.position = new LatLng(results[0].geometry.location); mapElement.append(marker); responseDiv.style.display = 'block'; responsePre.innerText = JSON.stringify(response, null, 2); return results; } catch (e) { alert( 'Geocode was not successful for the following reason: ' + String(e) ); } }
Visualizza l'esempio completo.
Viewport Biasing
Puoi indicare al servizio di geocodifica di preferire i risultati all'interno di una determinata area visibile (espressa come riquadro di delimitazione). Per farlo, imposta il parametro bounds all'interno dell'oggetto letterale GeocoderRequest per definire i limiti di questa area visibile. Tieni presente che l'applicazione di bias preferisce solo i risultati entro i limiti; se esistono risultati più pertinenti al di fuori di questi limiti, potrebbero essere inclusi.
Ad esempio, un geocodice per "Winnetka" generalmente restituisce questo sobborgo di Chicago:
{ "types":["locality","political"], "formatted_address":"Winnetka, IL, USA", "address_components":[{ "long_name":"Winnetka", "short_name":"Winnetka", "types":["locality","political"] },{ "long_name":"Illinois", "short_name":"IL", "types":["administrative_area_level_1","political"] },{ "long_name":"United States", "short_name":"US", "types":["country","political"] }], "geometry":{ "location":[ -87.7417070, 42.1083080], "location_type":"APPROXIMATE" }, "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q" }
Tuttavia, se specifichi un parametro bounds che definisce un riquadro di delimitazione per la San Fernando Valley di Los Angeles, questo geocodice restituisce il quartiere denominato "Winnetka" in quella località:
{ "types":["sublocality","political"], "formatted_address":"Winnetka, California, USA", "address_components":[{ "long_name":"Winnetka", "short_name":"Winnetka", "types":["sublocality","political"] },{ "long_name":"Los Angeles", "short_name":"Los Angeles", "types":["administrative_area_level_3","political"] },{ "long_name":"Los Angeles", "short_name":"Los Angeles", "types":["administrative_area_level_2","political"] },{ "long_name":"California", "short_name":"CA", "types":["administrative_area_level_1","political"] },{ "long_name":"United States", "short_name":"US", "types":["country","political"] }], "geometry":{ "location": [34.213171,-118.571022], "location_type":"APPROXIMATE" }, "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ" }
Bias del codice regione
Puoi impostare il servizio di geocodifica in modo che restituisca risultati con differenziazione dei risultati verso una determinata regione utilizzando esplicitamente il parametro region. Questo parametro accetta un codice regione, specificato come sottotag di regione Unicode di due caratteri (non numerici). Questi tag sono mappati direttamente ai valori ccTLD ("dominio di primo livello") familiari di due caratteri, ad esempio "uk" in "co.uk". In alcuni casi, il tag region supporta anche i codici ISO-3166-1, che a volte differiscono dai valori ccTLD (ad esempio "GB" per "Gran Bretagna").
Quando utilizzi il parametro region:
- Specifica un solo paese o una sola regione. I valori multipli vengono ignorati e potrebbero comportare una richiesta non riuscita.
- Utilizza solo sottotag di regione di due caratteri (formato Unicode CLDR). Tutti gli altri input genereranno errori.
- Sono supportati solo i paesi e le regioni elencati in Dettagli sulla copertura di Google Maps Platform.
Le richieste di geocodifica possono essere inviate per ogni dominio in cui l'applicazione Google Maps principale offre la geocodifica. Tieni presente che l'impostazione di bias preferisce solo i risultati per un dominio specifico; se esistono risultati più pertinenti al di fuori di questo dominio, potrebbero essere inclusi.
Ad esempio, un geocodice per "Toledo" restituisce questo risultato, poiché il dominio predefinito per il servizio di geocodifica è impostato sugli Stati Uniti:
{ "types":["locality","political"], "formatted_address":"Toledo, OH, USA", "address_components":[{ "long_name":"Toledo", "short_name":"Toledo", "types":["locality","political"] },{ "long_name":"Ohio", "short_name":"OH", "types":["administrative_area_level_1","political"] },{ "long_name":"United States", "short_name":"US", "types":["country","political"] }], "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw" }
Un geocodice per "Toledo" con il campo region impostato su
'es' (Spagna) restituirà la città spagnola:
{ "types":["locality","political"], "formatted_address":"Toledo, España", "address_components":[{ "long_name":"Toledo", "short_name":"Toledo", "types":["locality","political"] },{ "long_name":"Toledo", "short_name":"TO", "types":["administrative_area_level_2","political"] },{ "long_name":"Castilla-La Mancha", "short_name":"CM", "types":["administrative_area_level_1","political"] },{ "long_name":"España", "short_name":"ES", "types":["country","political"] }], "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y" }
Filtro dei componenti
Puoi impostare il servizio di geocodifica in modo che restituisca risultati relativi agli indirizzi limitati a un'area specifica utilizzando un filtro dei componenti. Specifica il filtro nel parametro
componentRestrictions. I valori dei filtri supportano gli stessi metodi di correzione ortografica e corrispondenza parziale delle altre richieste di geocodifica.
Il geocodificatore restituisce solo i risultati che corrispondono a tutti i filtri dei componenti. In altre parole, valuta le specifiche del filtro come AND, non come OR.
Un filtro dei componenti è costituito da uno o più dei seguenti elementi:
routecorrisponde al nome lungo o breve di un percorso.localitycorrisponde ai tipi di località e località secondaria.administrativeAreacorrisponde a tutti i livelli di area amministrativa.postalCodecorrisponde a codici postali e prefissi di codici postali.countrycorrisponde a un nome di paese o a un codice paese ISO 3166-1 di due lettere. Nota: l'API segue lo standard ISO per la definizione dei paesi e il filtro funziona meglio quando si utilizza il codice ISO corrispondente del paese.
L'esempio seguente mostra l'utilizzo del parametro
componentRestrictions per filtrare in base a country e postalCode:
async function codeAddress(request: google.maps.GeocoderRequest) { clear(); geocoder.geocode({ componentRestrictions: { country: 'AU', postalCode: '2000' } }) .then((result) => { const { results } = result; innerMap.setCenter(results[0].geometry.location); let marker = new google.maps.marker.AdvancedMarkerElement({ map: innerMap, position: results[0].geometry.location }); }) .catch((e) => { alert('Geocode was not successful for the following reason: ' + e); }); };
Evasione in caso di zero risultati
Per la geocodifica inversa, per impostazione predefinita la promessa viene interrotta su status=ZERO_RESULTS. Tuttavia, in questo caso i campi aggiuntivi a livello di risposta di plus_code e address_descriptor potrebbero comunque essere compilati. Se per il parametro fulfillOnZeroResults viene fornito il valore true,
viene compilato in questo caso. Se per il parametro fulfillOnZeroResults viene fornito il valore true, la promise non viene interrotta e questi campi aggiuntivi sono accessibili dalla promise, se presenti.
Di seguito è riportato un esempio di questo comportamento per una latitudine/longitudine in Antartide.
Anche se non sono presenti risultati di geocodifica inversa, possiamo comunque stampare il Plus Code nella promise se impostiamo fulfillOnZeroResults=true.
function addressDescriptorReverseGeocoding() { var latlng = new google.maps.LatLng(-75.290330, 38.653861); geocoder .geocode({ 'location': latlng, 'fulfillOnZeroResults': true, }) .then((response) => { console.log(response.plus_code); }) .catch((error) => { window.alert(`Error: ${error}`); }); }
Descrittori dell'indirizzo
I descrittori dell'indirizzo includono informazioni aggiuntive che aiutano a descrivere una località utilizzando punti di riferimento e aree. Dai un'occhiata alla demo dei descrittori di indirizzi per esplorare la funzionalità.
I descrittori dell'indirizzo possono essere attivati utilizzando il parametro extraComputations. Includi extra_computations=ADDRESS_DESCRIPTORS in una richiesta di geocodifica
, una richiesta di geocodifica inversa
o una richiesta di geocodifica di Places
per ricevere i descrittori degli indirizzi nella risposta.
Esempio di geocodifica di luoghi
La seguente query contiene l'indirizzo di un luogo a Delhi.
function addressDescriptorPlaceIdLookup() { geocoder.geocode({ geocoder.geocode({ 'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q', 'extraComputations': ['ADDRESS_DESCRIPTORS'] }, function(results, status) { if (status == 'OK') { console.log(results[0].address_descriptor); } else { window.alert('Geocode was not successful for the following reason: ' + status); } }); }
Esempio di geocodifica inversa
La seguente query contiene il valore di latitudine/longitudine di una località di Delhi.
function addressDescriptorReverseGeocoding() { var latlng = new google.maps.LatLng(28.640964,77.235875); geocoder .geocode({ 'location': latlng, 'extraComputations': ["ADDRESS_DESCRIPTORS"], }) .then((response) => { console.log(response.address_descriptor); }) .catch((error) => { window.alert(`Error`); }); }
Esempio di descrittore dell'indirizzo
Di seguito è riportato un esempio di address_descriptor.
{ "address_descriptor" : { "areas" : [ { "containment" : "OUTSKIRTS", "display_name" : { "language_code" : "en", "text" : "Turkman Gate" }, "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs" }, { "containment" : "OUTSKIRTS", "display_name" : { "language_code" : "en", "text" : "Chandni Chowk" }, "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI" }, { "containment" : "NEAR", "display_name" : { "language_code" : "en", "text" : "Katar Ganj" }, "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY" } ], "landmarks" : [ { "display_name" : { "language_code" : "en", "text" : "Delite Cinema" }, "straight_line_distance_meters" : 29.9306755065918, "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM", "travel_distance_meters" : 418.7794799804688, "spatial_relationship" : "ACROSS_THE_ROAD", "types" : [ "establishment", "movie_theater", "point_of_interest" ] }, { "display_name" : { "language_code" : "en", "text" : "YES Bank" }, "straight_line_distance_meters" : 66.83731079101562, "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ", "travel_distance_meters" : 489.0340270996094, "spatial_relationship" : "DOWN_THE_ROAD", "types" : [ "bank", "establishment", "finance", "point_of_interest" ] }, { "display_name" : { "language_code" : "en", "text" : "UCO Bank" }, "straight_line_distance_meters" : 25.38849639892578, "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM", "travel_distance_meters" : 403.2246398925781, "spatial_relationship" : "ACROSS_THE_ROAD", "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ] }, { "display_name" : { "language_code" : "en", "text" : "Delhi By Cycle Meeting Point" }, "straight_line_distance_meters" : 44.02867126464844, "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM", "travel_distance_meters" : 97.41281890869141, "spatial_relationship" : "AROUND_THE_CORNER", "types" : [ "establishment", "point_of_interest", "tourist_attraction", "travel_agency" ] }, { "display_name" : { "language_code" : "en", "text" : "Axis Bank Branch" }, "straight_line_distance_meters" : 102.3495178222656, "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4", "travel_distance_meters" : 330.8566284179688, "spatial_relationship" : "DOWN_THE_ROAD", "types" : [ "bank", "establishment", "finance", "point_of_interest" ] } ] } }
In ogni oggetto address_descriptor sono presenti due array: landmarks e areas. L'array landmarks contiene fino a 5 risultati classificati in ordine di pertinenza, tenendo conto della vicinanza alla coordinata richiesta, della prevalenza del punto di riferimento e della sua visibilità. Ogni risultato relativo ai punti di riferimento contiene i seguenti valori:
place_idè l'ID luogo del risultato dei punti di riferimento. Consulta la panoramica degli ID luogo.display_nameè il nome visualizzato del punto di riferimento e contienelanguage_codeetext.straight_line_distance_metersè la distanza punto a punto in metri tra la coordinata di input e il risultato dei punti di riferimento.travel_distance_metersè la distanza in metri percorsa utilizzando la rete stradale (ignorando le limitazioni stradali) tra la coordinata di input e il risultato dei punti di riferimento.spatial_relationshipè la relazione stimata tra la coordinata di input e il risultato dei punti di riferimento:"NEAR"è la relazione predefinita quando non si applica nessuna delle seguenti condizioni."WITHIN"quando la coordinata di input è contenuta entro i limiti della struttura associata al punto di riferimento."BESIDE"quando la coordinata di input è direttamente adiacente al punto di riferimento o al punto di accesso del punto di riferimento."ACROSS_THE_ROAD"quando la coordinata di input si trova esattamente di fronte al punto di riferimento sull'altro lato del percorso."DOWN_THE_ROAD"quando la coordinata di input si trova lungo lo stesso percorso del punto di riferimento, ma non"BESIDES"o"ACROSS_THE_ROAD"."AROUND_THE_CORNER"quando la coordinata di input si trova lungo un percorso perpendicolare al punto di riferimento (limitato a una singola svolta)."BEHIND"quando la coordinata di input è spazialmente vicina al punto di riferimento, ma lontana dal suo punto di accesso.typessono i tipi di luogo del punto di riferimento.
L'oggetto areas contiene fino a 3 risposte e si limita ai luoghi che rappresentano piccole regioni, come quartieri, località secondarie e grandi complessi. Le aree che contengono la coordinata richiesta vengono elencate per prime e ordinate dalla più piccola alla più grande. Ogni risultato areas contiene i seguenti valori:
place_idè l'ID luogo del risultato delle aree. Consulta la panoramica degli ID luogo.display_nameè il nome visualizzato dell'area e contienelanguage_codeetext.containmentè la relazione di contenimento stimata tra la coordinata di input e il risultato delle aree:"NEAR"è la relazione predefinita quando non si applica nessuna delle seguenti condizioni."WITHIN"quando la coordinata di input è vicina al centro dell'area."OUTSKIRTS"quando la coordinata di input è vicina al bordo dell'area.
Copertura dei descrittori dell'indirizzo
I descrittori dell'indirizzo sono in GA per l'India. L'utilizzo dei descrittori di indirizzi in India non comporta costi aggiuntivi ed è coperto dallo SKU Geocoding (India) Essentials esistente.
Feedback
Questa funzionalità è disponibile in tutte le regioni. È in GA per l'India e nella fase di lancio sperimentale pre-GA per tutte le altre regioni. Apprezziamo il tuo feedback:
- Per problemi relativi solo alla regione India, contatta il team di assistenza.
- Per inviare un feedback sulla release sperimentale, inviaci un'email all'indirizzo address-descriptors-feedback@google.com.
- Per saperne di più, consulta i dettagli sulla copertura dei descrittori di indirizzi.
Geocodifica inversa (ricerca di indirizzi)
Il termine geocodifica si riferisce generalmente alla traduzione di un indirizzo leggibile dall'uomo in una posizione su una mappa. Il processo inverso, ovvero la traduzione di una posizione sulla mappa in un indirizzo leggibile, è noto come geocodifica inversa.
Anziché fornire un address testuale, fornisci una coppia latitudine/longitudine separata da virgole nel parametro location.
L'esempio seguente geocodifica un valore di latitudine/longitudine e centra la mappa in quella posizione, visualizzando una finestra informativa con l'indirizzo formattato. Fai clic in un punto qualsiasi della mappa per geocodificare la località o inserisci le tue coordinate.
TypeScript
let marker: google.maps.marker.AdvancedMarkerElement; async function init() { // Request the needed libraries. const [{ InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] = await Promise.all([ google.maps.importLibrary('maps'), google.maps.importLibrary('geocoding'), google.maps.importLibrary('marker'), ]); // Get the gmp-map element. const mapElement = document.querySelector('gmp-map')!; // Get the inner map. const innerMap = mapElement.innerMap; // Get the latlng input box. const latLngQuery = document.getElementById('latlng') as HTMLInputElement; // Get the submit button. const submitButton = document.getElementById('submit')!; // Set the cursor to crosshair. innerMap.setOptions({ draggableCursor: 'crosshair', zoom: 13, mapTypeControl: false, }); // Create a marker for re-use. marker = new AdvancedMarkerElement({ map: innerMap, }); marker.anchorTop = '40px'; const geocoder = new Geocoder(); const infoWindow = new InfoWindow(); // Add a click event listener to the submit button. submitButton.addEventListener('click', () => { void geocodeLatLng(geocoder, innerMap, infoWindow); }); // Add a click event listener to the map. innerMap.addListener('click', (event: google.maps.MapMouseEvent) => { if (event.latLng) { latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`; void geocodeLatLng(geocoder, innerMap, infoWindow); } }); // Make an initial request upon loading. void geocodeLatLng(geocoder, innerMap, infoWindow); } async function geocodeLatLng( geocoder: google.maps.Geocoder, map: google.maps.Map, infoWindow: google.maps.InfoWindow ) { const input = (document.getElementById('latlng') as HTMLInputElement).value; const latlngStr = input.split(',', 2); const latlng = { lat: parseFloat(latlngStr[0]), lng: parseFloat(latlngStr[1]), }; try { const { results } = await geocoder.geocode({ location: latlng }); if (results[0]) { marker.position = latlng; map.setCenter(latlng); infoWindow.setContent(results[0].formatted_address); infoWindow.open(map, marker); } else { window.alert('No results found'); } } catch (e) { window.alert('Geocoder failed due to: ' + String(e)); } } void init();
JavaScript
let marker; async function init() { // Request the needed libraries. const [{ InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] = await Promise.all([ google.maps.importLibrary('maps'), google.maps.importLibrary('geocoding'), google.maps.importLibrary('marker'), ]); // Get the gmp-map element. const mapElement = document.querySelector('gmp-map'); // Get the inner map. const innerMap = mapElement.innerMap; // Get the latlng input box. const latLngQuery = document.getElementById('latlng'); // Get the submit button. const submitButton = document.getElementById('submit'); // Set the cursor to crosshair. innerMap.setOptions({ draggableCursor: 'crosshair', zoom: 13, mapTypeControl: false, }); // Create a marker for re-use. marker = new AdvancedMarkerElement({ map: innerMap, }); marker.anchorTop = '40px'; const geocoder = new Geocoder(); const infoWindow = new InfoWindow(); // Add a click event listener to the submit button. submitButton.addEventListener('click', () => { void geocodeLatLng(geocoder, innerMap, infoWindow); }); // Add a click event listener to the map. innerMap.addListener('click', (event) => { if (event.latLng) { latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`; void geocodeLatLng(geocoder, innerMap, infoWindow); } }); // Make an initial request upon loading. void geocodeLatLng(geocoder, innerMap, infoWindow); } async function geocodeLatLng(geocoder, map, infoWindow) { const input = document.getElementById('latlng').value; const latlngStr = input.split(',', 2); const latlng = { lat: parseFloat(latlngStr[0]), lng: parseFloat(latlngStr[1]), }; try { const { results } = await geocoder.geocode({ location: latlng }); if (results[0]) { marker.position = latlng; map.setCenter(latlng); infoWindow.setContent(results[0].formatted_address); infoWindow.open(map, marker); } else { window.alert('No results found'); } } catch (e) { window.alert('Geocoder failed due to: ' + String(e)); } } void init();
CSS
/* * Always set the map height explicitly to define the size of the div element * that contains the map. */ gmp-map { height: 100%; } /* * Optional: Makes the sample page fill the window. */ html, body { height: 100%; margin: 0; padding: 0; font-family: Roboto, sans-serif; } #floating-panel { background-color: #fff; border-radius: 5px; box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px; margin: 10px; padding: 10px; font-family: Roboto, sans-serif; font-size: 1rem; } #latlng { width: 100%; font-family: Roboto, sans-serif; font-size: 1rem; margin-bottom: 4px; } #submit { font-size: 1rem; }
HTML
<html>
<head>
<title>Reverse Geocoding</title>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
<script>
// prettier-ignore
(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
key: "GOOGLE_MAPS_API_KEY"
});
</script>
</head>
<body>
<gmp-map center="0.714224, -73.961452" zoom="8" map-id="DEMO_MAP_ID">
<div id="floating-panel" slot="control-block-start-inline-start">
<p>
Click the map to reverse geocode, or add your own
coordinates.
</p>
<input
id="latlng"
type="text"
value="40.714224, -73.961452" /><br />
<input id="submit" type="button" value="Reverse Geocode" />
</div>
</gmp-map>
</body>
</html>Tieni presente che nell'esempio precedente abbiamo mostrato il primo risultato selezionando results[0]. Il geocodificatore inverso spesso restituisce più di un risultato. Gli indirizzi geocodificati non sono solo indirizzi postali, ma qualsiasi modo per denominare geograficamente una località. Ad esempio, quando esegui la geocodifica di un punto nella città di Chicago, il punto geocodificato potrebbe essere etichettato come via, città (Chicago), stato (Illinois) o paese (Stati Uniti). Tutti sono indirizzi per il geocodificatore. Il geocodificatore inverso restituisce tutti questi risultati.
Il geocodificatore inverso trova corrispondenze con entità politiche (paesi, province, città e quartieri), indirizzi e codici postali.
Ecco un esempio dell'elenco di indirizzi che la query precedente potrebbe restituire:
results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA" results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA" results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA" results[3].formatted_address: "Brooklyn, NY, USA" results[4].formatted_address: "New York, NY, USA" results[5].formatted_address: "Brooklyn, NY 11211, USA" results[6].formatted_address: "Kings County, NY, USA" results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA" results[8].formatted_address: "New York Metropolitan Area, USA" results[9].formatted_address: "New York, USA"
Gli indirizzi vengono restituiti in ordine di corrispondenza, dalla migliore alla peggiore. In genere, l'indirizzo più esatto è il risultato più in evidenza, come in questo caso.
Tieni presente che restituiamo diversi tipi di indirizzi, dall'indirizzo più specifico a entità politiche meno specifiche come quartieri, città, contee, stati e così via. Se vuoi trovare un indirizzo più generico, ti consigliamo di esaminare il campo results[].types.
Nota: la geocodifica inversa non è una scienza esatta. Il geocodificatore tenterà di trovare la località indirizzabile più vicina entro una determinata tolleranza.
Recupero di un indirizzo per un ID luogo
Fornisci un placeId per trovare l'indirizzo di un ID luogo specifico. L'ID luogo è un identificatore univoco che può essere utilizzato con altre API di Google. Ad esempio, puoi fornire il placeId restituito dall'API Roads per ottenere l'indirizzo di un punto agganciato. Per saperne di più sugli ID luogo, consulta la panoramica degli ID luogo.
Quando fornisci un placeId, la richiesta non può contenere nessuno dei seguenti campi:
addresslatLnglocationcomponentRestrictions
L'esempio seguente accetta un ID luogo, trova l'indirizzo corrispondente e centra la mappa in quella posizione. Inoltre, viene visualizzata una finestra informativa che mostra l'indirizzo formattato del luogo pertinente:
TypeScript
// Initialize the map. async function init(): Promise<void> { const [{ Geocoder }, { InfoWindow }] = await Promise.all([ google.maps.importLibrary('geocoding'), google.maps.importLibrary('maps'), google.maps.importLibrary('marker'), ]); const mapElement = document.querySelector('gmp-map')!; const innerMap = mapElement.innerMap; const geocoder = new Geocoder(); const infoWindow = new InfoWindow(); document.getElementById('submit')!.addEventListener('click', () => { void geocodePlaceId(geocoder, innerMap, infoWindow); }); } // This function is called when the user clicks the UI button. async function geocodePlaceId( geocoder: google.maps.Geocoder, map: google.maps.Map, infoWindow: google.maps.InfoWindow ) { const placeId = (document.getElementById('place-id') as HTMLInputElement) .value; const { AdvancedMarkerElement } = await google.maps.importLibrary('marker'); const { results } = await geocoder.geocode({ placeId }); if (results[0]) { map.setZoom(11); map.setCenter(results[0].geometry.location); const marker = new AdvancedMarkerElement({ map, position: results[0].geometry.location, }); infoWindow.setContent(results[0].formatted_address); infoWindow.open(map, marker); } else { window.alert('No results found'); } } void init();
JavaScript
// Initialize the map. async function init() { const [{ Geocoder }, { InfoWindow }] = await Promise.all([ google.maps.importLibrary('geocoding'), google.maps.importLibrary('maps'), google.maps.importLibrary('marker'), ]); const mapElement = document.querySelector('gmp-map'); const innerMap = mapElement.innerMap; const geocoder = new Geocoder(); const infoWindow = new InfoWindow(); document.getElementById('submit').addEventListener('click', () => { void geocodePlaceId(geocoder, innerMap, infoWindow); }); } // This function is called when the user clicks the UI button. async function geocodePlaceId(geocoder, map, infoWindow) { const placeId = document.getElementById('place-id').value; const { AdvancedMarkerElement } = await google.maps.importLibrary('marker'); const { results } = await geocoder.geocode({ placeId }); if (results[0]) { map.setZoom(11); map.setCenter(results[0].geometry.location); const marker = new AdvancedMarkerElement({ map, position: results[0].geometry.location, }); infoWindow.setContent(results[0].formatted_address); infoWindow.open(map, marker); } else { window.alert('No results found'); } } void init();
Scegli l'API di indirizzi o coordinate corretta
Espandi la sezione seguente per confrontare google.maps.Geocoder con altre API di Google Maps Platform per attività comuni relative a indirizzi e coordinate:
Confronta Geocoder con altre API di Google Maps Platform
| Obiettivo dello sviluppatore | API Recommender o metodo consigliato | Quando utilizzarle |
|---|---|---|
Converti un indirizzo completo in coordinate LatLng (geocodifica diretta)
|
geocoder.geocode({ address })
(google.maps.Geocoder)
|
Utilizzala quando hai già una stringa di indirizzo completa e non ambigua e hai bisogno delle coordinate della mappa. |
Converti le coordinate GPS o della mappa selezionata ({ lat, lng }) in un indirizzo leggibile (geocodifica inversa)
|
geocoder.geocode({ location })
(google.maps.Geocoder)
|
Utilizzala per i report sul campo, per i segnaposto di consegna o per visualizzare l'indirizzo più vicino per una coordinata. |
| Ricerca di indirizzi con completamento automatico mentre un utente digita in un campo di immissione |
<gmp-place-autocomplete>
(PlaceAutocompleteElement)
|
Utilizzalo per le caselle di ricerca interattive durante la digitazione dell'utente, anziché chiamare Geocoder a ogni pressione di un tasto.
|
| Verifica un indirizzo di pagamento o di spedizione, standardizza i componenti postali o controlla la recapitabilità di unità e locali secondari |
API Address Validation
(POST https://addressvalidation.googleapis.com/v1:validateAddress)
|
Utilizzala per il pagamento nell'e-commerce, i moduli di spedizione e i workflow che devono confermare se un indirizzo postale o un numero di appartamento/unità è consegnabile (cosa che Geocoder non verifica).
|
Risolvi una coordinata (lat, lng) e un timestamp in un offset UTC (rawOffset, dstOffset) e IANA timeZoneId
|
API Fuso Orario
(GET https://maps.googleapis.com/maps/api/timezone/json)
|
Utilizzala quando hai bisogno dell'ID fuso orario IANA, dell'offset UTC o dell'offset dell'ora legale per una coordinata e un timestamp (che Geocoder non restituisce).
|