La geocodifica è il processo di conversione degli indirizzi ("1600 Amphitheatre Parkway, Mountain View, CA") in coordinate geografiche (37.423021, -122.083739), che puoi utilizzare per posizionare indicatori o la mappa. Le API di Google Maps Platform offrono due approcci alla geocodifica:
- Geocodifica lato client, eseguita nel browser, in genere in risposta all'azione dell'utente. L'API Maps JavaScript fornisce classi che effettuano le richieste per te. Questo approccio è descritto nella documentazione dell'API Maps JavaScript.
- Geocodifica lato server HTTP, che consente al tuo server di eseguire query direttamente sui server di Google per ottenere i geocodici. L'API Geocoding è il servizio web che fornisce questa funzionalità. In genere, questo servizio viene integrato con altro codice in esecuzione lato server. La geocodifica lato server è descritta nella documentazione dell'API Geocoding.
Esempi di geocodifica lato client e lato server
Di seguito è riportato un esempio di geocodifica lato client che prende un indirizzo, lo geocodifica, sposta il centro della mappa in quella posizione e vi aggiunge un indicatore di mappa:
geocoder = new google.maps.Geocoder(); geocoder.geocode({ 'address': address }, function(results, status) { if (status == google.maps.GeocoderStatus.OK) { map.setCenter(results[0].geometry.location); var marker = new google.maps.Marker({ map: map, position: results[0].geometry.location }); } });
Per altri esempi, consulta la documentazione dell'API Maps JavaScript.
Ecco un esempio di utilizzo di Python per eseguire una richiesta di geocodifica lato server nell'API Geocoding v4:
import json import urllib.request address = "1600+Amphitheatre+Parkway,+Mountain+View,+CA" key = "my-key-here" url = f"https://geocode.googleapis.com/v4/geocode/address/{address}" headers = {"X-Goog-Api-Key": key} req = urllib.request.Request(url, headers=headers) with urllib.request.urlopen(req) as response: result = json.loads(response.read().decode("utf-8"))
In questo modo viene generato un oggetto JSON con i seguenti contenuti:
{ "results": [ { "place": "places/ChIJiSSC8QK6j4AR98Thup8mqTc", "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc", "location": { "latitude": 37.4224864, "longitude": -122.0855962 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.4211700197085, "longitude": -122.08691558029149 }, "high": { "latitude": 37.4238679802915, "longitude": -122.08421761970851 } }, "bounds": { "low": { "latitude": 37.4221145, "longitude": -122.0860002 }, "high": { "latitude": 37.4228775, "longitude": -122.085133 } }, "formattedAddress": "Google Building 41, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94043-1351", "administrativeArea": "CA", "locality": "Mountain View", "addressLines": [ "1600 Amphitheatre Pkwy" ] }, "addressComponents": [ { "longText": "Google Building 41", "shortText": "Google Building 41", "types": [ "premise" ], "languageCode": "en" }, { "longText": "1600", "shortText": "1600", "types": [ "street_number" ] }, { "longText": "Amphitheatre Parkway", "shortText": "Amphitheatre Pkwy", "types": [ "route" ], "languageCode": "en" }, { "longText": "Mountain View", "shortText": "Mountain View", "types": [ "locality", "political" ], "languageCode": "en" }, { "longText": "Santa Clara County", "shortText": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ], "languageCode": "en" }, { "longText": "California", "shortText": "CA", "types": [ "administrative_area_level_1", "political" ], "languageCode": "en" }, { "longText": "United States", "shortText": "US", "types": [ "country", "political" ], "languageCode": "en" }, { "longText": "94043", "shortText": "94043", "types": [ "postal_code" ] }, { "longText": "1351", "shortText": "1351", "types": [ "postal_code_suffix" ] } ], "types": [ "premise", "street_address" ] } ] }
Per altri esempi, consulta la panoramica dell'API Geocoding v4 e la guida alla geocodifica di un indirizzo.
Considerazioni su quote e costi
I costi, le quote e i limiti di frequenza della geocodifica determinano le strategie descritte in questo documento.
Costo
I limiti di quota giornaliera (QPD) non vengono utilizzati per le richieste di geocodifica. Invece, ogni richiesta di geocodifica, sia lato client tramite il browser sia lato server tramite il servizio web dell'API Geocoding, viene fatturata in base al prezzo per richiesta. Per gestire i costi di utilizzo, valuta la possibilità di gestire i limiti di utilizzo e le quote.
Limiti di frequenza
Il servizio di geocodifica è limitato a 3000 QPM (query al minuto), calcolate come somma delle query lato client e lato server.
Quando esegui richieste di geocodifica lato client a intervalli periodici, ad esempio in un'app mobile, le richieste potrebbero restituire errori se tutti gli utenti effettuano richieste contemporaneamente (ad esempio, tutti nello stesso secondo di ogni minuto). Per evitare che ciò accada, prendi in considerazione una delle seguenti opzioni:
- Introduci intervalli casuali nelle tue richieste (jitter). Assicurati che le richieste siano casuali per l'intera base utenti.
- Se sviluppi per Android, utilizza una sveglia ripetuta non esatta.
- Se sviluppi per Android, seleziona una strategia di localizzazione appropriata.
Memorizzazione nella cache
Consulta le norme dell'API Geocoding relative alla memorizzazione nella cache.
Architettura lato server e lato client nella versione 4
L'API Geocoding v4 (tra cui SearchDestinations, GeocodeAddress, GeocodeLocation e GeocodePlace) è progettata come API server-to-server. La chiamata degli endpoint v4 dal server di backend offre vantaggi fondamentali:
- Informazioni sull'arrivo iperlocali: il metodo
SearchDestinations(POST /v4/geocode/destinations) è disponibile esclusivamente utilizzando richieste REST o gRPC lato server e restituisce ingressi degli edifici, punti di navigazione instradabili, contorni degli edifici e punti di riferimento nelle vicinanze che non sono disponibili nei geocodificatori del browser lato client. - Sicurezza delle API migliorata: le chiamate lato server proteggono le chiavi API e i token OAuth dall'esposizione nei browser client. Consulta Sicurezza delle API.
- Maschere di campo di risposta: gli endpoint v4 lato server supportano le maschere di campo, consentendoti di richiedere solo i campi necessari alla tua applicazione per ridurre al minimo le dimensioni del payload e la latenza.
Quando utilizzare la ricerca nel browser lato client
Per le applicazioni browser interattive che rispondono alle pressioni dei tasti in tempo reale, valuta la possibilità di combinare Place Autocomplete lato client (per eliminare le ambiguità dell'input utente e ottenere un ID luogo) con una chiamata di backend a SearchDestinations o GeocodePlace per recuperare in modo sicuro coordinate o dettagli iperlocali.