Google Static Maps 開發人員指南

Google Static Maps API 可讓您在不需要使用 JavaScript 或任何動態頁面載入功能的情況下，將「Google 地圖」影像內嵌在您的網頁。Google Static Maps API 服務會根據透過標準 HTTP 要求傳送的 URL 參數來建立您的地圖，並以可以在網頁上顯示之影像的形式傳回地圖。

注意：Google Static Maps API 的使用限制已經變更。建立 API 金鑰並將它包括在您的要求中，可讓您在 Google Developers Console 中追蹤使用量，以及視需要購買額外配額。

此文件提供 Google Static Maps API v2 的詳細資料。如果要更新您的 v1 URL，請參考升級指南。

快速範例

下列範例包含紐約市市區之 Google Static Maps API 影像的 URL，顯示如下：

https://maps.googleapis.com/maps/api/staticmap?center=Brooklyn+Bridge,New+York,NY&zoom=13&size=600x300&maptype=roadmap
&markers=color:blue%7Clabel:S%7C40.702147,-74.015794&markers=color:green%7Clabel:G%7C40.711614,-74.012318
&markers=color:red%7Clabel:C%7C40.718217,-73.998284
&key=YOUR_API_KEY

曼哈頓下城的搜尋點

請注意，您不需要透過任何「特殊」的方式來讓這個影像在頁面上顯示。不需要使用 JavaScript。我們只需要建立 URL，並將它放置在 <img> 標籤內。您可以將 Google Google Static Maps API 放置在網頁上可以放置影像的任何位置。

目標對象

本文件的適用對象是，想要在網頁或行動裝置應用程式內包括 Google Static Maps API 影像的網站與行動應用程式開發人員。它提供使用 API 的簡介和可用參數的參考資料。

總覽

Google Static Maps API 會傳回影像 (可以是 GIF、PNG 或 JPEG)，做為對透過 URL 傳送之 HTTP 要求的回應。針對每個要求，您可以指定地圖位置、影像大小、縮放層級、地圖類型，以及在地圖上的位置放置選擇性標記。您可以進一步使用英數字元為您的標記新增標籤。

Google Static Maps API 影像已內嵌於 <img> 標籤的 src 屬性內，或是於其他程式設計語言中與其相當的屬性內。如果 Google Static Maps API 影像被用於 Web 應用程式 (例如瀏覽器) 之外，則必須包含一個指向網頁瀏覽器或原生「Google 地圖」應用程式中之顯示位置的連結。(Google Maps API for Work 使用者已放棄此需求)。請參考 Google 地圖/Google 地球之服務條款的第 10.1.1(h) 節，以取得與此需求有關的完整與最新語言。

此文件說明 Google Static Maps API URL 和可用參數的必要格式。它也提供一些指定 URL 的祕訣與技巧。

URL 參數

Google Static Maps API URL 必須是下列格式：

https://maps.googleapis.com/maps/api/staticmap?parameters

如果您的網站是透過 HTTPS 存取，您也必須經由 HTTPS 載入 Google Static Maps API 影像，以避免瀏覽器安全性警示。如果您的要求包括敏感使用者資訊 (例如使用者的位置)，也建議使用 HTTPS。

https://maps.googleapis.com/maps/api/staticmap?parameters

注意：Google Static Maps API 並不支援使用 HTTPS 的自訂圖示 URL；在這種情況下，將會顯示預設圖示。

無論是使用 HTTP 或 HTTPS，特定 URL 參數是必要的，而某些則是選擇性。根據 URL 標準，所有參數都使用 & 字元來分隔。參數清單與其可能值列舉如下。

重要：下方針對 URL 參數的討論，為了使說明能夠明確易懂，將針對範例提供其預先逸出的格式。在將任何要求傳送至 API 之前，應該對它的參數進行正確的 URL 編碼。例如，有許多參數都使用縱線字元 (|) 做為分隔符號，而這種符號在最終的 URL 中應該編碼為 %7C，如本文件一開始的快速範例中所示。如需詳細資訊，請參閱建置有效的 URL。

Google Static Maps API 使用下列 URL 參數來定義地圖影像：

位置參數

  • center (在沒有標記的情況下為「必要」) 會定義地圖中心，與地圖所有邊緣的距離都相同。此參數可接受能識別地球表面上唯一位置，格式為以逗號分隔之 {latitude,longitude} 組合 (例如「40.714728,-73.998672」) 或是字串地址 (例如「city hall, new york, ny」) 的位置。如需詳細資訊，請參閱下方的位置。
  • zoom (在標記不存在的情況下為「必要」) 定義地圖的縮放層級，這能決定地圖放大的層級。此參數可接受與所需地區之縮放層級相對應的數值。如需詳細資訊，請參閱下方的縮放層級。

