A breve su Google Maps Platform saranno disponibili nuovi stili di mappa. Questo aggiornamento dello stile della mappa include una nuova tavolozza dei colori predefinita e miglioramenti all'usabilità e alle esperienze delle mappe. Tutti gli stili di mappa verranno aggiornati automaticamente a marzo 2025. Per ulteriori informazioni sulla disponibilità e su come attivare la funzionalità in precedenza, consulta la sezione 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 esempio "1600 Amphitheatre Parkway, Mountain View, CA") in coordinate geografiche (ad esempio 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 (consulta la sezione 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 a partire dall'input dell'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 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 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 eseguire altre operazioni. Se l'API non è elencata, abilitala:
1. Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Libreria. In alternativa, nel menu a sinistra, seleziona Raccolta.
2. Cerca API Geocoding, poi selezionala dall'elenco dei risultati.
3. Seleziona ABILITA. Al termine del processo, l'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 con pagamento a consumo per Maps, Routes e Places. Per ulteriori informazioni sui nuovi prezzi e sui limiti di utilizzo per l'utilizzo del servizio JavaScript Geocoding, consulta Utilizzo e fatturazione per l'API Geocoding.

Norme

L'utilizzo del servizio Geocoding deve essere conforme ai criteri descritti per l'API Geocoding.

Richieste di geocodifica

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

Puoi accedere al servizio di geocodifica dell'API di Google Maps all'interno del tuo codice tramite l'oggetto costruttore google.maps.Geocoder. Il metodo Geocoder.geocode() avvia una richiesta al servizio di geocodifica, passando un valore letterale 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 solo dei seguenti campi:

address: l'indirizzo che vuoi geocodificare.
o
location: LatLng (o LatLngLiteral) per cui vuoi ottenere l'indirizzo leggibile più vicino. Il geocodificatore esegue un codice geografico inverso. Per ulteriori informazioni, consulta la sezione Invertire la geocodifica.
o
placeId: l'ID del luogo per il quale vuoi ottenere l'indirizzo leggibile più vicino. Scopri di più sul recupero di un indirizzo per un ID luogo.

Parametri facoltativi:

bounds: il LatLngBounds entro il quale differenziare i risultati del geocodice in modo più evidente. Il parametro bounds influenzerà solo, non completamente, i risultati provenienti dal geocodificatore. Scopri di più sulla differenziazione per area visibile di seguito.
componentRestrictions: utilizzata per limitare i risultati a un'area specifica. Leggi ulteriori informazioni sul filtro dei componenti di seguito.
region: il codice regione, specificato come sottotag della regione Unicode a due caratteri (non numerici). Nella maggior parte dei casi, questi tag sono mappati direttamente a valori a due caratteri ccTLD ("dominio di primo livello"). Il parametro region influenzerà solo, non del tutto, i risultati provenienti dal geocodificatore. Scopri di più sulla differenziazione dei codici regione di seguito.
extraComputations: l'unico valore consentito per questo parametro è ADDRESS_DESCRIPTORS. Vedi i descrittori degli indirizzi per maggiori dettagli.
fulfillOnZeroResults: soddisfa la promessa con uno stato ZERO_RESULT nella risposta. Ciò potrebbe essere opportuno perché anche se non ottieni risultati di geocodifica, potrebbero comunque essere restituiti altri campi di livello di risposta. Per ulteriori dettagli, consulta la pagina Evasione degli ordini su zero risultati.

Risposte di geocodifica

Il servizio di geocodifica richiede l'esecuzione di un metodo di callback al momento del recupero dei risultati del geocodificatore. Questo callback deve passare due parametri per contenere il codice results e un 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. Dovrebbero invece essere accessibili attraverso la promessa. Per ulteriori dettagli, consulta la pagina Evasione degli ordini su zero risultati.

Risultati geocodifica

L'oggetto GeocoderResult rappresenta un singolo risultato di geocodifica. Una richiesta di geocodifica può restituire più oggetti risultati:

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 caratteristica restituita nel risultato. Ad esempio, il codice geografico "Chicago" restituisce "locality", che indica che "Chicago" è una città, e restituisce anche "political" (politica), che indica che si tratta di un'entità politica. Leggi ulteriori informazioni sui tipi di indirizzo e sui tipi di componenti di indirizzo di seguito.
formatted_address è una stringa contenente l'indirizzo leggibile di questa località.
Spesso, questo indirizzo equivale 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 è logicamente composto da uno o più componenti di indirizzo. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è costituito dai seguenti componenti: "111" (il numero civico), "8th Avenue" (il percorso), "New York" (la città) e "NY" (lo stato degli Stati Uniti).

