Annuncio: a breve su Google Maps Platform saranno disponibili nuovi stili della mappa di base. Questo aggiornamento dello stile della mappa include una nuova tavolozza dei colori predefinita, indicatori modernizzati e miglioramenti alle esperienze e all'usabilità delle mappe. Tutti gli stili di mappa verranno aggiornati automaticamente a marzo 2025. Per ulteriori informazioni sulla disponibilità e su come attivare in anteprima questa funzionalità, consulta Nuovo stile di mappa per Google Maps Platform.

Questa pagina è stata tradotta dall'API Cloud Translation.

Servizio di geocodifica

Nota: librerie lato server

Panoramica

La geocodifica è il processo di conversione degli indirizzi (ad es. "1600 Amphitheatre Parkway, Mountain View, CA") in coordinate geografiche (ad es.latitudine 37,423021 e longitudine -122,083739), che puoi utilizzare per inserire indicatori o posizionare la mappa.

La geocodifica inversa è il processo di conversione delle coordinate geografiche in un indirizzo leggibile (vedi Geocodifica inversa (ricerca indirizzo)).

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 dinamicamente dai dati inseriti dall'utente. Se invece vuoi geocodificare indirizzi statici noti, consulta il servizio web di geocodifica.

Per iniziare

Prima di utilizzare il servizio Geocoding nell'API Maps JavaScript, assicurati innanzitutto che l'API Geocoding sia attivata 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, poi seleziona lo stesso progetto 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, attivala:
1. Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Raccolta. In alternativa, nel menu a sinistra, seleziona Raccolta.
2. Cerca API Geocoding e selezionala dall'elenco dei risultati.
3. Seleziona ATTIVA. Al termine del processo, API Geocoding viene visualizzata nell'elenco delle API nella dashboard.

Prezzi e norme

Prezzi

A partire dal 16 luglio 2018 è entrato in vigore un nuovo piano tariffario di pagamento a consumo per Maps, Routes e Places. Per scoprire di più sui nuovi prezzi e limiti di utilizzo per l'utilizzo del servizio di geocodifica JavaScript, consulta Utilizzo e fatturazione per l'API Geocoding.

Norme

L'utilizzo del servizio di geocodifica deve essere conforme alle norme descritte per l'API Geocoding.

Richieste di geocodifica

L'accesso al servizio Geocoding è asincrono, poiché l'API Google Maps deve effettuare una chiamata a un server esterno. Per questo motivo, devi passare un metodo di callback da eseguire al termine della richiesta. Questo metodo di callback elabora i risultati. Tieni presente che il geocodificatore potrebbe restituire più di un risultato.

Accedi al servizio di geocodifica dell'API Google Maps all'interno del codice tramite l'oggetto del costruttore google.maps.Geocoder. Il metodo Geocoder.geocode() avvia una richiesta al servizio di geocodifica, passando un literal oggetto GeocoderRequest contenente i termini di input e un metodo di callback da eseguire al ricevimento della risposta.

Il valore letterale dell'oggetto GeocoderRequest contiene i seguenti campi:

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

Parametri obbligatori:devi fornire uno e un solo dei seguenti campi:

address: l'indirizzo da geocodificare.
o
location: l'LatLng (o LatLngLiteral) per cui vuoi ottenere l'indirizzo più simile e leggibile da una persona. Il geocodificatore esegue una geocodifica inversa. Per ulteriori informazioni, consulta la sezione Geocodifica inversa.
o
placeId: l'ID luogo per il quale vuoi ottenere l'indirizzo più vicino leggibile da una persona. Scopri di più su come recuperare un indirizzo per un ID luogo.

Parametri facoltativi:

bounds: il valore LatLngBounds entro il quale orientare i risultati di geocodifica in modo più evidente. Il parametro bounds influenzerà solo, non limiterà completamente, i risultati del geocodificatore. Di seguito sono riportate maggiori informazioni sul bias dell'area visibile .
componentRestrictions: utilizzato per limitare i risultati a un'area specifica. Di seguito sono riportate ulteriori informazioni sul filtro dei componenti.
region: il codice regione, specificato come subtag regione Unicode di due caratteri (non numerico). Nella maggior parte dei casi, questi tag vengono mappati direttamente ai valori di due caratteri dei ccTLD ("domini di primo livello") familiari. Il parametro region influisce solo sui risultati del geocodificatore, senza limitarli completamente. Di seguito sono riportate ulteriori informazioni sul bias del codice regione.
extraComputations: l'unico valore consentito per questo parametro è ADDRESS_DESCRIPTORS. Per ulteriori dettagli, consulta i descrittori di indirizzo.
fulfillOnZeroResults: verifica la promessa con uno stato ZERO_RESULT nella risposta. Questo può essere auspicabile perché, anche con zero risultati di geocodifica, potrebbero essere restituiti ancora altri campi a livello di risposta. Per ulteriori dettagli, consulta Esecuzione dell'ordine in assenza di risultati.