地圖參數

  • size (「必要」) 定義地圖影像的矩形維度。這個參數可接受 {horizontal_value}x{vertical_value} 格式的字串。例如，500x400 將定義一個寬度為 500 像素、高度為 400 像素的地圖。寬度小於 180 像素的地圖將會顯示縮小的 Google 標誌。這個參數受到 scale 參數的影響 (於下方描述)；最終輸出大小是 size 與 scale 值的乘積。
  • scale (「選擇性」) 會影響傳回的像素數目。scale=2 所傳回的像素為 scale=1 的兩倍，但會維持相同的涵蓋區域和細節層級 (換句話說，地圖的內容沒有變更)。這對於開發高解析度顯示，或是產生以列印為目的之地圖而言相當實用。預設值為 1。可接受的值為 2 與 4 (4 僅供 Google Maps API for Work 客戶使用)。如需詳細資訊，請參閱 Scale 值。
  • format (「選擇性」) 定義結果影像的格式。根據預設，Google Static Maps API 會建立 PNG 影像。有數種可能的格式，包括 GIF、JPEG 與 PNG 類型。您使用的格式，取決於您想要呈現該影像的方式。JPEG 通常能提供較高的壓縮率，而 GIF 和 PNG 則提供較佳的細緻度。如需詳細資訊，請參閱影像格式。
  • maptype (「選擇性」) 定義要建構之地圖的類型。有數種可能的 maptype 值，包括 roadmap、satellite、hybrid 與 terrain。如需詳細資訊，請參閱下方的 Google Static Maps API Maptypes。
  • language (「選擇性」) 定義用於顯示地圖方塊標籤的語言。請注意，只有某些國家/地區的地圖方塊才支援此參數，如地圖方塊集不支援要求的特定語言，將會使用該地圖方塊集預設語言。
  • region (「選擇性」) 會根據地緣政治敏感度，定義要顯示的適當邊界。接受以兩個字元的 ccTLD (「頂層地區」) 值方式所指定的地區代碼。

特徵參數

  • markers (「選擇性」) 定義一或多個要在指定位置附加至影像的標記。這個參數可接受單一標記定義，其參數以縱線字元 (|) 分隔。同一個 markers 參數內可以放置多個展示相同樣式的標記；您也可以透過新增其他 markers 參數，以新增其他展示不同樣式的標記。請注意，如果您為地圖提供標記，便不需要指定 (通常需要指定) center 與 zoom 參數。如需詳細資訊，請參閱下方的 Google Static Maps API 標記。
  • path (「選擇性」) 定義兩個或更多連結點的單一路徑，以疊加在指定位置的影像上。這個參數可接受以縱線字元 (|) 分隔的點定義字串。您可以透過新增其他 path 參數以提供其他路徑。請注意，如果您為地圖提供路徑，便不需要指定 (通常需要指定) center 與 zoom 參數。如需詳細資訊，請參閱下方的 Google Static Maps API 路徑。
  • visible (「選擇性」) 指定必須在地圖上保持可見的一個或更多 位置，不過這並不會顯示標記或其他指標。使用這個參數可確保特定特徵或地圖位置會在 Google Static Maps API 上顯示。
  • style (「選擇性」) 定義自訂樣式以改變地圖上指定特徵 (例如道路、公園等) 的呈現方式。這個參數可接受能識別要選取之特徵的 feature 與 element 引數，以及要套用至該選取項目的樣式操作集。您可以透過新增其他 style 參數以提供多個樣式。如需詳細資訊，請參閱下方的樣式化地圖。

金鑰與簽章參數

  • key (「必要」) 可讓您在 Google Developers Console 中監視應用程式的 API 使用狀況、啟用以個別金鑰 (而非以個別 IP 位址) 為基礎的配額限制，以及確保 Google 可以在必要時就您的應用程式相關問題與您聯絡。如需詳細資訊，請參閱取得金鑰與簽章。
  • signature (建議) 是一個數位簽章，它是用來驗證使用您的 API 金鑰產生要求的所有網站，是否擁有正確的授權。如需詳細資訊，請參閱取得金鑰與簽章。

Google Maps API for Work 使用者必須在要求中包括有效的 client 與 signature 參數。如需詳細資訊，請參閱 Google Maps API for Work 驗證與授權一章。

URL 大小限制

Google Static Maps API URL 有 2048 個字元的大小限制。您在實際操作時應該不需要用到超過此限制的 URL，除非您會產生擁有大量標記與路徑的複雜地圖。不過，請注意特定字元在傳送至 API 之前，可能會因為瀏覽器和/或服務所執行的 URL 編碼動作，導致產生較多的字元。如需詳細資訊，請參閱建置有效的 URL。

參數用法

Google Static Maps API 相對來說較易於使用，因為它只包含一個參數化的 URL。本節將解釋如何使用這些參數來建構您的 URL。

指定位置

Google Static Maps API 必須要能準確地識別地圖上的位置，以同時將焦點放在地圖上正確的位置 (透過 center 參數) 和/或在地圖上的位置放置任何選用的地點標記 (透過 markers 參數)。Google Static Maps API 使用數字 (緯度與經度值) 或字串 (地址) 來指定這些位置。這些值能夠識別一個「地理編碼」的位置。

有數個參數 (例如 markers 與 path 標記) 可接受多個位置。在這些情況下，位置將以縱線字元 (|) 分隔。

緯度與經度

緯度與經度是以使用逗號分隔之文字字串內的數字 (準確度為小數點後 6 位數) 來定義。例如，「40.714728,-73.998672」就是一個有效的地理編碼值。位於小數點後 6 位數之後的準確度值將被忽略。