Non analizzare l'indirizzo formattato in modo programmatico. Utilizza invece i singoli componenti dell'indirizzo, che include la risposta dell'API, in aggiunta al campo dell'indirizzo formattato.
address_components[] è un array contenente i componenti separati applicabili a questo indirizzo.

In genere, ogni componente dell'indirizzo contiene i seguenti campi:
- types[] è un array che indica il tipo del componente dell'indirizzo. Consulta l'elenco dei tipi supportati.
- long_name è la descrizione testuale completa o il nome del componente dell'indirizzo restituito dal geocoder.
- short_name è un nome testuale abbreviato per il componente dell'indirizzo, se disponibile. Ad esempio, un componente indirizzo per lo stato dell'Alaska potrebbe avere "Alaska" come long_name e short_name "AK" utilizzando l'abbreviazione postale a due lettere.
Tieni presente le seguenti informazioni sull'array address_components[]:
- L'array dei 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 una richiesta e l'altra. 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 mancare in una risposta successiva.
Leggi ulteriori informazioni sui tipi di indirizzo e sui tipi di componenti di indirizzo di seguito.
partial_match indica che il geocodificatore non ha restituito una corrispondenza esatta per la richiesta originale, anche se è riuscito a far corrispondere parte dell'indirizzo richiesto. Ti consigliamo di esaminare la richiesta originale per verificare la presenza di errori ortografici e/o un indirizzo incompleto.

Nella maggior parte dei casi, le corrispondenze parziali si verificano per indirizzi che non esistono all'interno della località passata nella richiesta. Le corrispondenze parziali possono essere restituite anche quando una richiesta corrisponde a due o più sedi nella stessa località. Ad esempio, "Hillpar St, Bristol, UK" restituirà una corrispondenza parziale sia per Henry Street che per Henrietta Street. Tieni presente che se una richiesta include un componente di un indirizzo con errori ortografici, il servizio di geocodifica potrebbe suggerire un indirizzo alternativo. Anche i suggerimenti attivati in questo modo verranno contrassegnati come corrispondenza parziale.
place_idè l'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 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 di Place ID.
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à.
geometry contiene le seguenti informazioni:
- location contiene il valore di latitudine e longitudine geocodificati. Tieni presente che la posizione viene restituita 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 (come gli incroci). In genere, i risultati interpolati vengono 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 una polilinea (ad es. una strada) o un poligono (regione).
  - APPROXIMATE indica che il risultato restituito è approssimativo.
- viewport archivia l'area visibile consigliata per il risultato restituito.
- bounds (restituito facoltativamente) archivia l'elemento LatLngBounds che può contenere completamente il risultato restituito. Tieni presente che questi limiti potrebbero non corrispondere all'area visibile consigliata. Ad esempio, San Francisco include le Isole Faallon, che tecnicamente fanno parte della città, ma non devono essere restituite nell'area visibile.

Gli indirizzi verranno restituiti dal Geocoder 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 pagina Localizzazione.

Tipi di indirizzi e di componenti di indirizzo

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

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

