Servizio di geocodifica

Nota: librerie lato server
Sviluppatori dello Spazio economico europeo (SEE)

Panoramica

Il geocoding è il processo di conversione degli indirizzi (ad esempio "1600 Amphitheatre Parkway, Mountain View, CA") in coordinate geografiche (ad esempio latitudine 37.423021 e longitudine -122.083739), che puoi utilizzare per posizionare 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 ID luogo specifico.

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.

Inizia

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

Per visualizzare l'elenco delle API abilitate:

  1. Vai alla console Google Cloud.
  2. 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.
  3. Nell'elenco delle API nella dashboard, cerca l'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, nel menu a sinistra, seleziona Raccolta.
    2. Cerca l'API Geocoding, quindi selezionala dall'elenco dei risultati.
    3. Seleziona ATTIVA. Al termine del processo, l'API Geocoding viene visualizzata nell'elenco delle API nella dashboard.

Prezzi e norme

Prezzi

Per informazioni sui prezzi e sulle norme di utilizzo del servizio Geocoding JavaScript, consulta Utilizzo e fatturazione per l'API Geocoding.

Norme

L'utilizzo del servizio Geocoding deve essere conforme alle norme 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 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.

Accedi al servizio di geocodifica dell'API Google Maps all'interno del codice utilizzando l'oggetto costruttore google.maps.Geocoder. Il metodo Geocoder.geocode() avvia una richiesta al servizio di geocodifica, passandogli un 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 e uno solo dei seguenti campi:

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

Parametri facoltativi:

  • bounds: il LatLngBounds entro il quale dare maggiore risalto ai risultati di geocodifica. Il parametro bounds influenzerà solo i risultati del geocoder, non li limiterà completamente. Consulta maggiori informazioni sulla distorsione dell'area visibile di seguito.
  • componentRestrictions: utilizzato per limitare i risultati a un'area specifica. Scopri di più sul filtraggio dei componenti di seguito.
  • region: il codice della regione, specificato come tag secondario Unicode di due caratteri (non numerici). Nella maggior parte dei casi, questi tag vengono mappati direttamente ai valori ccTLD (domini di primo livello) a due caratteri. Il parametro region influenzerà solo, non limiterà completamente, i risultati del geocoder. Scopri di più sulla distorsione del codice regione di seguito.
  • extraComputations: l'unico valore consentito per questo parametro è ADDRESS_DESCRIPTORS. Per ulteriori dettagli, vedi descrittori di indirizzo.
  • fulfillOnZeroResults: soddisfa la promessa di uno stato ZERO_RESULT nella risposta. Ciò potrebbe essere utile perché anche con zero risultati di geocodifica potrebbero essere restituiti campi aggiuntivi a livello di risposta. Per ulteriori dettagli, consulta Completamento in caso di zero risultati.