經度值是根據它們與定義本初子午線的英國格林威治之間的距離。由於格林威治位於緯度 51.477222 的位置，因此我們可以透過輸入 51.477222,0 的 center 值，以將地圖置中於格林威治：

英國格林威治

緯度與經度值必須對應到地球表面上的有效位置。緯度值可以介於 -90 到 90 之間，而經度值可以介於 -180 到 180 之間。如果您指定無效的緯度或經度值，您的要求將被視為無效要求而被拒絕。

地址

由於大多數的人都無法判讀緯度與經度，因此他們會使用「地址」來表示位置。將地址轉換為地理位置的程序稱為「地理編碼」，而 Google Static Maps API 服務可以為您所提供的有效地址進行地理編碼。

針對任何可以提供緯度/經度的參數，您可以改為指定一個表示「地址」的字串。Google 將會對該地址進行地理編碼，並向 Google Static Maps API 服務提供緯度/經度值，以用來放置標記或指定位置。字串應該進行 URL 逸出，例如像是「City Hall, New York, NY」的地址，應該要轉換為「City+Hall,New+York,NY」。

請注意，地址可能會反映出準確的位置 (例如街道地址)、折線 (例如具名路線)，或是多邊形區域 (例如城市、國家/地區或國家公園)。針對折線與多邊形的結果，Google Static Maps API 伺服器將會使用該線條/區域的中心點做為地址中心。如果您對於地址進行地理編碼的方式有疑問，可以使用這個地理編碼公用程式來測試該地址。

下列範例將為加州柏克萊產生一個 Google Static Maps API：

https://maps.googleapis.com/maps/api/staticmap?center=Berkeley,CA&zoom=14&size=400x400&key=YOUR_API_KEY

加州柏克萊

縮放層級

「Google 地圖」上的地圖都有整數的「縮放層級」，它定義目前檢視的解析度。介於 0 (最低縮放層級，整個世界都會顯示在地圖上) 與 21+ (放大至街道與個別建築物) 的縮放層級都可以在預設的 roadmap 檢視中顯示。建築物的輪廓，在可用的情形下將會以約為 17 的縮放層級顯示在地圖上。這個值會視區域而異，也會因應數據的進化而隨時間改變。

「Google 地圖」將縮放層級 0 設定為能夠涵蓋整個地球。之後的每一個縮放層級，都會將水平與垂直維度的準確度提升兩倍。如需更多有關此工作是如何完成的資訊，請參閱 Google Maps JavaScript API 文件。

注意：地球上並非所有位置都可以使用所有的縮放層級。由於地球上個別位置的資料細微度不同，因此縮放層級將會視位置而異。

如果您傳送了一個沒有可用地圖方塊之縮放層級的要求，Google Static Maps API 將會傳回一個顯示該位置最大縮放層級的地圖。

下列範例要求兩個具有相同 center 值的曼哈頓地圖，但個別的縮放層級則為 12 與 14：

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=YOUR_API_KEY

遙遠的曼哈頓  近距離的曼哈頓

影像大小

搭配 center 使用的 size 參數，定義地圖的涵蓋區域。當它透過 scale 值 (預設為 1) 倍增後，也能定義地圖的輸出大小 (以像素為單位)。

下列表格顯示 size 參數於每個 scale 值的最大允許值。

API scale=1 scale=2 scale=4
免費 640x640 640x640 (傳回 1280x1280 像素) 無法使用。
Google Maps API for Work 2048x2048 1024x1024 (傳回 2048x2048 像素) 512x512 (傳回 2048x2048 像素)

下列範例要求位於赤道的縮放層級 1 地球片段：

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=400x50&key=YOUR_API_KEY

赤道

下列範例要求位於相同區域，大小為 100 x 100 像素的小型地圖。請注意到較小的 Google 標誌：

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=100x100&key=YOUR_API_KEY

小型赤道地圖

Scale 值

Google Static Maps API 的 size 參數以像素為單位定義地圖的大小，因此 size=200x200 的地圖將會以 200 像素乘以 200 像素的形式傳回。在一個每英寸像素 (ppi) 值大約為 100 的 LCD 電腦螢幕上，一個 200x200 地圖的每一維度皆大約為 2 英寸。

不過，有越來越多的行動裝置包含了像素密度超過 300ppi 的高解析度螢幕，這將會：

  • 使 200x200 像素影像的大小降低至 0.7 英寸，並造成標籤與圖示太小而無法辨識；或是
  • 對影像做出縮放 (放大/縮小) 以提升可讀性，並造成模糊或像素化的影像。
太小 太模糊

針對行動裝置進行開發時，請使用 API 的 scale 參數來傳回可解決上述問題的較高解析度地圖影像。透過將 scale 值乘以 size，便能在不變更地圖的涵蓋區域下，判斷影像的實際輸出大小 (以像素為單位)。(預設的 scale 值為 1；可接受的值為 1、2，以及 (僅適用於 Google Maps API for Work 客戶) 4)。

例如，scale 值為 2 時將會傳回與要求相同，且沒有指定 scale 的地圖涵蓋區域，但其每一維度都會擁有兩倍的像素。這也包括道路與標籤，並使它們可以在高解析度、小尺寸螢幕，以及由瀏覽器拓展的情況下也可以判讀。

150x150 150x150&scale=2