street_address indica un indirizzo preciso.
route indica un percorso denominato (ad esempio "US 101").
intersection indica un incrocio principale, di solito composto da due strade principali.
political indica un'entità politica. Di solito, questo tipo indica un poligono di alcune amministrazioni civili.
country indica l'entità politica nazionale ed è in genere il tipo di ordine più elevato restituito dal geocodificatore.
administrative_area_level_1 indica una persona giuridica civile di primo ordine al di sotto del livello nazionale. 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 Administration_area_level_1 corrisponderanno molto 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 varietà di indicatori e dati sulla posizione.
administrative_area_level_2 indica una persona giuridica civile di secondo ordine al di sotto del livello nazionale. All'interno degli Stati Uniti, questi livelli amministrativi sono contee. Non tutti i paesi presentano questi livelli amministrativi.
administrative_area_level_3 indica una persona giuridica civile di terzo ordine al di sotto del livello del paese. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
administrative_area_level_4 indica una persona giuridica civile di quarto ordine al di sotto del livello del paese. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
administrative_area_level_5 indica una persona giuridica di quinto ordine al di sotto del livello nazionale. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
administrative_area_level_6 indica una persona giuridica civile di sesto ordine al di sotto del livello nazionale. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
administrative_area_level_7 indica una persona giuridica civile di settimo ordine al di sotto del livello nazionale. Questo tipo indica un ente civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
colloquial_area indica un nome alternativo di uso comune per l'entità.
locality indica una città o un'entità politica incorporata in una città.
sublocality indica una persona giuridica di primo ordine sotto una località. Per alcune località potrebbe essere disponibile uno dei seguenti tipi: da sublocality_level_1 a sublocality_level_5. Ogni livello di circoscrizione è un'entità civile. Numeri più grandi indicano un'area geografica più piccola.
neighborhood indica un quartiere denominato
premise indica una posizione denominata, di solito un edificio o un insieme di edifici con un nome comune
subpremise indica un'entità di primo ordine sotto una località denominata, di solito un singolo edificio all'interno di una raccolta di edifici con un nome comune
plus_code indica un riferimento a una località codificato, derivato da latitudine e longitudine. I plus code possono essere utilizzati in sostituzione degli indirizzi stradali in luoghi in cui non sono presenti (in cui gli edifici non sono numerati o le strade non hanno nomi). Per maggiori dettagli, visita la pagina https://plus.codes.
postal_code indica un codice postale utilizzato per la posta all'interno del paese.
natural_feature indica una caratteristica naturale in evidenza.
airport indica un aeroporto.
park indica un parco denominato.
point_of_interest indica un punto d'interesse con nome. In genere, questi "PDI" sono entità locali di spicco che non rientrano facilmente in un'altra categoria, come ad esempio "Empire State Building" o "Torre Eiffel".

Un elenco di tipi vuoto indica che non esistono tipi noti per il componente dell'indirizzo specifico, ad esempio Lieu-dit in Francia.

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

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

floor indica il piano dell'indirizzo di un edificio.
establishment in genere indica un luogo che non è ancora stato classificato.
landmark indica un luogo nelle vicinanze utilizzato come riferimento, per facilitare la navigazione.
point_of_interest indica un punto d'interesse con nome.
parking indica un parcheggio o una struttura di parcheggio.
post_box indica una casella postale specifica.
postal_town indica un raggruppamento di aree geografiche, come locality e sublocality, utilizzate per gli indirizzi postali in alcuni paesi.
room indica la stanza dell'indirizzo di un 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 ed è stato restituito almeno un geocodice.
"ZERO_RESULTS" indica che il geocodice è riuscito, ma non ha restituito risultati. Questo può accadere se al geocodificatore è stato trasmesso un address inesistente.
"OVER_QUERY_LIMIT" indica che hai superato la tua quota.
"REQUEST_DENIED" indica che la tua richiesta è stata rifiutata. La pagina web non può utilizzare il geocodificatore.
"INVALID_REQUEST" indica in genere 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. Riprova.
"ERROR" indica che la richiesta è scaduta o si è verificato un problema nel contattare i server di Google. Riprova.

In questo esempio, geocodificaamo un indirizzo e posizioniamo un indicatore in corrispondenza dei valori di latitudine e longitudine restituiti. Tieni presente che il gestore viene passato come valore letterale 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 esempio.

Differenziazione dell'area visibile

Puoi indicare al servizio di geocodifica di preferire i risultati all'interno di una determinata area visibile (espressi come riquadro di delimitazione). Per farlo, imposta il parametro bounds all'interno del valore letterale dell'oggetto GeocoderRequest per definire i limiti di questa area visibile. Tieni presente che la differenziazione preferisce solo i risultati che rientrano nei limiti; se esistono risultati più pertinenti al di fuori di questi limiti, possono essere inclusi.

Ad esempio, il 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, specificando 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 posizione:

{
  "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"
}

Differenziazione del codice regione

Puoi impostare il servizio di geocodifica in modo che restituisca risultati differenziati per una determinata regione in modo esplicito utilizzando il parametro region. Questo parametro utilizza un codice regione, specificato come sottotag della regione Unicode a due caratteri (non numerici). Questi tag sono mappati direttamente a valori a due caratteri familiari ccTLD ("dominio di primo livello"), come 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. Più valori vengono ignorati e la richiesta potrebbe non andare a buon fine.
Utilizza solo sottotag di regione a due caratteri (formato Unicode CLDR). Tutti gli altri input comporteranno errori.
Sono supportati solo i paesi e le regioni elencati nei dettagli di copertura di Google Maps Platform.

