Servizio di geocodifica

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Panoramica

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

La codifica geografica 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 base all'input utente. Se invece vuoi geocodificare indirizzi noti e statici, consulta il servizio web di geocodifica.

Per cominciare

Prima di utilizzare il servizio Geocoding nell'API Maps JavaScript, assicurati che l'API Geocoding sia abilitata in Google Cloud Console, nello stesso progetto configurato per l'API Maps JavaScript.

Per visualizzare l'elenco delle API abilitate:

  1. Vai a Google Cloud Console.
  2. Fai clic sul pulsante Seleziona un progetto, quindi scegli lo stesso progetto che hai configurato per l'API Maps JavaScript e fai clic su Apri.
  3. Nell'elenco delle API nella Dashboard, cerca API Geocoding.
  4. Se vedi l'API nell'elenco, non devi fare altro. Se l'API non è elencata, abilitala:
    1. Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Libreria. In alternativa, seleziona Raccolta dal menu laterale a sinistra.
    2. Cerca API Geocoding, quindi selezionala dall'elenco dei risultati.
    3. Seleziona ABILITA. Al termine della procedura, l'API Geocoding sarà visualizzata nell'elenco delle API sulla Dashboard.

Prezzi e norme

Prezzi

Dal 16 luglio 2018 è entrato in vigore un nuovo piano con pagamento a consumo per Maps, Routes e Places. Per ulteriori informazioni sui nuovi prezzi e limiti di utilizzo per il servizio di geocodifica JavaScript, consulta la sezione Utilizzo e fatturazione per l'API Geocoding.

Limiti di frequenza

Tieni presente quanto segue in merito alle limitazioni di frequenza per le richieste aggiuntive:

Il limite di frequenza aggiuntivo viene applicato per sessione utente, indipendentemente dal numero di utenti che condividono lo stesso progetto. Quando carichi l'API per la prima volta, ti viene assegnata una quota iniziale di richieste. Una volta utilizzata questa quota, l'API applica limiti di frequenza su richieste aggiuntive al secondo. Se vengono effettuate troppe richieste in un determinato periodo di tempo, l'API restituisce un codice di risposta OVER_QUERY_LIMIT.

Il limite di frequenza per sessione impedisce l'utilizzo di servizi lato client per le richieste batch, ad esempio la geocodifica in batch. Per le richieste in batch, usa il servizio web dell'API Geocoding.

Criteri

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

Richieste di geocodifica

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

Accedi 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 di oggetto GeocoderRequest contenente i termini di input e un metodo di callback da eseguire al ricevimento della risposta.

Il valore letterale oggetto GeocoderRequest contiene i seguenti campi:

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

Parametri obbligatori. Devi specificare uno solo dei seguenti campi:

  • address: l'indirizzo che vuoi geocodificare
    oppure
    location: il LatLng (o LatLngLiteral) per il quale vuoi ottenere l'indirizzo più leggibile. Il geocodificatore esegue una codifica geografica inversa. Per ulteriori informazioni, consulta la sezione Geocodifica inversa.
    oppure
    placeId: l'ID del luogo per il quale vuoi ottenere l'indirizzo più simile e leggibile. Scopri di più sul recupero di un indirizzo per un ID luogo.

Parametri facoltativi:

  • bounds: LatLngBounds all'interno del quale orientare i risultati geografici in modo più evidente. Il parametro bounds influenza solo i risultati del geocodificatore, non limitandoli. Di seguito sono riportate ulteriori informazioni sulla previsione delle visualizzazioni.
  • componentRestrictions: utilizzato per limitare i risultati a un'area specifica. Leggi ulteriori informazioni sul filtro dei componenti di seguito.
  • region: il codice della regione, specificato come un sottoregione Unicode di due caratteri (non numerico). Nella maggior parte dei casi, questi tag mappano direttamente i valori a due caratteri ccTLD (dominio di primo livello) che conosci. Il parametro region influenza solo i risultati del geocodificatore, non limitandoli. Di seguito sono riportate ulteriori informazioni sulla polarizzazione del codice in base all'area geografica.

Risposte di geocodifica

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

Risultati di geocodifica