在使用 CSS 設定高度與寬度，並插入 img 或 div 標籤後，這種影像也能在電腦瀏覽器上運作良好。瀏覽器會在不影響品質的情況下，把該影像的大小向下調整至正確的大小。

下列表格顯示三種不同的影像要求。

  • 第一個是針對沒有指定 scale 值的 100x100 影像。雖然它能在電腦上正確顯示，對於行動裝置來說卻太小而無法閱讀。
  • 第二個將使地圖大小變成兩倍。在桌面上時，CSS 會將它調整至指定的 100x100 img 元素，但在向下調整影像大小ˋ的過程中，道路與標籤將會變得太小。雖然該影像的大小對於行動裝置而言是適合的，但道路與標籤卻如上面所述而難以辨識。
  • 第三個要求是針對 100x100 的地圖，並包含 scale=2。該影像於傳回時將包含 200px 的詳細資料；電腦能完美地向下調整該影像，使它與原始的 100x100 要求之間毫無差異，而行動裝置則能夠利用由 API 傳回的額外解析度。
裝置 100x100 200x200 100x100&scale=2
電腦
(在 img 標籤上擁有
height="100px" 與
width="100px")
高解析度
(模擬)

祕訣：行動裝置平台 (例如 Android 與 iOS) 透過針對每一解析度指定個別影像，來使應用程式能夠支援高解析度螢幕。Scale 參數可讓您透過設定 scale=1 與 scale=2，輕鬆地要求兩個相同的地圖影像，一個適用於標準解析度螢幕，另一個則適用於高解析度螢幕。

如需更多針對行動裝置與高解析度螢幕進行開發的資訊，建議您閱讀下列文章：

影像格式

影像能以數種常見的 Web 圖形格式傳回：GIF、JPEG 與 PNG。format 參數可接受下列其中一個值：

  • png8 或 png (預設) 指定 8 位元 PNG 格式。
  • png32 指定 32 位元 PNG 格式。
  • gif 指定 GIF 格式。
  • jpg 指定 JPEG 壓縮格式。
  • jpg-baseline 指定非漸進式 JPEG 壓縮格式。

jpg 與 jpg-baseline 通常能夠提供最小的影像大小，不過這也使它們的壓縮方式較容易「失真」，並有可能降低影像的品質。gif、png8 與 png32 都能提供無損壓縮。

大多數的 JPEG 影像皆為漸進式，這代表它們會預先載入較為粗糙的影像，並隨著資料的增加而提升影像解析度。這能讓影像迅速地在網頁上載入，這也是目前 JPEG 最普遍的用途。不過，某些 JPEG 的用途 (特別是在印刷上) 需要使用非漸進式 (基準式) 的影像。在這種情況下，便需要使用非漸進式的 jpg-baseline 格式。

地圖類型

Google Static Maps API 能建立數種格式的地圖，如下所示：

  • roadmap (預設) 指定標準道路圖影像，這是「Google 地圖」網站上通常會顯示的地圖格式。如果沒有指定 maptype 值，則 Google Static Maps API 預設會提供 roadmap 地圖方塊。
  • satellite 會指定衛星影像。
  • terrain 會指定實際地勢圖影像，並顯示地形與植被。
  • hybrid 會指定衛星與道路圖影像的整合影像，並會在衛星影像上顯示一層透明的主要街道與地點名稱。

您可以在下列程式碼範例中看見道路圖與地形類型之間的差異。

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=roadmap&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=YOUR_API_KEY

曼哈頓標準地圖  曼哈頓地形地圖

混合地圖會使用衛星影像與主要道路圖特徵來建立組合地圖。下列範例顯示衛星與混合地圖類型：

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=hybrid&key=YOUR_API_KEY

曼哈頓衛星地圖  曼哈頓地形地圖

樣式化地圖

樣式化地圖可讓您自訂標準 Google 地圖樣式的呈現方式，變更這類元素 (道路、公園、建地區域) 的視覺顯示，以反映出有別於預設地圖類型的不同樣式。這些元件被稱為「特徵」，而樣式化地圖可讓您選取這些特徵，並將視覺樣式套用到它們的顯示上 (包括將它們完全隱藏)。透過這些變更，便可以使地圖在周圍頁面內強調特定元件或補足內容。

自訂的「樣式化」地圖包含一個或多個指定樣式，每一個樣式都是透過 Google Static Maps API 要求 URL 內的 style 參數所指出。其他樣式是透過傳遞其他 style 參數來指定。樣式包含了一個「選取項目」，以及一個套用該選取項目的「規則」集。規則指出該套用至選取項目的視覺修改。

每個 style 宣告都包含下列引數，並於 style 宣告內以縱線 (「|」) 字元分隔。

  • feature (選擇性) 指出針對此樣式修改應該選取的特徵。(請參閱下方的地圖特徵)。如果沒有傳遞任何 feature 引數，便會選取所有特徵。
  • element (選擇性) 可指示要選取之已選取特徵的子集。(請參閱下方的地圖元素)。如果沒有傳遞任何 element 引數，便會選取該特徵的所有元素。
  • 下列任一引數都指出要套用至上述選取項目的「規則」。所有規則都會按照它們在 style 宣告內出現的順序套用。(請參閱下方的樣式規則)。只要符合 Google Static Maps API 的標準 URL 長度限制條件，樣式選取項目之後可以跟隨任意數目的規則。

