Best practice per l'utilizzo dei servizi web dell'API Geolocation

I servizi web di Google Maps Platform sono una raccolta di interfacce HTTP per i servizi Google che forniscono dati geografici per le applicazioni di mappe.

Questa guida descrive alcune pratiche comuni utili per configurare le richieste di servizi web ed elaborare le risposte dei servizi. Consulta la guida per gli sviluppatori per la documentazione completa sull'API Geolocation.

Che cos'è un servizio web?

I servizi web di Google Maps Platform sono un'interfaccia per richiedere i dati dell'API di Google Maps da servizi esterni e utilizzare i dati all'interno delle applicazioni Maps. Questi servizi sono progettati per essere utilizzati insieme a una mappa, in conformità alle limitazioni di licenza nei Termini di servizio di Google Maps Platform.

I servizi web delle API di Google Maps utilizzano richieste HTTP(S) a URL specifici, trasmettendo parametri URL e/o dati POST in formato JSON come argomenti ai servizi. In genere, questi servizi restituiscono i dati nel corpo della risposta come JSON per l'analisi e/o l'elaborazione da parte della tua applicazione.

Le richieste di geolocalizzazione vengono inviate tramite POST al seguente URL:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

Nota: tutte le applicazioni dell'API Geolocation richiedono l'autenticazione. Leggi ulteriori informazioni sulle credenziali di autenticazione.

Accesso SSL/TLS

HTTPS è obbligatorio per tutte le richieste di Google Maps Platform che utilizzano chiavi API o contengono dati utente. Le richieste effettuate tramite HTTP che contengono dati sensibili potrebbero essere rifiutate.

Uso educato delle API di Google

I client API mal progettati possono caricare più carico del necessario sia su Internet che sui server di Google. Questa sezione contiene alcune best practice per i client delle API. Seguendo queste best practice, puoi evitare che la tua applicazione venga bloccata per uso illecito involontario delle API.

Backoff esponenziale

In rari casi, si potrebbe verificare un errore nel soddisfare la tua richiesta: potresti ricevere un codice di risposta HTTP 4XX o 5XX oppure la connessione TCP potrebbe semplicemente non riuscire da qualche parte tra il tuo client e il server di Google. Spesso vale la pena ritentare la richiesta poiché la richiesta di follow-up potrebbe avere esito positivo quando l'originale non è andato a buon fine. Tuttavia, è importante non limitarsi a ripetere ripetutamente le richieste ai server di Google. Questo comportamento di loop può sovraccaricare la rete tra il client e Google, causando problemi a molte parti.

Un approccio migliore è riprovare con un aumento dei ritardi tra un tentativo e l'altro. Di solito il ritardo viene aumentato di un fattore moltiplicativo a ogni tentativo, un approccio noto come backoff esponenziale.

Ad esempio, considera un'applicazione che vuole effettuare questa richiesta all'API Time Zone:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

L'esempio Python seguente mostra come effettuare la richiesta con backoff esponenziale:

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay each time we retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

Devi inoltre fare attenzione a non trovare codice di nuovo tentativo più in alto nella catena di chiamate dell'applicazione che porta a richieste ripetute in rapida successione.

Richieste sincronizzate

Un numero elevato di richieste sincronizzate alle API di Google può sembrare un attacco Distributed DoS (DDoS) sull'infrastruttura di Google ed essere gestito di conseguenza. Per evitare questo problema, devi assicurarti che le richieste API non siano sincronizzate tra i client.

Ad esempio, considera un'applicazione che mostra l'ora nel fuso orario corrente. È probabile che questa applicazione imposti una sveglia nel sistema operativo client per riattivarla all'inizio dell'ora, in modo che l'ora visualizzata possa essere aggiornata. L'applicazione non deve effettuare chiamate API nell'ambito dell'elaborazione associata all'allarme.

L'esecuzione di chiamate API in risposta a un allarme fisso non è corretta, perché le chiamate API vengono sincronizzate all'inizio del minuto, anche tra dispositivi diversi, invece di essere distribuite in modo uniforme nel tempo. Un'applicazione progettata male all'inizio di ogni minuto produrrà un picco di traffico sessanta volte superiore al normale.

È consigliabile, invece, impostare una seconda sveglia su un orario scelto in modo casuale. Quando questo secondo allarme si attiva, l'applicazione chiama le API di cui ha bisogno e archivia i risultati. Se l'applicazione vuole aggiornare la visualizzazione all'inizio, utilizza i risultati archiviati in precedenza anziché chiamare di nuovo l'API. Con questo approccio, le chiamate API sono distribuite in modo uniforme nel tempo. Inoltre, le chiamate API non ritardano il rendering quando il display viene aggiornato.

A parte l'inizio del minuto, altri orari di sincronizzazione comuni che dovresti non scegliere come target sono l'inizio dell'ora e l'inizio di ogni giorno a mezzanotte.

Elaborazione risposte

Questa sezione illustra come estrarre questi valori in modo dinamico dalle risposte del servizio web.

I servizi web di Google Maps forniscono risposte facili da capire, ma non esattamente facili da usare. Quando esegui una query, anziché visualizzare un insieme di dati, probabilmente vorrai estrarre alcuni valori specifici. In genere, vorrai analizzare le risposte del servizio web ed estrarre solo i valori che ti interessano.

Lo schema di analisi utilizzato dipende dal fatto che tu restituisca l'output in JSON. Le risposte JSON, essendo già sotto forma di oggetti JavaScript, possono essere elaborate all'interno di JavaScript stesso sul client.