L'oggetto GeocoderResult rappresenta un singolo risultato di geocodifica. Una richiesta geocodificata 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 illustrati 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, un blocco geografico di "Chicago" restituisce "località" che indica che "Chicago" è una città e restituisce anche "politico" che indica che è un'entità politica. Di seguito sono riportate ulteriori informazioni sui tipi di indirizzi e sui tipi di componenti degli indirizzi.
  • formatted_address è una stringa contenente l'indirizzo leggibile di questa località.

    Spesso questo indirizzo è equivalente all'indirizzo postale. Tieni presente che alcuni paesi, come il Regno Unito, non consentono la distribuzione di indirizzi postali reali a causa di limitazioni relative alle licenze.

    L'indirizzo formattato è logicamente composto da uno o più componenti dell'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" (stato degli Stati Uniti).

    Non analizzare l'indirizzo formattato in modo programmatico. Utilizza invece i singoli componenti dell'indirizzo, che includono la risposta dell'API, oltre al campo dell'indirizzo formattato.

  • address_components[] è un array contenente i componenti separati applicabili a questo indirizzo.

    Ciascun componente dell'indirizzo contiene in genere i seguenti campi:

    • types[] è un array che indica il tipo del componente indirizzo. Consulta l'elenco dei tipi supportati.
    • long_name è la descrizione completa del testo 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 può avere un long_name di "Alaska" e un short_name di "AK"; utilizzando l'abbreviazione postale di 2 lettere.

    Osserva le seguenti informazioni sull'array di address_components[]:

    • L'array dei componenti indirizzo può contenere più componenti di formatted_address.
    • L'array non include necessariamente tutte le entità politiche che contengono un indirizzo, oltre a 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 la posizione nell'array. Il tipo del componente può cambiare. Un determinato componente potrebbe mancare in una risposta successiva.

    Di seguito sono riportate ulteriori informazioni sui tipi di indirizzi e sui tipi di componenti degli indirizzi.

  • partial_match indica che il geocodificatore non ha restituito una corrispondenza esatta per la richiesta originale, anche se era in grado di corrispondere a parte dell'indirizzo richiesto. Ti consigliamo di esaminare la richiesta originale di errori ortografici e/o un indirizzo incompleto.

    Nella maggior parte dei casi, le corrispondenze parziali si verificano per gli indirizzi che non esistono nella località specificata 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, Regno Unito" restituirà una corrispondenza parziale sia per Henry Street che per Henrietta Street. Tieni presente che se una richiesta include un componente indirizzo errato, il servizio di geocodifica potrebbe suggerire un indirizzo alternativo. Anche i suggerimenti attivati in questo modo verranno contrassegnati come corrispondenze parziali.

  • place_idè un identificatore univoco di un luogo, che può essere utilizzato con altre API di Google. Ad esempio, potete utilizzare place_id con la libreria API di Google Places per ottenere dettagli su un'attività locale, come numero di telefono, orari di apertura, recensioni degli utenti e altro ancora. Consulta la panoramica sull'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à.
  • geometry contiene le seguenti informazioni:

    • location contiene il valore di latitudine e longitudine geocodificata. Tenete 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 una geocodifica precisa.
      • RANGE_INTERPOLATED indica che il risultato restituito riflette un'approssimazione (di solito su una strada) interpolata tra due punti precisi (come incroci). In genere i risultati interpolati vengono restituiti quando i codici geografici panoramici non sono disponibili per un indirizzo.
      • GEOMETRIC_CENTER indica che il risultato restituito è il centro geometrico di un risultato, come una polilinea (ad esempio, una strada) o un poligono (regione).
      • APPROXIMATE indica che il risultato restituito è approssimativo.

    • viewport archivia l'area visibile consigliata per il risultato restituito.
    • (Facoltativo) bounds archivia 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 Farallon, che sono tecnicamente 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 del codice JavaScript dell'API utilizzando il parametro language. Per ulteriori informazioni, consulta la sezione Localizzazione.

Tipi di indirizzo e tipi di componenti di indirizzo

