Best practice per l'utilizzo dell'API Street View Static

Le API web statiche di Google Maps Platform sono una raccolta di interfacce HTTP ai servizi Google che generano immagini che puoi incorporare direttamente nella tua pagina web.

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

Questa guida descrive alcune pratiche comuni utili per configurare le richieste di servizio web per le immagini e per elaborare le risposte del servizio. Consulta la guida per gli sviluppatori per la documentazione completa dell'API Street View Static.

L'API Street View Static si comporta come un'API web statica, mentre il servizio di metadata può essere considerato un servizio web. Per ulteriori informazioni sul servizio di metadati, consulta la pagina sui metadati delle immagini di Street View.

Che cos'è un'API web statica?

Le API web statiche di Google Maps Platform ti consentono di incorporare un'immagine di Google Maps nella tua pagina web senza richiedere JavaScript o il caricamento di pagine dinamiche. Le API web statiche creano un'immagine in base ai parametri URL inviati utilizzando una richiesta HTTPS standard.

Una richiesta API Street View Static tipica è generalmente del seguente tipo:

  https://www.googleapis.com/streetview/z/x/y?parameters

Che cos'è un servizio web?

I servizi web di Google Maps Platform sono un'interfaccia per richiedere i dati dell'API Maps da servizi esterni e utilizzarli nelle tue applicazioni Maps. Questi servizi sono progettati per essere utilizzati in combinazione con una mappa, come indicato nelle limitazioni della licenza dei Termini di servizio di Google Maps Platform.

I servizi web delle API Maps utilizzano richieste HTTP(S) a URL specifici, passando 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 dell'applicazione.

Una richiesta di metadati dell'API Street View Static ha il seguente formato:

https://maps.googleapis.com/maps/api/streetview/parameters

Nota: tutte le applicazioni dell'API Street View Static richiedono l'autenticazione. Scopri di più sulle credenziali di autenticazione.

Accesso SSL/TLS

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

Creazione di un URL valido

Potresti pensare che un URL "valido" sia evidente, ma non è così. Ad esempio, un URL inserito nella barra degli indirizzi di un browser può contenere caratteri speciali (ad es."上海+中國"); il browser deve tradurre internamente questi caratteri in una codifica diversa prima della trasmissione. Allo stesso modo, qualsiasi codice che genera o accetta input UTF-8 potrebbe trattare gli URL con caratteri UTF-8 come "validi", ma dovrebbe anche tradurre questi caratteri prima di inviarli a un server web. Questa procedura è chiamata codifica URL o codifica percentuale.

Attenzione: i browser e/o i servizi potrebbero eseguire automaticamente la codifica URL di un URI richiesta prima dell'invio. Nelle API che utilizzano la firma delle richieste crittografiche, questo può potenzialmente invalidare la firma, se la codifica URL altera la richiesta dopo la firma. Per evitare questo problema, codifica sempre la stringa di query prima di firmare la richiesta.

Caratteri speciali

Dobbiamo tradurre i caratteri speciali perché tutti gli URL devono essere conformi alla sintassi specificata dalla specifica Uniform Resource Identifier (URI). In pratica, questo significa che gli URL devono contenere solo un sottoinsieme speciale di caratteri ASCII: i familiari simboli alfanumerici e alcuni caratteri riservati per l'utilizzo come caratteri di controllo all'interno degli URL. Questa tabella riassume questi caratteri:

Partenza	caratteri	Utilizzo degli URL
Alfanumerico	a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9	Stringhe di testo, utilizzo dello schema (http), porta (8080) e così via.
Non prenotato	- _ . ~	Stringhe di testo
Prenotato	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	Caratteri di controllo e/o stringhe di testo

Quando crei un URL valido, devi assicurarti che contenga solo i caratteri mostrati nella tabella. In genere, l'adeguamento di un URL all'utilizzo di questo insieme di caratteri comporta due problemi, uno di omissione e uno di sostituzione:

• I caratteri che vuoi gestire esistono al di fuori dell'insieme riportato sopra. Ad esempio, i caratteri in lingue straniere come 上海+中國 devono essere codificati utilizzando i caratteri riportati sopra. Per convenzione, gli spazi (che non sono consentiti negli URL) sono spesso rappresentati anche utilizzando il carattere più '+'.
• I caratteri all'interno dell'insieme riportato sopra sono caratteri riservati, ma devono essere utilizzati in modo letterale. Ad esempio, ? viene utilizzato negli URL per indicare l'inizio della stringa di query. Se vuoi utilizzare la stringa "? e i Mysterions", devi codificare il carattere ?.'?'

Tutti i caratteri da codificare per l'URL vengono codificati utilizzando un carattere '%' e un valore esadecimale di due caratteri corrispondente al carattere UTF-8. Ad esempio,上海+中國 in UTF-8 viene codificato per l'URL come%E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. La stringa ? and the Mysterians viene codificata come URL come %3F+and+the+Mysterians o %3F%20and%20the%20Mysterians.

Caratteri comuni che richiedono la codifica

Alcuni caratteri comuni che devono essere codificati sono:

Carattere non sicuro	Valore codificato
Spazio	%20
"	%22
<	%3C
>	%3E
#	%23
%	%25
|	%7C

A volte la conversione di un URL ricevuto dall'input dell'utente può essere complicata. Ad esempio, un utente potrebbe inserire un indirizzo come "5th&Main St." In genere, devi creare l'URL dalle sue parti, trattando qualsiasi input dell'utente come caratteri letterali.

Inoltre, gli URL sono limitati a 16384 caratteri per tutti i servizi web e le API web statiche di Google Maps Platform. Per la maggior parte dei servizi, questo limite di caratteri viene raramente raggiunto. Tuttavia, tieni presente che alcuni servizi hanno diversi parametri che possono generare URL lunghi.

Utilizzo corretto delle API di Google

Client API progettati male possono generare un carico maggiore del necessario sia su internet sia sui server di Google. Questa sezione contiene alcune best practice per i client delle API. Seguire queste best practice può aiutarti a evitare il blocco della tua applicazione per uso improprio involontario delle API.

Backoff esponenziale

In rari casi, potrebbe verificarsi un problema durante l'elaborazione della richiesta. Potresti ricevere un codice di risposta HTTP 4XX o 5XX oppure la connessione TCP potrebbe non riuscire a un certo punto tra il client e il server di Google. Spesso vale la pena riprovare a inviare la richiesta, poiché la richiesta di follow-up potrebbe andare a buon fine se quella originale non è riuscita. Tuttavia, è importante non eseguire semplicemente un loop ripetuto di richieste ai server di Google. Questo comportamento di looping può sovraccaricare la rete tra il tuo client e Google, causando problemi a molte parti.

Un approccio migliore è quello di riprovare con ritardi crescenti tra un tentativo e l'altro. In genere, 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

Il seguente esempio in Python 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}")

Inoltre, assicurati che nella catena di chiamate dell'applicazione non sia presente un codice di ripetizione che porti a richieste ripetute in rapida successione.

Richieste sincronizzate

Un numero elevato di richieste sincronizzate alle API di Google può sembrare un attacco DDoS (Distributed Denial of Service) all'infrastruttura di Google ed essere trattato di conseguenza. Per evitarlo, devi assicurarti che le richieste dell'API non siano sincronizzate tra i client.

Ad esempio, considera un'applicazione che mostra l'ora nel fuso orario corrente. Questa applicazione probabilmente imposterà una sveglia nel sistema operativo del client per risvegliarlo all'inizio del minuto in modo che l'ora visualizzata possa essere aggiornata. L'applicazione non deve effettuare chiamate API nell'ambito dell'elaborazione associata all'allarme.

Eseguire chiamate API in risposta a una sveglia fissa non è consigliabile perché le chiamate API vengono sincronizzate con l'inizio del minuto, anche tra dispositivi diversi, anziché essere distribuite in modo uniforme nel tempo. Un'applicazione progettata male che esegue questa operazione produrrà un picco di traffico pari a sessantacinque volte i livelli normali all'inizio di ogni minuto.

Invece, un possibile buon design è impostare una seconda sveglia su un'ora scelta in modo casuale. Quando viene attivato questo secondo avviso, l'applicazione chiama le API di cui ha bisogno e memorizza i risultati. Quando l'applicazione vuole aggiornare la visualizzazione all'inizio del minuto, utilizza i risultati memorizzati in precedenza anziché richiamare di nuovo l'API. Con questo approccio, le chiamate API vengono distribuite uniformemente nel tempo. Inoltre, le chiamate API non ritardano il rendering durante l'aggiornamento del display.

Oltre all'inizio del minuto, altri momenti comuni di sincronizzazione che devi fare attenzione non scegliere come target sono l'inizio di un'ora e l'inizio di ogni giorno a mezzanotte.

Elaborazione delle risposte

Nota: poiché il formato esatto delle singole risposte con una richiesta di servizio web non è garantito (alcuni elementi potrebbero essere mancanti o in più posizioni), non dovresti mai presumere che il formato restituito per una determinata risposta sia lo stesso per query diverse. Devi invece elaborare la risposta e selezionare i valori appropriati tramite espressioni.

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

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

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