Risposte di geocodifica

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

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 spiegati di seguito:

  • types[] è un array che indica il tipo di indirizzo del risultato restituito. Questo array contiene un insieme di zero o più tag che identificano il tipo di funzionalità restituita nel risultato. Ad esempio, un geocode di "Chicago" restituisce "locality", che indica che "Chicago" è una città, e anche "political", che indica che è un'entità politica. Scopri di più su tipi di indirizzo e tipi di componenti dell'indirizzo di seguito.
  • formatted_address è una stringa contenente l'indirizzo leggibile di questa posizione.

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

    L'indirizzo formattato è composto logicamente da uno o più componenti dell'indirizzo. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è composto dai seguenti componenti: "111" (il numero civico), "8th Avenue" (la strada), "New York" (la città) e "NY" (lo stato degli Stati Uniti).

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

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

    Ogni componente dell'indirizzo in genere 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 o il nome completo del componente dell'indirizzo restituito dal geocodificatore.
    • short_name è un nome testuale abbreviato per il componente dell'indirizzo, se disponibile. Ad esempio, un componente dell'indirizzo per lo stato dell'Alaska potrebbe avere un long_name di "Alaska" e un short_name di "AK" utilizzando l'abbreviazione postale di due lettere.

    Tieni presente quanto segue in merito all'array address_components[]:

    • L'array di componenti dell'indirizzo può contenere più componenti di 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 il geocoding inverso, passando la latitudine/longitudine dell'indirizzo come parametro alla richiesta.
    • Non è garantito che il formato della risposta rimanga lo stesso tra le richieste. In particolare, il numero di address_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 non essere presente in una risposta successiva.

    Scopri di più su tipi di indirizzo e tipi di componenti dell'indirizzo di seguito.

  • partial_match indica che il geocoder non ha restituito una corrispondenza esatta per la richiesta originale, anche se è riuscito a trovare una corrispondenza parziale dell'indirizzo richiesto. Ti consigliamo di esaminare la richiesta originale per verificare la presenza di errori ortografici e/o un indirizzo incompleto.

    Le corrispondenze parziali si verificano più spesso per gli indirizzi stradali che non esistono all'interno della località che trasmetti nella richiesta. Le corrispondenze parziali possono essere restituite anche quando una richiesta corrisponde a due o più località nella stessa località. Ad esempio, "Hillpar St, Bristol, UK" restituirà una corrispondenza parziale sia per Henry Street che per Henrietta Street. Tieni presente che se una richiesta include un componente dell'indirizzo scritto in modo errato, il servizio di geocoding potrebbe suggerire un indirizzo alternativo. I suggerimenti attivati in questo modo verranno contrassegnati anche come corrispondenza parziale.

  • place_idè un identificatore univoco di un luogo, che può essere utilizzato con altre API di Google. Ad esempio, puoi utilizzare place_id con la libreria dell'API Google Places per ottenere i dettagli di un'attività locale, come il numero di telefono, l'orario di apertura, le recensioni degli utenti e altro ancora. Consulta la panoramica dell'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 geocodificato. Tieni presente che restituiamo questa posizione come oggetto LatLng, non come stringa formattata.
    • location_type memorizza dati aggiuntivi sulla località specificata. Sono supportati i seguenti valori:
      • ROOFTOP indica che il risultato restituito riflette un geocodice preciso.
      • RANGE_INTERPOLATED indica che il risultato restituito riflette un'approssimazione (di solito su una strada) interpolata tra due punti precisi (ad esempio incroci). I risultati interpolati vengono generalmente restituiti quando i geocodici 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 esempio una strada) o un poligono (regione).
      • APPROXIMATE indica che il risultato restituito è approssimativo.

    • viewport memorizza la finestra consigliata per il risultato restituito.
    • bounds (restituito facoltativamente) memorizza il LatLngBounds che può contenere completamente il risultato restituito. Tieni presente che questi limiti potrebbero non corrispondere alla finestra consigliata. (Ad esempio, San Francisco include le isole Farallon, che tecnicamente fanno parte della città, ma non devono essere restituite nella finestra.)

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

Tipi di indirizzo e tipi di componenti dell'indirizzo

L'array types[] in GeocoderResult nella risposta indica il tipo di indirizzo. Esempi di tipi di indirizzo includono un indirizzo stradale, un paese o un'entità politica. L'array types in GeocoderAddressComponent indica il tipo di ogni parte dell'indirizzo. Alcuni esempi sono il numero civico o il paese.

Gli indirizzi possono avere più tipi. I tipi possono essere considerati "tag". Ad esempio, molte città sono taggate con i tipi political e locality.

Sono supportati i seguenti tipi, restituiti sia negli array di tipi di indirizzo sia di tipi di componenti di indirizzo:

