Le API web statiche di Google Maps Platform sono una raccolta di interfacce HTTP di servizi Google che generano immagini da incorporare direttamente nella tua pagina web.
Questa guida descrive alcune pratiche comuni utili per configurare le richieste di immagine ed elaborare le risposte dei servizi. Consulta la guida per gli sviluppatori per la documentazione completa dell'API Maps Static.
Che cos'è un'API Static Web?
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 alcun caricamento dinamico della pagina. Le API web statiche creano un'immagine basata su parametri URL che vengono inviati utilizzando una richiesta HTTPS standard.Una tipica richiesta all'API Maps Static ha in genere il seguente formato:
https://www.googleapis.com/staticmap/z/x/y?parameters
Nota: tutte le applicazioni API Maps Static richiedono l'autenticazione. Leggi ulteriori informazioni sulle credenziali di autenticazione.
Accesso SSL/TLS
HTTPS è richiesto 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
Puoi pensare che un URL "valido" sia ovvio, ma
non è 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.
Per lo stesso token, qualsiasi codice che genera o accetta input UTF-8 potrebbe trattare come "validi" gli URL con caratteri UTF-8, ma dovrebbe anche tradurli prima di inviarli a un server web.
Questo processo è noto come
codifica degli 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, ovvero i simboli alfanumerici familiari, e alcuni caratteri riservati da utilizzare come caratteri di controllo all'interno degli URL. In questa tabella sono riepilogati questi caratteri:
| Configura | personaggi | Utilizzo dell'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 | Stringhe di testo, utilizzo dello schema (http), porta (8080) e così via. |
| Non prenotato | - _ ~ | Stringhe di testo |
| Riservata | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | Caratteri di controllo e/o stringhe di testo |
Quando crei un URL valido, devi assicurarti che contenga solo i caratteri visualizzati nella tabella. La conformità di un URL per l'utilizzo di questo set di caratteri in genere causa due problemi, uno di omissione e uno di sostituzione:
- I caratteri che vuoi gestire non rientrano nel set riportato sopra. Ad esempio, i caratteri in lingue straniere
come
上海+中國devono essere codificati utilizzando i caratteri precedenti. Secondo le convenzioni più diffuse, gli spazi (che non sono consentiti all'interno degli URL) vengono spesso rappresentati utilizzando anche il carattere'+'. - I caratteri esistono all'interno del set precedente come caratteri riservati, ma devono essere utilizzati letteralmente.
Ad esempio,
?viene utilizzato all'interno degli 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 nell'URL vengono codificati utilizzando un carattere '%' e un valore esadecimale di due caratteri corrispondenti al carattere UTF-8. Ad esempio,
上海+中國 in UTF-8 verrebbe codificato nell'URL
%E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. La
stringa ? and the Mysterians avrebbe la codifica 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 |
A volte la conversione di un URL ricevuto dall'input dell'utente è complessa. Ad esempio, un utente potrebbe inserire l'indirizzo"Via Roma 12". In genere, devi generare l'URL dalle sue parti, trattando qualsiasi input utente come caratteri letterali.
Inoltre, gli URL hanno un limite di 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 viene raramente raggiunto. Tuttavia, tieni presente che alcuni servizi hanno diversi parametri che possono generare URL lunghi.