Risposte alla geocodifica

Il servizio di geocodifica richiede un metodo di callback da eseguire al recupero dei risultati del geocodificatore. Questo callback deve passare due parametri per contenere il codice results e un codice status, in questo ordine.

Nota: la risposta di geocodifica contiene anche i campi plus_code e address_descriptor a livello di risposta, ma non sono accessibili tramite il callback. ma tramite la promessa. Per ulteriori dettagli, consulta Esecuzione dell'ordine in assenza di risultati.

Risultati della 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 descritti 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 "località", che indica che "Chicago" è una città, e restituisce anche "politico", che indica che si tratta di un'entità politica. Di seguito sono riportate ulteriori informazioni sui tipi di indirizzi e sui tipi di componenti dell'indirizzo.
formatted_address è una stringa contenente l'indirizzo in formato leggibile di questa stazione di ricarica.
Spesso questo indirizzo è equivalente all'indirizzo postale. Tieni presente che alcuni paesi, come il Regno Unito, non consentono la distribuzione di indirizzi postali veri a causa di limitazioni relative alle 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 via), "New York" (la città) e "NY" (lo stato USA).

Non analizzare l'indirizzo formattato tramite programmazione. 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 componenti distinti 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. Consulta l'elenco dei tipi supportati.
- long_name è la descrizione completa del testo o il nome del componente dell'indirizzo restituito dal geocodificatore.
- short_name è un nome testuale abbreviato per l'elemento dell'indirizzo, se disponibile. Ad esempio, un componente dell'indirizzo per lo stato dell'Alaska potrebbe avere un long_name di "Alaska" e un short_name di "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, a parte 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 invariato tra le richieste. In particolare, il numero di address_components varia 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 essere mancante in una risposta successiva.
Di seguito sono riportate ulteriori informazioni sui tipi di indirizzi e sui tipi di componenti dell'indirizzo.
partial_match indica 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 gli indirizzi che non esistono nella località specificata nella richiesta. Possono essere riportate anche corrispondenze parziali 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 scritto male, il servizio di geocodifica potrebbe suggerire un indirizzo alternativo. Anche i suggerimenti attivati in questo modo verranno contrassegnati come corrispondenza parziale.
place_idè un identificatore univoco di un luogo che può essere utilizzato con altre API di Google. Ad esempio, puoi utilizzare place_id con la libreria dell'API Google Luoghi per ottenere i dettagli di un'attività locale, come numero di telefono, orari 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 contenente più località.
geometry contiene le seguenti informazioni:
- location contiene il valore geocodificato latitudine,longitudine. Tieni presente che restituiamo questa posizione come oggetto LatLng, non come stringa formattata.
- location_type memorizza dati aggiuntivi sulla località specificata. Al momento sono supportati i seguenti valori:
  - ROOFTOP indica che il risultato restituito riflette un codice geografico preciso.
  - RANGE_INTERPOLATED indica che il risultato restituito riflette un'approssimazione (di solito su una strada) interpolata tra due punti precisi (ad es. incroci). I risultati interpolati vengono generalmente restituiti quando i codici geografici del tetto non sono disponibili per un indirizzo.
  - GEOMETRIC_CENTER indica che il risultato restituito è il centro geometrico di un risultato come un polilinea (ad esempio una strada) o un poligono (regione).
  - APPROXIMATE indica che il risultato restituito è approssimativo.
- viewport memorizza l'area visibile consigliata per il risultato restituito.
- bounds (restituito facoltativamente) memorizza LatLngBounds che può contenere completamente il risultato restituito. Tieni presente che questi limiti potrebbero non corrispondere al viewport consigliato. Ad esempio, San Francisco include le Isole Farallon, che tecnicamente fanno parte della città, ma non devono essere restituite nell'area visibile.

Gli indirizzi verranno restituiti dal geocodificatore utilizzando l'impostazione della lingua preferita del browser o la lingua specificata durante il caricamento del codice JavaScript dell'API utilizzando il parametro language. Per ulteriori informazioni, consulta Localizzazione.