Tipo di indirizzo Descrizione
street_address Un indirizzo preciso.
route Un percorso denominato (ad esempio "US 101").
intersection Un incrocio importante, di solito tra due strade principali.
political Un'entità politica. In genere, questo tipo indica un poligono di un'amministrazione civile.
country L'entità politica nazionale, in genere il tipo di ordine più elevato restituito dal geocodificatore.
administrative_area_level_1 Una divisione amministrativa principale al di sotto del livello paese. Negli Stati Uniti, questi livelli amministrativi sono gli stati. Non tutte le nazioni presentano questi livelli amministrativi. Nella maggior parte dei casi, i nomi brevi administrative_area_level_1 corrispondono strettamente alle suddivisioni ISO 3166-2 e ad altri elenchi ampiamente diffusi; tuttavia, ciò non è garantito, in quanto i nostri risultati di geocodifica si basano su una serie di indicatori e dati sulla posizione.
administrative_area_level_2 Una divisione amministrativa di secondo livello al di sotto del livello paese. Negli Stati Uniti, questi livelli amministrativi sono le contee. Non tutte le nazioni presentano questi livelli amministrativi.
administrative_area_level_3 Una divisione amministrativa di terzo livello al di sotto del livello paese. Questo tipo indica una suddivisione civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
administrative_area_level_4 Una divisione amministrativa di quarto livello al di sotto del livello paese. Questo tipo indica una suddivisione civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
administrative_area_level_5 Una divisione amministrativa di quinto livello al di sotto del livello paese. Questo tipo indica una suddivisione civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
administrative_area_level_6 Una divisione amministrativa di sesto livello al di sotto del livello paese. Questo tipo indica una suddivisione civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
administrative_area_level_7 Una divisione amministrativa di settimo livello al di sotto del livello paese. Questo tipo indica una suddivisione civile minore. Non tutte le nazioni presentano questi livelli amministrativi.
colloquial_area Un nome alternativo comunemente utilizzato per l'entità.
locality Un'entità politica di una città o di un comune costituita in società.
sublocality Una divisione amministrativa di primo livello al di sotto di una località. Per alcune località potrebbe essere visualizzato uno dei tipi aggiuntivi: sublocality_level_1 - sublocality_level_5. Ogni livello di località secondaria è un'entità civile. I numeri più grandi indicano un'area geografica più piccola.
neighborhood Un quartiere con un nome.
premise Una località denominata, di solito un edificio o un insieme di edifici con un nome comune.
subpremise Un'entità indirizzabile al di sotto del livello dell'edificio, ad esempio un appartamento, un'unità o una suite.
plus_code Un riferimento alla posizione codificato, derivato da latitudine e longitudine. I Plus Code possono essere utilizzati in sostituzione degli indirizzi stradali nei luoghi in cui non esistono (dove gli edifici non sono numerati o le strade non hanno un nome). Per maggiori dettagli, visita la pagina https://plus.codes.
postal_code Un codice postale utilizzato per la spedizione della posta tradizionale di un paese.
natural_feature Un elemento naturale di spicco.
airport Un aeroporto.
park Un parco con nome.
point_of_interest Un punto d'interesse denominato. In genere, questi "PDI" sono entità locali importanti che non rientrano facilmente in un'altra categoria, ad esempio "Empire State Building" o "Torre Eiffel".

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

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

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

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

Tipo di componente dell'indirizzo Descrizione
floor Il piano di un indirizzo dell'edificio.
establishment In genere un luogo che non è ancora stato classificato.
landmark Un luogo nelle vicinanze utilizzato come riferimento per facilitare la navigazione.
point_of_interest Un punto d'interesse denominato.
parking Un parcheggio o una struttura per parcheggiare l'auto.
post_box Una casella postale specifica.
postal_town Un raggruppamento di aree geografiche, ad esempio locality e sublocality, utilizzato per gli indirizzi postali in alcuni paesi.
room La stanza di un indirizzo dell'edificio.
street_number Il numero civico preciso.
bus_station, train_station e transit_station La posizione di una fermata di autobus, treno o trasporto pubblico.

Codici di stato