注意：style 宣告必須依照表明的順序指定上述引數。例如，擁有兩個規則的特徵選取項目將會以下列方式顯示：

style=feature:featureArgument|element:elementArgument|rule1:rule1Argument|rule2:rule2Argument

地圖特徵

地圖包含一組「特徵」，如道路或公園。特徵類型會形成一個類別樹狀結構，根類別則是 feature:all。某些常見的特徵列示如下：

  • feature:all (預設) 會選取地圖的所有特徵。
  • feature:road 會選取地圖上的所有道路。
  • feature:landscape 會選取地圖上的所有背景景色，這通常是道路之間的區域。在城市中，景色通常由建地區域所構成。

地圖內可選特徵的完整清單記錄在 Google Maps JavaScript API 參考資料中。

某些特徵類型類別包含使用點標記法 (例如，landscape.natural 或 road.local) 指定的子類別。如果指定上層特徵 (例如 road)，則套用到此選項的樣式也會套用到所有道路上 (包括子類別)。

地圖特徵元素

此外，地圖上有些特徵通常是由不同的「元素」所構成。例如，道路不僅包含地圖上的圖形線條 (幾何形狀)，也包含附加於地圖、指示其名稱的文字 (標籤)。選取特徵內元素的方法，是透過宣告 element 引數。支援的元素引數值如下：

  • element:all (預設) 會選取該特徵的所有元素。
  • element:geometry 只會選取該特徵的幾何元素。
  • element:labels 只會選取與該特徵關聯的文字標籤。

如果沒有傳遞任何 element 引數，便會將樣式套用至該特徵的所有元素 (無論元素類型為何)。

下列 style 宣告會選取所有當地道路的標籤：

style=feature:road.local|element:labels

樣式規則

樣式規則為套用至在每個 style 宣告中指定之特徵與元素的格式選項。每一 style 宣告都必須包含一或多個操作，使用縱線 (「|」) 字元來分隔。每個操作都使用冒號 (「:」) 字元來指定其引數值，而所有操作都以其指定順序套用至選取項目。

目前支援下列操作引數，以及它們可接受的值：

  • hue (0xRRGGBB 格式的 RGB 十六進位字串) 可指出套用至選取項目的基本色彩。(* 請參閱下方的使用注意事項。)
  • lightness (介於 -100 到 100 之間的浮點數值) 指出元素亮度的百分比變更。負值會降低亮度 (其中 -100 指定黑色)，而正值會提高亮度 (其中 +100 指定白色)。
  • saturation (介於 -100 到 100 之間的浮點數值) 指出套用到元素之基本色彩濃度的百分比變更。
  • gamma (介於 0.01 到 10.0 之間的浮點數值，其中 1.0 表示不套用校正) 指出套用到元素的色差補正校正數目。色差補正以非直線性方式修改色調的光度，同時不影響白色或黑色值。色差補正通常用來修改多個元素的對比。例如，您可以修改色差補正來提高或降低元素邊緣和內部兩者的對比。低色差補正值 (< 1) 會提高對比，而高色差補正值 (> 1) 會降低對比。
  • inverse_lightness:true 會反轉現有的光度。
  • visibility (on、off 或 simplified) 指出地圖上是否顯示元素，以及其顯示方式。visibility:simplified 指出地圖應該針對適合的元素簡化其表現方式。(例如，簡化的道路架構可能會顯示較少道路。)

樣式規則必須以獨立且獨特之操作的形式套用，並按照在 style 宣告內出現的順序套用。順序很重要，因為某些操作不能相互交換。透過樣式操作修改的特徵和/或元素 (通常) 已經有現有樣式，而操作會針對這些現有樣式 (如果有的話) 執行。

請注意，我們使用色調、飽和度、光度 (HSL) 模型，指示樣式工具操作內的色彩。這些定義色彩的操作在圖形設計中很常見。「色調」指出基本色彩，「飽和度」指出該色彩的濃度，「光度」指出構色中白色或黑色的相對數目。全部的三個 HSL 值都可以對應到 RGB 值 (反之亦然)。色差補正可以在色彩空間上修改飽和度，這通常是用來提高或降低對比。此外，HSL 模型能在座標空間內定義顏色，其中 hue 指出色彩轉輪內的方向，而飽和度與光度則指出不同軸上的增幅。色調是在 RGB 色彩空間內進行測量，這個色彩空間與大多數的 RGB 色彩空間類似，唯一的差別在於缺少白色與黑色的色度。

RGB 色彩轉輪

注意：雖然 hue 使用 RGB 十六進位色彩值，但是它只使用此值來決定基本色彩 (它在色彩轉輪上的方向)，而不能決定飽和度或光度 (會隨著百分比的變更而獨立指示)。例如，純綠色的色調可以被定義為 hue:0x00ff00 或 hue:0x000100，這兩個色調會一模一樣。(兩個值都能指向 HSL 色彩ˋ模型上的純綠色)。RGB hue 值包含相等的紅色、綠色和藍色，例如 hue:0x0000000 (黑色) 和 hue:0xffffff (白色) 以及純灰色階，但是這些值不表示色調，也不表示 HSL 座標空間中的方向。如果要指出黑色、白色或灰色，您必須移除所有 saturation (新增 saturation:-100 操作) 並改為調整 lightness。