Tipi di indirizzi e tipi di componenti di indirizzo

L'array types[] in GeocoderResult indica il tipo di indirizzo. L'array types[] può essere restituito anche all'interno di un GeocoderAddressComponent per indicare il tipo del componente dell'indirizzo specifico. Gli indirizzi restituiti dal geocodificatore possono avere più tipi; i tipi possono essere considerati tag. Ad esempio, molte città sono contrassegnate con il tipo political e locality.

I seguenti tipi sono supportati e restituiti dal geocodificatore sia nei tipi di indirizzi sia nei tipi di componenti dell'indirizzo:

street_address indica un indirizzo stradale preciso.
route indica un percorso denominato (ad es. "US 101").
intersection indica un incrocio importante, di solito di due strade principali.
political indica un'entità politica. In genere, questo tipo indica un poligono di un'amministrazione civile.
country indica l'entità politica nazionale ed è tipicamente il tipo di ordine più elevato restituito dal geocodificatore.
administrative_area_level_1 indica un'entità civile di primo ordine al di sotto del livello del paese. Negli Stati Uniti, questi livelli amministrativi sono gli stati. Non tutti i paesi presentano questi livelli amministrativi. Nella maggior parte dei casi, i nomi brevi di administrative_area_level_1 corrispondono quasi esattamente alle suddivisioni ISO 3166-2 e ad altri elenchi molto diffusi; tuttavia, non è garantito, in quanto i risultati del nostro geocoding si basano su una serie di indicatori e dati sulla posizione.
administrative_area_level_2 indica un'entità civile di secondo ordine al di sotto del livello del paese. Negli Stati Uniti, questi livelli amministrativi sono le contee. Non tutti i paesi presentano questi livelli amministrativi.
administrative_area_level_3 indica un'entità civile di terzo ordine al di sotto del livello di paese. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
administrative_area_level_4 indica una persona giuridica civile di quarto ordine al di sotto del livello di paese. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
administrative_area_level_5 indica un'entità civile di quinto ordine al di sotto del livello di paese. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
administrative_area_level_6 indica un'entità civile di sesto ordine al di sotto del livello del paese. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
administrative_area_level_7 indica un'entità civile di settimo ordine al di sotto del livello di paese. Questo tipo indica una suddivisione civile minore. Non tutti i paesi presentano questi livelli amministrativi.
colloquial_area indica un nome alternativo di uso comune per l'entità.
locality indica un'entità politica costituita come città o paese.
sublocality indica un'entità civile di primo ordine al di sotto di una località. Per alcune località potrebbe essere visualizzato uno dei tipi aggiuntivi: sublocality_level_1 a sublocality_level_5. Ogni livello di località secondaria è un'entità civile. Numeri più grandi indicano un'area geografica più piccola.
neighborhood indica un quartiere denominato.
premise indica una località con nome, in genere un edificio o un insieme di edifici con un nome comune.
subpremise indica un'entità indirizzabile al di sotto del livello della struttura, ad esempio un appartamento, un'unità o una suite.
plus_code indica un riferimento alla posizione codificato, ricavato dalla latitudine e dalla longitudine. I Plus Code possono essere utilizzati al posto degli indirizzi in 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 indica un codice postale utilizzato per la spedizione della posta tradizionale all'interno del paese.
natural_feature indica una caratteristica naturale prominente.
airport indica un aeroporto.
park indica un parco denominato.
point_of_interest indica un punto di interesse denominato. In genere, questi "PDV" 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 sono presenti tipi noti per il particolare componente dell'indirizzo, ad esempio Lieu-dit in Francia.

Oltre a quanto indicato sopra, i componenti dell'indirizzo possono includere i tipi riportati di seguito.

Nota:questo elenco non è esaustivo ed è soggetto a modifiche.

floor indica il piano di un indirizzo dell'edificio.
establishment indica in genere un luogo che non è stato ancora classificato.
landmark indica un luogo nelle vicinanze utilizzato come riferimento per agevolare la navigazione.
point_of_interest indica un punto di interesse denominato.
parking indica un parcheggio o un'area di parcheggio.
post_box indica una cassetta postale specifica.
postal_town indica un raggruppamento di aree geografiche, ad esempio locality e sublocality, utilizzato per gli indirizzi postali in alcuni paesi.
room indica la stanza di un indirizzo dell'edificio.
street_number indica il numero civico esatto.
bus_station, train_station e transit_station indicano la posizione di una fermata di autobus, treno o trasporto pubblico.

