使用 Maps Static API 的最佳做法

Google 地圖平台靜態 Web API 是 Google 服務的一組 HTTP 介面,這些介面會產生可直接嵌入網頁的圖片。

本指南說明設定映像檔要求和處理服務回應的一些常見做法。如需 Maps Static API 的完整說明文件,請參閱開發人員指南

什麼是 Static Web API?

Google 地圖平台靜態網路 API 可讓您在網頁中嵌入 Google 地圖圖片,完全無需 JavaScript 或任何動態頁面載入。靜態 Web 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 的網址長度上限都是 16384 個字元。對於大部分的服務而言,很少出現接近此字元限制的情況。但請注意,某些服務的幾個參數可能會產生較長的網址。