此外，修改已經有色彩配置的現有特徵時，變更 hue 之類的值並不會變更色彩的現有 saturation 或 lightness。

下列範例顯示布魯克林的地圖，其中所有當地道路都已變更為亮綠色，而住宅區則變更為黑色 (請注意，在這個完整運作的範例中，縱線分隔符號已正確完成 URL 編碼。請參閱上方的注意事項)：

https://maps.googleapis.com/maps/api/staticmap?size=512x512&zoom=15&center=Brooklyn&style=feature:road.local%7Celement:geometry%7Ccolor:0x00ff00%7Cweight:1%7Cvisibility:on&style=feature:landscape%7Celement:geometry.fill%7Ccolor:0x000000%7Cvisibility:on&style=feature:administrative%7Celement:labels%7Cweight:3.9%7Cvisibility:on%7Cinverse_lightness:true&style=feature:poi%7Cvisibility:simplified&key=YOUR_API_KEY

下列範例使用操作與簡化作業來概略顯示美國道路地圖集的外觀。

https://maps.googleapis.com/maps/api/staticmap?size=512x512&zoom=12&amp;center=Chicago&format=png&style=feature:road.highway%7Celement:geometry%7Cvisibility:simplified%7Ccolor:0xc280e9&style=feature:transit.line%7Cvisibility:simplified%7Ccolor:0xbababa&style=feature:road.highway%7Celement:labels.text.stroke%7Cvisibility:on%7Ccolor:0xb06eba&style=feature:road.highway%7Celement:labels.text.fill%7Cvisibility:on%7Ccolor:0xffffff&key=YOUR_API_KEY

標記

markers 參數可在一組位置定義一或多個標記的集合。於單一 markers 宣告內定義的每一標記，必須展現相同的視覺樣式；如果要顯示不同樣式的標記，便需要提供多個具有獨立樣式資訊的 markers 參數。

markers 參數可接受下列格式的值指派集合 (「標記描述元」)：

markers=markerStyles|markerLocation1| markerLocation2|... 等。

「markerStyles」集合是在 markers 宣告的開始位置宣告，並由零或多個樣式描述元 (以縱線字元 (|) 分隔) 所構成，後面跟隨同樣以縱線字元 (|) 分隔之一或多個位置的集合。

由於樣式資訊與位置資訊都是透過縱線字元分隔，樣式資訊在任何標記描述元中都必須優先出現。一旦 Google Static Maps API 伺服器在標記描述元中遇到一個位置，所有其他標記參數也都會被假設為位置。

標記樣式

標記樣式描述元的集合是一系列以縱線字元 (|) 分隔的值指派。這個樣式描述元定義在此樣式描述元內顯示標記時所使用的視覺屬性。這些樣式描述元包含下列機碼/值指派：

  • size: (選擇性) 從 {tiny, mid, small} 集合指定標記的大小。如果沒有設定 size 參數，該標記將會以預設 (標準) 大小顯示。

  • color: (選擇性) 指定一個 24 位元色彩 (例如：color=0xFFFFCC) 或是一個來自 {black, brown, green, purple, yellow, blue, gray, orange, red, white} 集合的預先定義色彩。

    請注意，雖然標記不支援透明度 (使用 32 位元十六進位色彩值指定)，但是路徑卻支援。

  • label: (選擇性) 指定來自 {A-Z, 0-9} 集合的單一大寫英數字元。(大寫字元的要求為此版本 API 所新增)。請注意，預設與 mid 大小的標記是唯一能夠顯示 alphanumeric-character 參數的標記。tiny 與 small 標記無法顯示英數字元。

注意：與其使用這些標記，您可以改為使用您的自訂圖示。(如需詳細資訊，請參閱下方的自訂圖示。)

標記位置

每一個標記描述元都必須包含一個或多個位置的集合，定義要在地圖上放置標記的位置。這些位置可以指定為緯度/經度值，或是指定為地址。這些位置是使用縱線字元 (|) 分隔。

位置的參數會定義標記在地圖上的位置。如果位置位於地圖之外，且假設已提供 center 與 zoom 參數，那麼該標記將不會出現在已建構的影像上。然而，如果沒有提供這些參數，Google Static Maps API 伺服器將會自動建構一個包含所提供標記的影像。(請參閱下方的隱含定位。)

下列顯示範例的標記宣告。請注意，我們定義一個樣式集，以及三個位置：

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&size=400x400&
markers=color:blue%7Clabel:S%7C11211%7C11206%7C11222&key=YOUR_API_KEY

三個布魯克林郵遞區號

如果要定義擁有不同樣式的標記，便必須提供多個 markers 參數。這個 markers 參數集定義了三個標記：一個位於「62.107733, -145.5419」，標籤為「S」的藍色標記、一個位於「Delta Junction, AK」的小型綠色標記，以及一個位於「Tok, AK」，標籤為「C」的中型黃色標記。這些標記將在下列範例中顯示：

https://maps.googleapis.com/maps/api/staticmap?center=63.259591,-144.667969&zoom=6&size=400x400\
&markers=color:blue%7Clabel:S%7C62.107733,-145.541936&markers=size:tiny%7Ccolor:green%7CDelta+Junction,AK\
&markers=size:mid%7Ccolor:0xFFFF00%7Clabel:C%7CTok,AK"&key=YOUR_API_KEY