Codici di stato

Il codice status può restituire uno dei seguenti valori:

"OK" indica che non si sono verificati errori; l'indirizzo è stato analizzato correttamente e almeno un codice geografico è stato restituito.
"ZERO_RESULTS" indica che il codice geografico è andato a buon fine, ma non ha restituito risultati. Ciò può verificarsi se al geocodificatore è stato passato un address inesistente.
"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.
In genere, "INVALID_REQUEST" indica che la query (address, components o latlng) non è presente.
"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 provi di nuovo.
"ERROR" indica che il tempo per la richiesta è scaduto o si è verificato un problema di contatto con i server di Google. La richiesta potrebbe andare a buon fine se provi di nuovo.

In questo esempio, geocodifichiamo un indirizzo e inseriamo un indicatore nei valori di latitudine e longitudine restituiti. Tieni presente che il gestore viene passato come litteale di funzione anonima.

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

Visualizza l'esempio.

Bias dell'area visibile

Puoi indicare al servizio di geocodifica di dare la preferenza ai risultati all'interno di un determinato ambito (espresso come una casella delimitante). A tal fine, imposta il parametro bounds all'interno del valore letterale dell'oggetto GeocoderRequest per definire i limiti di questa area visibile. Tieni presente che l'applicazione di un bias preferisce i risultati all'interno dei limiti; se esistono risultati più pertinenti al di fuori di questi limiti, potrebbero essere inclusi.

Ad esempio, un codice geografico per "Winnetka" restituisce generalmente 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 rettangolo delimitante per la San Fernando Valley di Los Angeles, questo codice geografico 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 orientati in modo esplicito a una determinata regione utilizzando il parametro region. Questo parametro accetta un codice regione, specificato come un sottotag regione Unicode di due caratteri (non numerico). Questi tag vengono mappati direttamente ai valori di due caratteri dei ccTLD ("domini di primo livello") familiari, 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 ("GB" per "Gran Bretagna", ad esempio).

Quando utilizzi il parametro region:

Specifica un solo paese o una sola regione. I valori multipli vengono ignorati e potrebbero comportare un errore nella richiesta.
Utilizza solo sottotag di regione di due caratteri (formato Unicode CLDR). Tutti gli altri input causeranno errori.
Sono supportati solo i paesi e le regioni elencati nella sezione Dettagli sulla copertura di Google Maps Platform.

Le richieste di geocodifica possono essere inviate per ogni dominio in cui l'applicazione principale Google Maps offre la geocodifica. Tieni presente che l'applicazione di bias preferisce solo i risultati per un dominio specifico. Se esistono risultati più pertinenti al di fuori di questo dominio, possono 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 codice geografico 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 di altre richieste di geocodifica.

Il geocodificatore restituisce solo i risultati che corrispondono a tutti i filtri del componente. 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:

route corrisponde al nome lungo o breve di un percorso.
locality corrisponde ai tipi di località e sottolocalità.
administrativeArea corrisponde a tutti i livelli di area amministrativa.
postalCode corrisponde ai codici postali e ai prefissi dei codici postali.
country corrisponde a un nome di paese o a un codice paese di due lettere ISO 3166-1. Nota: l'API segue lo standard ISO per la definizione dei paesi e il filtro funziona al meglio se 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:

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

Soddisfa senza risultati

Per la geocodifica inversa, per impostazione predefinita la promessa non è valida su status=ZERO_RESULTS. Tuttavia, i campi di livello di risposta aggiuntivi di plus_code e address_descriptor potrebbero essere ancora compilati in questo caso. Se viene fornito true per il parametro fulfillOnZeroResults, la promessa non è interrotta e questi campi aggiuntivi sono accessibili dalla promessa, se presenti.