Il codice status 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 è stato creato correttamente, ma non ha restituito risultati. Ciò può verificarsi se al geocoder è stato trasmesso 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.
  • "INVALID_REQUEST" in genere indica che la query (address, components o latlng) è mancante.
  • "UNKNOWN_ERROR" indica che la richiesta non è stata elaborata a causa di un errore del server. La richiesta potrebbe andare a buon fine se riprovi.
  • "ERROR" indica che la richiesta è scaduta o che si è verificato un problema durante il contatto con i server di Google. La richiesta potrebbe andare a buon fine se riprovi.

In questo esempio, codifichiamo geograficamente 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.

Bias dell'area visibile

Puoi indicare al servizio di geocodifica di preferire i risultati all'interno di una determinata area visibile (espressa come riquadro di selezione). 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 distorsione privilegia solo i risultati entro i limiti; se esistono risultati più pertinenti al di fuori di questi limiti, potrebbero essere inclusi.

Ad esempio, un geocodice per "Winnetka" 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, la specifica di un parametro bounds che definisce un riquadro di delimitazione per la San Fernando Valley di Los Angeles fa sì che questo geocodice restituisca 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 a una determinata regione in modo esplicito utilizzando il parametro region. Questo parametro accetta un codice regione, specificato come tag secondario regione Unicode di due caratteri (non numerici). Questi tag vengono mappati direttamente ai valori ccTLD (domini di primo livello) a due caratteri, ad esempio "uk" in "co.uk". In alcuni casi, il tag region supporta anche i codici ISO 3166-1, che a volte differiscono dai valori dei TLD con codice paese ("GB" per "Gran Bretagna", ad esempio).

Quando utilizzi il parametro region:

  • Specifica un solo paese o una sola regione. Più valori vengono ignorati e potrebbero comportare un errore della richiesta.
  • Utilizza solo sottotag di regione di due caratteri (formato Unicode CLDR). Tutti gli altri input genereranno errori.
  • Sono supportati solo i paesi e le regioni elencati nei Dettagli della copertura di Google Maps Platform.

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

Ad esempio, un geocodice per "Toledo" restituisce questo risultato, poiché il dominio predefinito per il servizio 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 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"
}

Component Filtering

Puoi impostare il servizio di geocoding in modo che restituisca risultati di indirizzi limitati a un'area specifica utilizzando un filtro dei componenti. Specifica il filtro nel parametro componentRestrictions. I valori dei filtri supportano gli stessi metodi di correzione ortografica e corrispondenza parziale delle altre richieste di geocodifica.

Il geocoder restituisce solo i risultati che corrispondono a tutti i filtri dei componenti. ovvero valuta le specifiche del filtro come AND, non come OR.

Un filtro dei componenti è composto da uno o più dei seguenti elementi:

  • route corrisponde al nome lungo o breve di un percorso.
  • locality corrisponde ai tipi di località e località secondaria.
  • 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 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 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 in caso di zero risultati

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

Di seguito è riportato un esempio di questo comportamento per una latitudine/longitudine in Antartide. Anche se non ci sono 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 dell'indirizzo

I descrittori dell'indirizzo includono informazioni aggiuntive che aiutano a descrivere una località utilizzando punti di riferimento e aree. Dai un'occhiata alla demo dei descrittori di indirizzi per esplorare la funzionalità.

I descrittori di indirizzi possono essere attivati tramite l'utilizzo 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 Places per ricevere i descrittori dell'indirizzo nella risposta.

Esempio di geocodifica dei luoghi

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