三個阿拉斯加城市，不同標記

自訂圖示

與其使用 Google 的標記圖示，您也可以改為使用自己的自訂圖示。自訂圖示是透過針對 markers 參數使用下列描述元來指定：

  • icon 可指定要用來做為標記自訂圖示的 URL。影像可以是 PNG、JPEG 或 GIF 格式，不過我們建議使用 PNG。
  • shadow (預設為 true) 指出 Google Static Maps API 服務應該要為影像建構適當的陰影。這個陰影是根據影像的可見區域與其不透明度/透明度而定。

icon 參數必須使用 URL 來指定 (該 URL 必須完成 URL 編碼)。您可以視需要使用任何有效的 URL，或是像 http://goo.gl 的短網址服務。大部分的短網址服務都有可以自動對 URL 進行編碼的好處。圖示的大小限制為 4096 像素 (對於正方形影像來說便是 64x64)，而 Google Static Maps API 服務針對每個要求則允許最多五個唯一的自訂圖示。請注意，這些個別的唯一圖示在 Google Static Maps API 內可以多次使用。

具有 shadow:true 描述元之自訂圖示 (預設) 的「錨定點」將會設定在所提供圖示影像的正下方，而陰影也會從該處投射。沒有陰影的圖示 (透過設定 shadow:false 描述元) 將會被假設為置中於其指定位置的圖示，因此它們的錨定點將會被設定在影像的正中央。

下列範例使用 Google 的 Chart API 來建立自訂標記，並顯示數間位於紐約市的咖啡廳：

https://maps.googleapis.com/maps/api/staticmap?size=480x480&markers=
icon:http://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600%7C
224+West+20th+Street+NY%7C75+9th+Ave+NY%7C700+E+9th+St+NY&key=YOUR_API_KEY

曼哈頓咖啡廳

注意：上面範例中的多層級逸出可能會令人感到困惑。Google Chart API 使用縱線字元 (|) 來分隔其 URL 參數內的字串。由於這個字元不能在 URL 內使用 (請參閱上方的注意事項)，因此在建立完整有效的 Chart URL 時，縱線字元將逸出為 %7C。現在，結果的 URL 已內嵌為符合 icon 規格的字串，但它包含了一個 % 字元 (來自上述的 %7C)。由於這個字元不能直接做為資料包括在 URL 中，因此必須逸出為 %25。結果便是使 URL 包含 %257C，其本身代表了兩個層級的編碼。同樣地，該 Chart URL 包含了一個 &，由於這個字元會和 Google Static Maps API URL 參數的分隔符號發生混淆，因此無法直接包括在 URL 中，而必須進行編碼。

以下為建立 Google Static Maps API URL 的步驟：

# Intended chld parameter:
chld=cafe|996600

# Embedded in a fully valid chart URL:
http://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Intended icon parameter, containing a fully valid URL:
markers=icon:http://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Embedded in a valid and unambiguous Google Static Maps API URL:
...&markers=icon:http://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600

Google Static Maps API 路徑

path 參數定義一或多個由路徑連接之位置的集合，以疊加至地圖影像上。path 參數可接受下列格式的數值指派集合 (「路徑描述元」)：

path=pathStyles|pathLocation1|pathLocation2|... 等。

請注意，兩個路徑點都是使用縱線字元 (|) 彼此分隔。由於樣式資訊與點資訊都是透過縱線字元分隔，因此樣式資訊在任何路徑描述元中都必須優先出現。一旦 Google Static Maps API 伺服器在路徑描述元中遭遇到一個位置，所有其他路徑參數也都會被假設為位置。

路徑樣式

路徑樣式描述元的集合是一系列以縱線字元 (|) 分隔的數值指派。這個樣式描述元定義顯示路徑時所使用的視覺屬性。這些樣式描述元包含下列機碼/值指派：

  • weight: (選擇性) 使用像素指定路徑的粗細。如果沒有設定 weight 參數，該路徑將會以預設粗細顯示 (5 個像素)。

  • color: (選用) 指定一個 24 位元色彩 (例如：color=0xFFFFCC) 或 32 位元十六進位值色彩 (例如：color=0xFFFFCCFF)，或是一個來自 {black, brown, green, purple, yellow, blue, gray, orange, red, white} 集合的色彩。

    指定 32 位元十六進位值時，最後的兩個字元為指定 8 位元 Alpha 透明度ˋˋ值。這個值介於 00 (完全透明) 到 FF (完全不透明) 之間。請注意，雖然路徑支援透明度，但標記並不支援。

  • fillcolor: (選擇性) 能同時指出路徑環繞一個多邊形區域，並指定該區域內疊加層所使用的填滿色彩。以下的位置集合並不需要是「封閉」的迴圈，因為 Google Static Maps API 伺服器會自動連接第一個點與最後一個點。不過，請注意任何位於填滿區域外圍的筆觸將不會被納入迴圈內，除非您特別提供相同的開始與結束位置。
  • geodesic: (選擇性) 指出要求的路徑必須解譯為符合地球弧度的測地線條。如果是「false」，則該路徑將會被轉譯為螢幕空間的直線。預設為「false」。