Di seguito è riportato un esempio di questo comportamento per latitudine/longitudine in Antartide. Anche se non ci sono risultati di geocodifica inversa, possiamo comunque stampare il codice Plus nella promessa 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`);
        });
    }

Descrittori di indirizzi

I descrittori di 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 degli indirizzi possono essere attivati tramite l'utilizzo del parametro extraComputations. Includi extra_computations=ADDRESS_DESCRIPTORS in una richiesta di geocodifica, una richiesta di geocodifica inversa o una richiesta di geocodifica di luoghi per ricevere descrittori di indirizzo nella risposta.

Esempio di geocodifica dei luoghi

La seguente query contiene l'indirizzo di un luogo a Delhi.

function addressDescriptorPlaceIdLookup() {
  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 per 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 indirizzo

Un esempio di address_descriptor è il seguente.

  {
    "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 di punto di riferimento contiene i seguenti valori:

place_id è l'ID posizione del risultato dei punti di riferimento. Consulta la panoramica sull'ID luogo.
display_name è il nome visualizzato del punto di riferimento e contiene language_code e text.
straight_line_distance_meters è la distanza in metri tra la coordinata di input e il risultato dei punti di riferimento.
travel_distance_meters è la distanza in metri percorsa tramite la rete stradale (ignorando le limitazioni stradali) tra la coordinata inserita 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 nei limiti della struttura associata al punto di riferimento.
"BESIDE" quando la coordinata inserita è direttamente adiacente al punto di riferimento o al punto di accesso del punto di riferimento.
"ACROSS_THE_ROAD" quando la coordinata inserita si trova direttamente di fronte al punto di riferimento sull'altro lato del percorso.
"DOWN_THE_ROAD" quando la coordinata inserita 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 come il punto di riferimento (limitato a un singolo tornante).
"BEHIND" quando la coordinata inserita è spazialmente vicina al punto di riferimento, ma lontana dal suo punto di accesso.

types sono i tipi di luoghi del punto di riferimento.

L'oggetto areas contiene fino a 3 risposte e si limita ai luoghi che rappresentano piccole regioni, come quartieri, sottolocalità e grandi complessi. Le aree che contengono la coordinata richiesta sono 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 sull'ID luogo.
display_name è il nome visualizzato dell'area e contiene language_code e text.
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 inserita è vicina al centro dell'area.
"OUTSKIRTS" quando la coordinata inserita è vicina al bordo dell'area.

Copertura dei descrittori di indirizzo

Questa funzionalità è disponibile solo in determinati paesi.

Questa è una funzionalità in anteprima e ci farebbe piacere ricevere un feedback. Inviaci un'email all'indirizzo address-descriptors-feedback@google.com.

Geocodifica inversa (ricerca indirizzo)

Il termine geocodifica si riferisce in genere alla traduzione di un indirizzo leggibile da una persona in una posizione su una mappa. Il processo inverso, ovvero la traduzione di una località sulla mappa in un indirizzo leggibile, è noto come geocodifica inversa.

Anziché fornire un valore address di tipo testo, fornisci una coppia di latitudine/longitudine separata da virgola nel parametro location.

Nota: se includi il parametro componentRestrictions nella richiesta, il parametro location viene ignorato.

Il seguente esempio esegue il geocodifica di un valore di latitudine/longitudine e centra la mappa sulla località in questione, visualizzando una finestra informativa con l'indirizzo formattato:

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.731, lng: -73.997 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodeLatLng(geocoder, map, infowindow);
    }
  );
}

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]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;index.ts

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.731, lng: -73.997 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

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]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;index.js

Visualizza esempio

Prova Sample

JSFiddle.net Google Cloud Shell

Tieni presente che nell'esempio precedente abbiamo mostrato il primo risultato selezionando results[0]. Il geocodificatore inverso restituisce spesso più di un risultato. Gli indirizzi geocodificati non sono solo indirizzi postali, ma qualsiasi modo per assegnare un nome geografico a una località. Ad esempio, quando esegui la geocodifica di un punto nella città di Chicago, il punto geocodificato può essere etichettato come indirizzo, come città (Chicago), come stato (Illinois) o come paese (Stati Uniti). Si tratta di indirizzi per il geocodificatore. Il geocodificatore inverso restituisce tutti questi risultati.

Il geocodificatore inverso associa 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 nell'ordine delle corrispondenze migliori a quelle peggiori. In genere, l'indirizzo più preciso è il risultato più in evidenza, come in questo caso. Tieni presente che restituiamo diversi tipi di indirizzi, dal più specifico indirizzo stradale a entità politiche meno specifiche come quartieri, città, contee, stati e così via. Se vuoi trovare una corrispondenza con un indirizzo più generale, ti consigliamo di controllare 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 determinato ID luogo. L'ID luogo è un identificatore univoco che può essere utilizzato con altre API Google. Ad esempio, puoi fornire il valore 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 valore placeId, la richiesta non può contenere nessuno dei seguenti campi:

address
latLng
location
componentRestrictions

L'esempio seguente accetta un ID luogo, trova l'indirizzo corrispondente e centra la mappa su quella posizione. Viene visualizzata anche una finestra informativa che mostra l'indirizzo formattato del luogo pertinente: