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

Le API web statiche di Google Maps Platform, una raccolta di interfacce HTTP, generano immagini da incorporare direttamente nella tua pagina web.

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

Questa guida descrive alcune pratiche comuni utili per configurare le richieste di immagini e servizi web ed elaborare le risposte dei servizi. Per ulteriori informazioni sull'API Street View Static, consulta la guida per gli sviluppatori.

L'API Street View Static agisce come un'API web statica, mentre il servizio di metadati agisce come un servizio web. Per saperne di più sul servizio di metadati, consulta 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 dinamico della pagina. Le API web statiche creano un'immagine in base ai parametri URL inviati utilizzando una richiesta HTTPS standard.

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

  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 di Google Maps da servizi esterni e utilizzarli nelle tue applicazioni Maps. Questi servizi sono progettati per essere utilizzati insieme a una mappa, in conformità alle Limitazioni della licenza dei Termini di servizio di Google Maps Platform.

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

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

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

Accesso SSL e TLS

Il protocollo 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.

Creazione di un URL valido

Potresti pensare che un URL "valido" sia evidente, ma non è proprio 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. Questo processo è chiamato codifica URL o codifica percentuale.

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, ciò significa che gli URL devono contenere solo un sottoinsieme speciale di caratteri ASCII: i simboli alfanumerici familiari e alcuni caratteri riservati da utilizzare come caratteri di controllo all'interno degli URL. Questa tabella riassume questi caratteri:

Riepilogo dei caratteri validi per gli URL
ConfiguratocaratteriUtilizzo 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
Prenotate ! * ' ( ) ; : @ & = + $ , / ? % # [ ] Caratteri di controllo e/o stringhe di testo

Quando crei un URL valido, devi assicurarti che contenga solo i caratteri mostrati nella tabella. La conformità di un URL all'utilizzo di questo insieme di caratteri generalmente comporta due problemi, uno di omissione e uno di sostituzione:

  • I caratteri che vuoi gestire non rientrano nel set precedente. Ad esempio, i caratteri in lingue straniere come 上海+中國 devono essere codificati utilizzando i caratteri sopra indicati. Per convenzione, gli spazi (che non sono consentiti negli URL) vengono spesso rappresentati anche utilizzando il carattere più '+'.
  • I caratteri esistono all'interno del set precedente come caratteri riservati, ma devono essere utilizzati letteralmente. Ad esempio, ? viene utilizzato negli URL per indicare l'inizio della stringa di query; se vuoi utilizzare la stringa "? and the Mysterions", devi codificare il carattere '?'.

Tutti i caratteri da codificare nell'URL vengono codificati utilizzando un carattere '%' e un valore esadecimale di due caratteri corrispondente al relativo carattere UTF-8. Ad esempio, 上海+中國 in UTF-8 verrebbe codificato nell'URL come %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. La stringa ? and the Mysterians verrebbe 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

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

Inoltre, gli URL sono limitati a 16.384 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 verrà raggiunto raramente. Tuttavia, tieni presente che alcuni servizi hanno diversi parametri che possono generare URL lunghi.

Utilizzo corretto delle API di Google

I client API progettati male possono generare carichi pesanti su internet e sui server. Questa sezione contiene le best practice per i client API. Seguire queste best practice può aiutarti a evitare che la tua applicazione venga bloccata per un abuso involontario delle API.

Backoff esponenziale

In rari casi, potrebbe verificarsi un problema con la richiesta; potresti ricevere un codice di risposta HTTP 4xx o 5xx oppure la connessione TCP potrebbe non riuscire tra il client e il server di Google. Spesso vale la pena riprovare la richiesta perché la richiesta successiva potrebbe riuscire anche se quella originale non è andata a buon fine. Tuttavia, è importante non inviare ripetutamente richieste ai server di Google. Questo comportamento di loop può sovraccaricare la rete tra il tuo client e Google, causando problemi a molte parti.

Un approccio migliore consiste nel riprovare con ritardi crescenti tra un tentativo e l'altro. In genere, il ritardo aumenta di un fattore moltiplicativo a ogni tentativo, un approccio noto come backoff esponenziale.

Ad esempio, considera un'applicazione che invia 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 in the following code 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 the request didn't produce an IOError, parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors can't be fixed by a retry, such as
                # INVALID_REQUEST or ZERO_RESULTS. Don't retry 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 on each retry.


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

Assicurati che non sia presente un codice di ripetizione 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 denial of service (DDoS) all'infrastruttura di Google e venire trattato di conseguenza. Per evitare questo problema, assicurati che le richieste API non siano sincronizzate tra i client.

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

Effettuare chiamate API in risposta a una sveglia fissa non è una buona idea 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 genera un picco di traffico 60 volte superiore ai livelli normali all'inizio di ogni minuto.

In alternativa, puoi progettare l'applicazione in modo che abbia una seconda sveglia impostata su un'ora scelta in modo casuale. Quando viene attivato questo secondo allarme, l'applicazione chiama le API di cui ha bisogno e memorizza i risultati. Quando l'applicazione aggiorna la visualizzazione all'inizio del minuto, utilizza i risultati memorizzati in precedenza anziché chiamare nuovamente l'API. Con questo approccio, le chiamate API vengono distribuite in modo uniforme nel tempo. Inoltre, le chiamate API non ritardano il rendering quando il display si aggiorna.

Oltre all'inizio del minuto, non scegliere come target altri orari di sincronizzazione comuni, come l'inizio di un'ora e l'inizio di ogni giorno a mezzanotte.

Elaborazione delle risposte

Poiché il formato esatto delle singole risposte a una richiesta di servizio web non è garantito (alcuni elementi potrebbero mancare o trovarsi in più posizioni), non dare per scontato che il formato restituito per una determinata risposta sia lo stesso per query diverse. Invece, elabora la risposta e seleziona i valori appropriati utilizzando le espressioni.

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

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

Lo schema di analisi che utilizzi dipende dal fatto che l'output venga restituito o meno in formato JSON. Le risposte JSON, essendo già sotto forma di oggetti JavaScript, possono essere elaborate all'interno di JavaScript stesso sul client.