Best practice per l'utilizzo dell'API Maps 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.

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

Che cos'è un'API web statica?

Una richiesta API Maps Static tipica è in genere del seguente tipo:

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

Nota: tutte le applicazioni dell'API Maps 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.

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:

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:

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.