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 che puoi adottare per configurare le richieste di immagini e le risposte del servizio di elaborazione. Per saperne di più sull'API Maps Static, consulta la guida per gli sviluppatori.
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 delle pagine. Le API web statiche creano un'immagine in base ai parametri URL inviati utilizzando una richiesta HTTPS standard.
Una tipica richiesta dell'API Maps Static ha il seguente formato:
https://www.googleapis.com/staticmap/z/x/y?parameters
Nota: tutte le applicazioni API Maps Static richiedono l'autenticazione. Per saperne di più, consulta Credenziali di autenticazione.
Accesso 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.
Creare un URL valido
Potresti pensare che un URL "valido" sia ovvio, ma
non è proprio così. Un URL inserito in una barra degli indirizzi di un browser, ad esempio, 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 considerare 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). Ciò significa che gli URL devono contenere solo un sottoinsieme speciale di caratteri ASCII: i familiari simboli alfanumerici e alcuni caratteri riservati da utilizzare come caratteri di controllo all'interno degli URL. Questa tabella riassume questi caratteri:
| Configurato | 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 |
| Prenotate | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | Caratteri di controllo e/o stringhe di testo |
Quando crei un URL valido, devi assicurarti che contenga solo i caratteri mostrati nella tabella. L'adeguamento 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
indicato sopra. 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 con codifica URL vengono codificati
utilizzando un carattere '%' e un valore esadecimale di due caratteri
corrispondente al carattere UTF-8. Ad esempio,
上海+中國 in UTF-8 sarebbe codificato come URL come
%E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. La
stringa ? and the Mysterians verrebbe codificata come URL
%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 costruire 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 di Google Maps Platform e le API web statiche. Per la maggior parte dei servizi, questo limite di caratteri viene raramente raggiunto. Tuttavia, tieni presente che alcuni servizi hanno diversi parametri che potrebbero generare URL lunghi.