function addressDescriptorPlaceIdLookup() {
  geocoder.geocode({
  geocoder.geocode({
    'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q',
    'extraComputations': ['ADDRESS_DESCRIPTORS']
    }, function(results, status) {
    if (status == 'OK') {
      console.log(results[0].address_descriptor);
    } else {
      window.alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

Esempio di geocodifica inversa

La seguente query contiene il valore di latitudine/longitudine 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 dell'indirizzo

Ecco un esempio di address_descriptor.

  {
    "address_descriptor" : {
       "areas" : [
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Turkman Gate"
             },
             "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs"
          },
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Chandni Chowk"
             },
             "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI"
          },
          {
             "containment" : "NEAR",
             "display_name" : {
                "language_code" : "en",
                "text" : "Katar Ganj"
             },
             "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY"
          }
       ],
       "landmarks" : [
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delite Cinema"
             },
             "straight_line_distance_meters" : 29.9306755065918,
             "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM",
             "travel_distance_meters" : 418.7794799804688,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "establishment", "movie_theater", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "YES Bank"
             },
             "straight_line_distance_meters" : 66.83731079101562,
             "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ",
             "travel_distance_meters" : 489.0340270996094,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "UCO Bank"
             },
             "straight_line_distance_meters" : 25.38849639892578,
             "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM",
             "travel_distance_meters" : 403.2246398925781,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delhi By Cycle Meeting Point"
             },
             "straight_line_distance_meters" : 44.02867126464844,
             "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM",
             "travel_distance_meters" : 97.41281890869141,
             "spatial_relationship" : "AROUND_THE_CORNER",
             "types" : [
                "establishment",
                "point_of_interest",
                "tourist_attraction",
                "travel_agency"
             ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Axis Bank Branch"
             },
             "straight_line_distance_meters" : 102.3495178222656,
             "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4",
             "travel_distance_meters" : 330.8566284179688,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          }
       ]
    }
  }

Ogni oggetto address_descriptor contiene 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 del punto di riferimento contiene i seguenti valori:

  • place_id è l'ID luogo del risultato dei punti di riferimento. Consulta la panoramica dell'ID luogo.
  • display_name è il nome visualizzato del punto di riferimento e contiene language_code e text.
  • straight_line_distance_meters è la distanza punto-punto in metri tra la coordinata di input e il risultato dei punti di riferimento.
  • travel_distance_meters è la distanza in metri percorsa utilizzando la rete stradale (ignorando le limitazioni stradali) tra le coordinate di input e il risultato dei punti di riferimento.
  • spatial_relationship è la relazione stimata tra la coordinata di input e il risultato dei punti di riferimento:
    • "NEAR" è la relazione predefinita quando non si applica nessuna delle seguenti condizioni.
    • "WITHIN" quando la coordinata di input è contenuta nei limiti della struttura associata al punto di riferimento.
    • "BESIDE" quando la coordinata di input è direttamente adiacente al punto di riferimento o al punto di accesso del punto di riferimento.
    • "ACROSS_THE_ROAD" quando la coordinata di input si trova direttamente di fronte al punto di riferimento sull'altro lato del percorso.
    • "DOWN_THE_ROAD" quando le coordinate di input si trovano sullo stesso percorso del punto di riferimento, ma non "BESIDES" o "ACROSS_THE_ROAD".
    • "AROUND_THE_CORNER" quando la coordinata di input si trova lungo un percorso perpendicolare al punto di riferimento (limitato a una sola svolta).
    • "BEHIND" quando la coordinata di input è spazialmente 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 a luoghi che rappresentano piccole regioni, come quartieri, località secondarie 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 dell'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 di input è vicina al centro dell'area.
    • "OUTSKIRTS" quando la coordinata di input è vicina al bordo dell'area.

Copertura dei descrittori dell'indirizzo

I descrittori dell'indirizzo sono disponibili in GA per l'India. L'utilizzo dei descrittori di indirizzi in India non comporta costi aggiuntivi e l'utilizzo è coperto dallo SKU Geocoding (India) Essentials esistente.

Feedback

Questa funzionalità è disponibile in tutte le regioni. È in GA per l'India e nella fase di lancio sperimentale pre-GA per tutte le altre regioni. Apprezziamo il tuo feedback:

Geocodifica inversa (ricerca indirizzo)

Il termine geocodifica si riferisce generalmente alla conversione di un indirizzo leggibile in una posizione su una mappa. La procedura inversa, ovvero la conversione di una posizione sulla mappa in un indirizzo leggibile, è nota come geocodifica inversa.

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