L'array types[] nel GeocoderResult indica il tipo di indirizzo. L'array types[] può essere restituito anche all'interno di un GeocoderAddressComponent per indicare il tipo del particolare componente indirizzo. Gli indirizzi restituiti dal geocodificatore potrebbero avere più tipi, che 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 in i tipi di indirizzo che nei tipi di componenti dell'indirizzo:

  • street_address indica un indirizzo preciso.
  • route indica un percorso denominato (ad esempio"US 101").
  • intersection indica un incrocio principale, generalmente composto da due strade principali.
  • political indica un'entità politica. Di solito, questo tipo indica un poligono di qualche amministrazione civile.
  • country indica l'entità politica nazionale e in genere è il tipo di ordine più elevato restituito dal Geocoder.
  • administrative_area_level_1 indica un'entità civile di primo ordine al di sotto del paese. All'interno degli Stati Uniti, questi livelli amministrativi sono stati. Non tutti i paesi espongono questi livelli amministrativi. Nella maggior parte dei casi, i nomi brevi di admin_area_level_1 corrisponderanno strettamente alle suddivisioni ISO 3166-2 e ad altri elenchi diffusi; tuttavia, ciò non è garantito in quanto i risultati della geocodifica si basano su una serie di indicatori e dati sulla posizione.
  • administrative_area_level_2 indica un'entità civile del secondo ordine sotto il livello del paese. All'interno degli Stati Uniti, questi livelli amministrativi sono contee. Non tutti i paesi espongono questi livelli amministrativi.
  • administrative_area_level_3 indica un'entità civile del terzo ordine sotto il livello del paese. Questo tipo indica una circoscrizione civile secondaria. Non tutti i paesi espongono questi livelli amministrativi.
  • administrative_area_level_4 indica un'entità civile del quarto ordine sotto il livello del paese. Questo tipo indica una circoscrizione civile secondaria. Non tutti i paesi espongono questi livelli amministrativi.
  • administrative_area_level_5 indica un'entità civile di quinto ordine al di sotto del livello paese. Questo tipo indica una circoscrizione civile secondaria. Non tutti i paesi espongono questi livelli amministrativi.
  • administrative_area_level_6 indica un'entità civile del sesto ordine al di sotto del livello del paese. Questo tipo indica una circoscrizione civile secondaria. Non tutti i paesi espongono questi livelli amministrativi.
  • administrative_area_level_7 indica un'entità civile del settimo ordine sotto il livello del paese. Questo tipo indica una circoscrizione civile secondaria. Non tutti i paesi espongono questi livelli amministrativi.
  • colloquial_area indica un nome alternativo di uso comune per l'entità.
  • locality indica un'entità politica costituita in città.
  • sublocality indica una persona giuridica di primo ordine sotto una località. Per alcune località potrebbe essere disponibile uno dei seguenti tipi aggiuntivi: da sublocality_level_1 a sublocality_level_5. Ogni livello di circoscrizione è un'entità civile. I numeri più grandi indicano un'area geografica più piccola.
  • neighborhood indica un quartiere denominato
  • premise indica una località denominata, in genere un edificio o una serie di edifici con un nome comune
  • subpremise indica un'entità di primo ordine sotto una località denominata, in genere un singolo edificio all'interno di una raccolta di edifici con un nome comune
  • plus_code indica un riferimento a una località codificata, derivato da latitudine e longitudine. I plus code possono essere utilizzati in sostituzione degli indirizzi stradali 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 indirizzare 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 di interesse denominato. In genere, queste "principali" sono entità locali di spicco che non si adattano facilmente a un'altra categoria, come "Empire State Building" o "Eiffel Tower".

Un elenco vuoto dei tipi indica che non ci sono tipi noti per il particolare componente indirizzo, ad esempio Lieu-dit in Francia.

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

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

  • floor indica il piano dell'indirizzo di un edificio.
  • establishment in genere indica un luogo non ancora classificato.
  • landmark indica un luogo vicino che viene utilizzato come riferimento per agevolare la navigazione.
  • point_of_interest indica un punto di interesse denominato.
  • parking indica un parcheggio o una struttura per il 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 di un indirizzo dell'edificio.
  • street_number indica il numero esatto della via.
  • 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 è stato restituito almeno un codice geografico.
  • "ZERO_RESULTS" indica che la geocodifica è riuscita, ma non ha restituito risultati. Questo può verificarsi se al geocodificatore viene trasmesso un elemento 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 è autorizzata a utilizzare il geocodificatore.
  • "INVALID_REQUEST" indica in genere che la query (address, components o latlng) è mancante.
  • "UNKNOWN_ERROR" indica che non è stato possibile elaborare la richiesta a causa di un errore del server. Se richiedi di nuovo un tentativo, la richiesta potrebbe avere esito positivo.
  • "ERROR" indica che la richiesta è scaduta o si è verificato un problema durante il contatto con i server di Google. Se richiedi di nuovo un tentativo, la richiesta potrebbe avere esito positivo.