È possibile inviare richieste di geocodifica per ogni dominio in cui l'applicazione principale di Google Maps offre la geocodifica. Tieni presente che la differenziazione preferisce 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 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 di filtro 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 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 circoscrizioni.
administrativeArea corrisponde a tutti i livelli di area amministrativa.
postalCode corrisponde ai codici postali e ai prefissi dei codici postali.
country corrisponde al nome di un 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 al 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:

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

Evasione degli ordini su zero risultati

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

Di seguito è riportato un esempio di questo comportamento per la latitudine/longitudine in Antartide. Anche se non si ottengono risultati di geocodifica inversa, possiamo comunque stampare il plus code 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 degli indirizzi includono informazioni aggiuntive che aiutano a descrivere una località utilizzando punti di riferimento e aree. Guarda la demo dei descrittori degli indirizzi per esplorare la funzionalità.

I descrittori di indirizzo possono essere abilitati tramite l'uso del parametro extraComputations. Includi extra_computations=ADDRESS_DESCRIPTORS in una richiesta di geocodifica , in una richiesta di geocodifica inversa o in una richiesta di geocodifica di luoghi per ricevere i descrittori degli indirizzi nella risposta.

Esempio di geocodifica in 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à a 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 di 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 luogo del risultato dei punti di riferimento. Consulta la panoramica di Place ID.
display_name è il nome visualizzato del punto di riferimento e contiene language_code e text.
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 attraverso la rete stradale (senza indicare i limiti 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 nessuno dei seguenti casi.
"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 accesso o al punto di accesso del punto di riferimento.
"ACROSS_THE_ROAD" quando la coordinata di input è esattamente opposta 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 una rotta perpendicolare come punto di riferimento (limitata a una singola svolta).
"BEHIND" quando la coordinata di input è spaziale vicina al punto di riferimento, ma lontana dal suo punto di accesso.

types sono i tipi di luogo del punto di riferimento.

L'oggetto areas contiene fino a tre risposte e si limita ai luoghi che rappresentano regioni di piccole dimensioni, come quartieri, sottolocalità e grandi complessi. Le aree che contengono la coordinata richiesta sono elencate per prime e sono ordinate dalla più piccola alla più grande. Ogni risultato di areas contiene i seguenti valori:

place_id è l'ID luogo del risultato delle aree. Consulta la panoramica di Place ID.
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 nessuno dei seguenti casi.
"WITHIN" quando la coordinata di input è vicina al centro dell'area.
"OUTSKIRTS" quando la coordinata di input è vicina al bordo dell'area.

Copertura descrittore dell'indirizzo

Questa funzionalità è disponibile soltanto in determinati paesi.

Questa è una funzionalità in anteprima e vorremmo avere un feedback. Inviaci un'email all'indirizzo address-descriptors-feedback@google.com.

Geocodifica inversa (ricerca di indirizzi)

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

Anziché specificare un address testuale, fornisci una coppia latitudine/longitudine separata da virgole nel parametro location.

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

L'esempio seguente geocodifica un valore di latitudine/longitudine e centra la mappa in questa posizione, mostrando 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 un modo qualsiasi per assegnare un nome geografico a una località. Ad esempio, durante la geocodifica di un punto della città di Chicago, il punto geocodificato potrebbe essere etichettato come un indirizzo civico, come la città (Chicago), come stato (Illinois) o come paese (Stati Uniti). Tutti sono indirizzi del 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 può essere restituito dalla query precedente:

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 decrescente. In genere, l'indirizzo più esatto è il risultato più evidente, 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 una corrispondenza con un indirizzo più generico, ti consigliamo di controllare il campo results[].types.

Nota: la geocodifica inversa non è una scienza esatta. Il geocodificatore cercherà di trovare la località indirizzabile più vicina entro una certa tolleranza.

Recupero di un indirizzo per un ID luogo

Specifica un placeId per trovare l'indirizzo di un determinato ID luogo. L'ID luogo è un identificatore univoco che può essere utilizzato con altre API di Google. Ad esempio, puoi fornire il valore placeId restituito dall'API Roads per ottenere l'indirizzo di un punto agganciato. Per ulteriori informazioni 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 anche visualizzata una finestra informativa con l'indirizzo formattato del luogo pertinente: