Google 地圖平台靜態網頁 API 是 Google 服務的 HTTP 介面集合,可產生可直接嵌入網頁的圖片。
本指南將說明設定圖片要求和處理服務回應時,可用於設定的常見做法。如需 Maps Static API 的完整說明文件,請參閱開發人員指南。
什麼是 Static Web API?
Google 地圖平台靜態網頁 API 可讓您在網頁中嵌入 Google 地圖圖片,不必使用 JavaScript 或任何動態頁面載入功能。靜態網頁 API 會根據使用標準 HTTPS 要求傳送的網址參數建立圖片。一般來說,典型的 Maps Static API 要求通常會採用以下格式:
https://www.googleapis.com/staticmap/z/x/y?parameters
注意:所有 Maps Static API 應用程式都需要驗證。進一步瞭解驗證憑證。
SSL/TLS 存取權
凡是使用 API 金鑰或包含使用者資料的 Google 地圖平台要求,都必須透過 HTTPS 傳送。透過 HTTP 提出的含有機密資料要求可能會遭到拒絕。
建立有效網址
您可能認為網址是否「有效」一眼就能判斷,但實際情況不然。例如,在瀏覽器的網址列內輸入的網址可能包含特殊字元 (例如 "上海+中國"
);瀏覽器必須在內部將這些字元轉譯為其他編碼方式才能傳送。同理可證,產生或接受 UTF-8 輸入值的任何程式碼都可能會將含有 UTF-8 字元的網址視為「有效網址」,但也需要先轉譯這些字元,才能向外傳送至網路伺服器。這個過程稱為網址編碼或百分比編碼。
特殊字元
所有網址都必須符合統一資源 ID (URI) 規格指定的語法,因此我們必須轉譯特殊字元。實務上,這表示網址只能包含一部分特殊 ASCII 字元:慣用的英數字元符號,以及用做網址內控制字元的部分預留字元。下表摘要列出這些字元:
字元集 | 字元 | 網址使用情況 |
---|---|---|
英數字元 | 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 | 文字字串、結構用途 (http )、通訊埠 (8080 ) 等。 |
非預留 | - _ . ~ | 文字字串 |
預留 | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | 控制字元和 (或) 文字字串 |
建立有效網址時,您必須確認網址僅包含表格中列出的字元。如果網址使用上述字元集,通常會導致兩個問題:一個是遺漏問題,一個則是代換問題:
- 您需要處理的字元不屬於上述字元集。舉例來說,外國語言的字元 (例如「
上海+中國
」) 就需要使用上述字元加以編碼。依照普遍慣例,空格 (網址內不允許使用) 通常也用加號'+'
字元來表示。 - 字元屬於上方字元集中的預留字元,但需要直接使用。舉例來說,網址內會使用
?
來表示查詢字串的開頭;如果您想使用「? and the Mysterions」這個字串,就必須對'?'
字元進行編碼。
所有字元進行網址編碼時,都會使用 '%'
字元,外加對應至各自 UTF-8 字元的雙字元十六進位值。舉例來說,「上海+中國
」以 UTF-8 編碼形式進行網址編碼的結果是 %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B
,「? and the Mysterians
」字串則是 %3F+and+the+Mysterians
或 %3F%20and%20the%20Mysterians
。
需要編碼的常見字元
必須編碼的部分常見字元如下:
不安全的字元 | 經過編碼的值 |
---|---|
空格 | %20 |
" | %22 |
< | %3C |
> | %3E |
# | %23 |
% | %25 |
| | %7C |
將使用者輸入內容轉換成網址的過程有時會遇到困難。舉例來說,使用者輸入的地址可能是「5th&Main St.」。一般來說,您應該根據各組成部分來建立網址,並將任何使用者輸入內容當成常值字元來處理。
此外,所有 Google 地圖平台網路服務和 Static Web API 的網址長度上限都是 16, 384 個字元。對於大部分的服務而言,很少出現接近此字元限制的情況。但請注意,某些服務的幾個參數可能會產生較長的網址。