L'esempio seguente esegue il geocoding di un valore di latitudine/longitudine e centra la mappa in quella posizione, visualizzando una finestra informativa con l'indirizzo formattato:

TypeScript

let marker;

async function initMap() {
    //  Request the needed libraries.
    const [{ Map, InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] =
        await Promise.all([
            google.maps.importLibrary(
                'maps'
            ) as Promise<google.maps.MapsLibrary>,
            google.maps.importLibrary(
                'geocoding'
            ) as Promise<google.maps.GeocodingLibrary>,
            google.maps.importLibrary(
                'marker'
            ) as Promise<google.maps.MarkerLibrary>,
        ]);

    // Get the gmp-map element.
    const mapElement = document.querySelector(
        'gmp-map'
    ) as google.maps.MapElement;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng') as HTMLInputElement;

    // Get the submit button.
    const submitButton = document.getElementById('submit') as HTMLElement;

    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
    });

    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    const geocoder = new Geocoder();
    const infowindow = new InfoWindow();

    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        geocodeLatLng(geocoder, innerMap, infowindow);
    });

    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
        geocodeLatLng(geocoder, innerMap, infowindow);
    });

    // Make an initial request upon loading.
    geocodeLatLng(geocoder, innerMap, infowindow);
}

async function geocodeLatLng(
    geocoder: google.maps.Geocoder,
    map: google.maps.Map,
    infowindow: google.maps.InfoWindow
) {
    const input = (document.getElementById('latlng') as HTMLInputElement).value;
    const latlngStr = input.split(',', 2);
    const latlng = {
        lat: parseFloat(latlngStr[0]),
        lng: parseFloat(latlngStr[1]),
    };

    geocoder
        .geocode({ location: latlng })
        .then((response) => {
            if (response.results[0]) {
                marker.position = latlng;
                map.setCenter(latlng);
                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));
}

initMap();
index.ts

JavaScript

let marker;
async function initMap() {
    //  Request the needed libraries.
    const [{ Map, InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('geocoding'),
        google.maps.importLibrary('marker'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng');
    // Get the submit button.
    const submitButton = document.getElementById('submit');
    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
    });
    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });
    const geocoder = new Geocoder();
    const infowindow = new InfoWindow();
    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Make an initial request upon loading.
    geocodeLatLng(geocoder, innerMap, infowindow);
}
async function geocodeLatLng(geocoder, map, infowindow) {
    const input = document.getElementById('latlng').value;
    const latlngStr = input.split(',', 2);
    const latlng = {
        lat: parseFloat(latlngStr[0]),
        lng: parseFloat(latlngStr[1]),
    };
    geocoder
        .geocode({ location: latlng })
        .then((response) => {
        if (response.results[0]) {
            marker.position = latlng;
            map.setCenter(latlng);
            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));
}
initMap();
index.js
Visualizza esempio

Prova campione

Tieni presente che nell'esempio precedente abbiamo mostrato il primo risultato selezionando results[0]. Il geocodificatore inverso spesso restituisce più di un risultato. Gli indirizzi geocodificati non sono solo indirizzi postali, ma qualsiasi modo per denominare geograficamente una località. Ad esempio, quando viene geocodificato un punto nella città di Chicago, il punto geocodificato può essere etichettato come indirizzo stradale, come città (Chicago), come stato (Illinois) o come paese (Stati Uniti). Tutti sono indirizzi per il 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 la query precedente potrebbe restituire: 

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

Gli indirizzi vengono restituiti in ordine di corrispondenza migliore. In genere, l'indirizzo più esatto è il risultato più in evidenza, come in questo caso. Tieni presente che restituiamo diversi tipi di indirizzi, dall'indirizzo stradale 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 esaminare il campo results[].types.

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

Quando fornisci un placeId, la richiesta non può contenere nessuno dei seguenti campi:

  • 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:

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;
index.ts

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;
index.js
Visualizza esempio

Prova campione