In questo esempio, geocodificamo un indirizzo e inseriamo un indicatore nei valori di latitudine e longitudine restituiti. Tieni presente che il gestore viene passato come un valore letterale di funzione anonimo.

  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.

Differenziazione area visibile

Puoi indicare al servizio di geocodifica di preferire i risultati all'interno di un'area visibile specifica (espressa come riquadro di delimitazione). Per farlo, imposta il parametro bounds all'interno del valore letterale oggetto GeocoderRequest in modo da definire i limiti di questa area visibile. Tenete presente che la differenziazione dei risultati preferisce solo 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" in genere 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 valle di San Fernando di Los Angeles, questo codice geografico restituisce il quartiere chiamato "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"
}

Differenziazione del codice per regione

Puoi impostare il servizio di geocodifica in modo che restituisca esplicitamente i risultati di una determinata regione utilizzando il parametro region. Questo parametro accetta un codice di regione, specificato come sottoregione Unicode di due caratteri (non numerico). Questi tag corrispondono direttamente al familiare ccTLD ("dominio di primo livello") a due caratteri, ad esempio "uk" in "co.uk" ad esempio. In alcuni casi, il tag region supporta anche i codici ISO-3166-1, che talvolta differiscono dai valori ccTLD (ad esempio GB, per"Gran Bretagna").

Quando utilizzi il parametro region:

  • Specifica un solo paese o una sola area geografica. Più valori vengono ignorati e potrebbero generare una richiesta non riuscita.
  • Utilizza solo sottotag di due caratteri che utilizzano la regione (formato Unicode CLDR). Tutti gli altri input generano errori.
  • Sono supportati solo i paesi e le aree geografiche elencati nei dettagli della copertura di Google Maps Platform.

Le richieste di geocodifica possono essere inviate per ogni dominio in cui l'applicazione principale di Google Maps offre la geocodifica. Tenete presente che la differenziazione dei risultati preferisce solo per un dominio specifico; se esistono risultati più pertinenti al di fuori di questo dominio, potrebbero essere inclusi.

Ad esempio, un codice geografico per "Toledo"; toledo" restituisce questo risultato, poiché il dominio predefinito per il servizio Geocoding è 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"
}

Filtraggio componenti

Puoi impostare il servizio di geocodifica in modo che restituisca i 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 di corrispondenza parziale di 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:

  • route corrisponde al nome lungo o breve di un percorso.
  • locality cerca corrispondenze con i tipi di località e località secondarie.
  • 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 meglio quando viene utilizzato il codice ISO corrispondente del paese.

L'esempio seguente mostra l'utilizzo del parametro componentRestrictions per filtrare per 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);
  }
});
}

Geocodifica inversa (ricerca indirizzi)

Il termine geocodifica si riferisce in genere alla traduzione di un indirizzo leggibile in una località su una mappa. Il processo di conversione della località, sulla mappa, in un indirizzo leggibile è noto come geocodifica inversa.

Invece di fornire una 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:

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;

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;
Visualizza l'esempio

Prova Esempio

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 un modo geografico per denominare una località. Ad esempio, durante 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). Sono tutti indirizzi al geocodificatore. Il geocodificatore inverso restituisce tutti questi risultati.

Il geocodificatore inverso corrisponde a entità politiche (paesi, province, città e quartieri), indirizzi e codici postali.

Ecco un esempio dell'elenco di indirizzi che potrebbero restituire la query indicata sopra:

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 base alle migliori corrispondenze. In genere, l'indirizzo più esatto è il risultato più in evidenza, 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ù generale, controlla il campo results[].types.

Nota: la geocodifica inversa non è una scienza esatta. Il geocodificatore tenterà di trovare la località indirizzabile più vicina entro una certa 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 di Google. Ad esempio, puoi fornire il valore placeId restituito dall'API Roads per ottenere l'indirizzo per un punto agganciato. Per scoprire di più sugli ID luogo, consulta la panoramica sull'ID luogo.

Quando fornisci un elemento placeId, la richiesta non può contenere i seguenti campi:

  • address
  • latLng
  • location
  • componentRestrictions

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

TypeScript

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

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

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const placeId = (document.getElementById("place-id") as HTMLInputElement)
    .value;

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

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(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;

JavaScript

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

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

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(geocoder, map, infowindow) {
  const placeId = document.getElementById("place-id").value;

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

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(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;
Visualizza l'esempio

Prova Esempio