下列為一些路徑定義的範例：

  • 細藍色線條，50% 不透明度：path=color:0x0000ff80|weight:1
  • 純色紅色線條：path=color:0xff0000ff|weight:5
  • 純色粗白色線條：path=color:0xffffffff|weight:10

路徑樣式是選擇性。如果您要使用預設屬性，便可以略過定義路徑屬性；在那種情況下，路徑描述元的第一個「引數」便會改為包含第一個宣告的點 (位置)。

路徑點

如果要繪製路徑，便需要同時向 path 參數傳遞兩個或更多的點。Google Static Maps API 將會以指定的順序，沿著那些點將路徑連接起來。每個「pathPoint」都在「pathDescriptor」中描述，並以 | (縱線) 字元分隔。

下列範例定義一條從紐約市聯合廣場到紐約市時代廣場，具有預設 50% 不透明度的藍色路徑。

從聯合廣場到時代廣場的路徑

path 參數的細節如下所示：

path=color:0x0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

下列範例定義一條相同的路徑，但卻是擁有 100% 不透明度的純色紅色線條：

從聯合廣場到時代廣場的路徑

這個 path 參數的細節如下所示：

path=color:0xff0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

下列範例定義一個位於曼哈頓的多邊形區域，並傳遞一系列的十字路口做為位置：

從聯合廣場到時代廣場的路徑

這個 path 參數的細節如下所示：

path=color:0x00000000|weight:5|fillcolor:0xFFFF0033|8th+Avenue+%26+34th+St,New+York,NY|\
8th+Avenue+%26+42nd+St,New+York,NY|Park+Ave+%26+42nd+St,New+York,NY,NY|\
Park+Ave+%26+34th+St,New+York,NY,NY

請注意，我們將路徑本身設定為不可見，並使多邊形區域具有 15% 的不透明度。

編碼折線

與其使用一系列的位置，您可以在 path 的位置宣告內使用 enc: 前置詞，將路徑宣告為編碼折線。請注意，如果您為地圖提供編碼折線路徑，便不需要指定 (通常需要指定) center 與 zoom 參數。

下列範例使用編碼折線繪製從英屬哥倫比亞省道森河市到阿拉斯加州德爾塔章克申的阿拉斯加公路路線輪廓：

https://maps.googleapis.com/maps/api/staticmap?size=400x400&path=weight:3%7Ccolor:orange%7Cenc:polyline_data&key=YOUR_API_KEY

阿拉斯加公路

編碼折線路徑與標準路競相同，可以在傳遞 fillcolor 引數至 path 參數的情況下區分多邊形區域。

下列範例繪製紐約市布魯克林的多邊形區域輪廓：

https://maps.googleapis.com/maps/api/staticmap?size=400x400&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7C
enc:encoded_data&key=YOUR_API_KEY

布魯克林編碼折線

檢視點

影像可以透過使用 visible 參數指定可見位置，以指定「檢視點」。visible 參數會指示 Google Static Maps API 服務建構一個使現有位置維持可見的地圖。(這個參數可以與現有標記或路徑搭配使用，以同時定義一個可見地區)。以這種方式定義的檢視點將能夠排除指定確切縮放層級的需求。

下列範例要求一個以馬薩諸塞州波士頓為中心的地圖，並同時包含位於馬薩諸塞州劍橋的麻省理工學院與哈佛廣場：

https://maps.googleapis.com/maps/api/staticmap?center=Boston,MA
&visible=77+Massachusetts+Ave,Cambridge,MA%7CHarvard+Square,Cambridge,MA&size=512x512&key=YOUR_API_KEY

劍橋地圖

地圖的隱含定位

通常您必須指定 center 與 zoom URL 參數，以定義您所產生之地圖的位置與縮放層級。然而，如果您提供 marker、path 或 visible 參數，便可以改為讓 Google Static Maps API 透過評估這些元素的位置，以隱含的方式判斷正確的中心位置與縮放層級。

透過提供兩個或更多的元素，Google Static Maps API 將能夠判斷適當的中心與縮放層級，並針對包含的元素提供寬廣的邊界。下列範例顯示包含加州的舊金山、奧克蘭，以及聖荷西的地圖：

https://maps.googleapis.com/maps/api/staticmap?size=512x512&maptype=roadmap\
&markers=size:mid%7Ccolor:red%7CSan+Francisco,CA%7COakland,CA%7CSan+Jose,CA&key=YOUR_API_KEY

疑難排解與支援

如需使用 Google Static Maps API 的詳細資訊，請參閱支援頁面。

Google Static Maps API 可能會在發生問題時發出錯誤或警告。您應該特別在發現地圖上有項目遺失時檢查是否有警告。在推出新的應用程式之前檢查是否有警告，也是一個良好的做法。請注意，由於警告是顯示在 HTTP 標頭中，因此可能不會立即出現。如需詳細資訊，請參閱錯誤和警告指南。

Google Static Maps API 先前要求您包括 sensor 參數，以指出您的應用程式是否使用感應器來判斷使用者的位置。現在已不再需要此參數。

傳送您對下列選項的寶貴意見...

這個網頁
文件意見
Google Static Maps API
產品意見
需要協助嗎？請前往我們的支援網頁。