開始使用

簡介

Maps Static API 會根據網址傳回 HTTP 要求的圖片 (GIF、PNG 或 JPEG)。針對每個要求，您可以指定地圖的位置、圖片大小、縮放等級、地圖類型以及地圖中位置的選用標記的位置。您也可以使用英數字元來為標記加上標籤，

Maps Static API 映像檔嵌入在 <img> 標記的 src 屬性中，或是其他程式設計語言的對等項目。

本文件說明 Maps Static API 網址的必要格式以及可用參數。並指出一些指定網址的提示和秘訣

事前準備

本文旨在協助網站和行動開發人員在網頁或行動應用程式中加入 Maps Static API 圖片。本文介紹如何使用 API 和可用參數的參考資源。

使用 Maps Static API 開始開發之前，請先詳閱驗證規定 (您必須具備 API 金鑰) 和 API 使用情形與計費資訊 (需為專案啟用計費功能)。

網址參數

Maps Static API 網址的格式必須為：

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

如果您的網站是透過 HTTPS 存取，您就必須透過 HTTPS 載入 Maps Static API 映像檔，以避免出現瀏覽器安全性警示。如果要求含有敏感的使用者資訊 (例如使用者的位置)，也建議採用 HTTPS。

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

無論是使用 HTTP 或 HTTPS，都需要使用特定網址參數，而部分參數為選用項目。如同網址的標準，所有參數都會以 & (&) 字元分隔。本文中列舉了參數清單及可能的值。

Maps Static API 使用以下網址參數來定義地圖圖片：

地區參數

  • center (如果標記不存在，則為必填) 定義地圖的中心，與地圖的所有邊緣等距。此參數接受一個位置的逗號分隔 {緯度,經度} 對 (例如，「40.714728,-73.998672」) 或字串位址 (例如 "city Hall, new york, ny")，或識別地球表面上唯一的位置。詳情請參閱 位置。
  • zoom (如果沒有標記，此為必填屬性) 定義地圖的「縮放等級」，這會決定地圖的放大等級。這個參數接受數值，對應至與所需地區縮放等級相同的縮放等級。詳情請參閱縮放等級。

地圖參數

  • size (必要) 定義地圖圖片的矩形維度。這個參數使用 {horizontal_value}x{vertical_value} 格式的字串。舉例來說，500x400 定義的寬度為 500 像素，高度為 400 像素。如果地圖寬度小於 180 像素，則會顯示較小的 Google 標誌。此參數會受到 scale 參數影響，最終輸出大小就是大小和比例值的乘積。
  • scale (選用) 會影響傳回的像素數量。scale=2 會傳回像素的 scale=1 倍數，同時保留相同的涵蓋範圍和細節層級 (即地圖內容不會變更)。開發高解析度螢幕時，這項功能非常實用。 預設值為 1。可接受的值為 1 和 2。詳情請參閱縮放值。
  • format (選用) 定義產生的圖片格式。根據預設，Maps Static API 會建立 PNG 圖片。並有多種格式可供選擇，包括 GIF、JPEG 和 PNG 類型。可用的格式取決於您呈現圖片的方式。JPEG 通常能夠提供較多的壓縮，而 GIF 和 PNG 則提供更多細節。詳情請參閱「圖片格式」。
  • maptype (選用) 定義要建構的地圖類型。幾種可能的地圖類型值，包括 roadmap、satellite、hybrid 和 terrain。詳情請參閱 Maps Static API 地圖類型。
  • language (選用) 定義在地圖圖塊中顯示標籤時所使用的語言。請注意，這個參數僅適用於部分國家/地區圖塊；如果圖塊集不支援特定要求的語言，系統將使用該圖塊的預設語言。
  • region (選用) 根據地理政治的敏感度來定義要顯示的邊框。可接受指定為 2 個字元的 ccTLD (「頂層網域」) 值的區域代碼。請參閱 Google 地圖平台涵蓋範圍詳細資料瞭解支援的地區。

特徵參數

  • map_id (選用) 會指定特定地圖的 ID。地圖 ID 會將地圖與特定樣式或地圖項目建立關聯，且必須和用於初始化地圖的 API 金鑰屬於相同的專案。詳情請參閱使用地圖 ID。
  • markers (選用) 定義一或多個標記，以附加至圖片的位置。此參數接受參數標記，並以直立線字元 (|) 分隔參數。如果標記包含多個樣式，系統會將多個標記放在同一個 markers 參數中；只要新增其他 markers 參數即可加入其他不同樣式的標記。請注意，如果您是為地圖提供標記，則不需要指定 (通常為必要) center 和 zoom 參數。詳情請參閱 Maps Static API 標記。
  • path (選用) 定義兩個或多個連接點的單一路徑，以在指定圖片上重疊。這個參數接受以直立線字元 (|) 分隔的點定義字串，或以路徑位置宣告中的 enc: 前置字元使用編碼折線。您可以新增額外的 path 參數來提供其他路徑。請注意，如果您為地圖提供路徑，就不需要指定 (通常為必要參數) center 和 zoom 參數。詳情請參閱 Maps Static API 路徑一文。
  • visible (選用) 會指定一或多個應要顯示在地圖上的位置，但不會顯示標記或其他指標。使用這個參數可確保特定功能或地圖位置已顯示在 Maps Static API 中。
  • style (選用) 會定義自訂樣式，以變更地圖中特定地圖項目 (道路、公園和其他地圖項目) 的呈現方式。此參數使用識別樣式的 feature 和 element 引數，以及套用至所選特徵的一組樣式運算。您可以新增多個 style 參數來提供多個樣式。詳情請參閱樣式化地圖指南。

鍵和簽名參數

  • key (必要) 可讓您在 Google Cloud Console 中監控應用程式的 API 使用情形，並確保 Google 可在必要時就應用程式的相關事宜與您聯絡。詳情請參閱搭配 Maps Static API 使用 API 金鑰。
  • signature (建議) 是一種數位簽章，可用於驗證使用 API 金鑰產生要求的所有網站都已獲得授權。沒有數位簽章的要求可能會失敗。詳情請參閱使用數位簽章。

網址大小限制

Maps Static API 的網址長度上限為 8192 個字元。實際運作時，除非您需要產生大量標記與路徑的複雜地圖，否則應該不需要使用超過這個上限的網址。

參數使用

Maps Static API 只包含容易使用的網址，因此相當容易使用。本節說明如何使用這些參數建構網址。

指定位置

Maps Static API 必須能夠精確識別地圖上的位置，包括將地圖聚焦在正確的位置 (使用 center 參數) 和/或在地圖上放置任何選用地標 (使用 markers 參數)。Maps Static API 使用數字 (經緯度值) 或字串 (位址) 來指定這些位置。這些值可識別地理編碼位置。

一些參數 (例如 markers 和 path 參數) 會使用多個位置。在這種情況下，這些位置會以直立線 (|) 字元分隔。

緯度和經度

緯度和經度在由逗號分隔的文字字串中使用數字，其精確度可達到小數點後 6 位。例如，「40.714728,-73.998672」是有效的地理編碼值。系統會忽略超過 6 位小數的精確度。

經度值是與英國格林威治 (本初子交會的故居) 之間的距離。由於格林威治位於緯度 51.477222，因此我們可以輸入 51.477222,0 的 center 值，以將格林威治設為地圖中心：

格林威治，英國

緯度和經度值必須對應到地球表面的有效位置。緯度值可以是介於 -90 到 90 之間的任何值，而經度值可介於 -180 和 180 之間。指定的緯度或經度值無效時，系統會拒絕您的要求。

地址

大多數使用者都不會使用緯度和經度，而是使用地址來表示位置。將地址轉換成地理點的過程稱為「地理編碼」；如果您提供有效的地址，Maps Static API 服務可以為您進行地理編碼。

而您可以在任何提供緯度/經度的參數中，改為指定指定 address 的字串。Google 會為地址進行地理編碼，並為 Maps Static API 服務提供緯度/經度值，以便放置標記或指定位置。字串應為網址編碼，例如「City Hall, New York, NY」等地址應轉換為「City+Hall,New+York,NY」。

請注意，地址可以反映精確位置，例如街道地址、折線 (例如指定路線) 或多邊形區域 (例如城市、國家/地區或國家公園)。如果是折線和多邊形的結果，Maps Static API 伺服器會使用線條/區域的中心點做為地址中心。如果不確定地址可能如何進行地理編碼，可以使用此地理編碼公用程式來測試地址。

下列範例會產生加州伯克利的靜態地圖圖片：

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

柏克萊 (加州)

縮放等級

「Google 地圖」中的地圖包含一個整數「縮放等級」，可定義目前檢視的解析度。在預設的 roadmap 檢視畫面中，縮放等級可介於 0 (最低縮放等級，且一張地圖可檢視整個世界) 至 21+ (向下至街道和個別建築物)。建築物輪廓 (如果有的話) 會顯示在縮放等級為 17 周圍。這個值因地區而異，且會隨著資料演變而隨著時間改變。

「Google 地圖」會將縮放等級設為「0」，以涵蓋整個地球。 每個成功的縮放等級在水平和垂直維度上都可提高兩倍的精確度。如要進一步瞭解相關做法，請參閱 Google Maps JavaScript API 說明文件。

注意：並非地球上的所有地點都會顯示所有縮放等級。縮放等級會因位置而異，因為全球某些部分的資料比其他地點更精細。

如果您傳送的縮放等級要求不存在地圖圖塊，Maps Static API 將改為傳回空白圖片。

以下清單列出各縮放等級大致可顯示的精細程度：

  • 1：全世界
  • 5：自然景觀/大陸
  • 10：城市
  • 15：街道
  • 20：建築

此範例要求兩個 center 值相同，但縮放等級分別為 12 和 14 的曼哈頓地圖：

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

曼哈頓法塔威 (Manhattan Faraway)  近距離曼哈頓

圖片大小

size 參數和 center 會定義地圖的涵蓋區域。此外，也乘以 scale 的值 (預設為 1) 來定義地圖的輸出大小 (以像素為單位)。

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

scale=1 scale=2
640x640 640x640 (傳回 1280x1280 像素)

這個範例要求縮放等級為 1 的赤道「地球」的「草地」：

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

赤道

此範例要求以相同區域為中心，大小為 100 x 100 像素的小地圖。請注意 Google 標誌縮小了：

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

小赤道地圖

縮放值

Maps Static API 的 size 參數可定義地圖大小 (以像素為單位)，讓具有 size=200x200 的地圖傳回 200 x 200 像素。在一般顯示每英寸約 100 像素 (ppi) 的 LCD 電腦螢幕上，200x200 的地圖在各維度中約為 2 英寸。

不過，行動裝置的螢幕解析度也越來越高，像素密度超過 300ppi，可以：

  • 將 200x200 像素的圖片縮小為 0.7 英寸，算繪標籤和圖示太小而難以閱讀；或
  • 縮放 (縮放) 圖片以提升清晰易讀，使圖片模糊不清或像素化。
太小 太模糊

針對行動裝置開發時，您可以使用 API 的 scale 參數，傳回能解決上述問題的高解析度地圖圖片。scale 值乘以 size 可確定圖片的實際輸出大小 (以像素為單位)，但不會變更地圖的涵蓋範圍。預設的 scale 值為 1；接受的值是 1 和 2。

舉例來說，如果指定比例值 2，系統會傳回與未指定要求相同的地圖涵蓋區域，但每個維度的像素數量為兩倍。包括道路和標籤，因此在高解析度、小尺寸螢幕或瀏覽器縮放時，清晰可讀。

150x150 150x150&scale=2

如果將圖片插入使用 CSS 設定的高度和寬度的 img 或 div 標記，這類圖片在電腦瀏覽器中的成效會良好。瀏覽器會將圖片大小縮小到正確的尺寸，而不會降低畫質。

此表格顯示三種不同的圖片要求。

  • 第一個是索取 100x100 圖像，未指定比例值。它 可正常顯示在桌面上，但在行動裝置上難以閱讀。
  • 第二個是索取兩倍大小的地圖。在電腦上，CSS 應符合指定的 100x100 img 元素，但因為縮小了圖片的大小，所以道路和標籤太小。在行動裝置上，圖片大小正確，但道路和標籤都難以辨識。
  • 第三個要求是包含 scale=2 的 100x100 地圖。圖片傳回的詳細資訊是 200px；電腦版會將圖片縮小到 100x100，因此與原始 100x100 要求是各自獨立的，而行動瀏覽器本身則支援 API 傳回的額外解析度。
圖片請求
裝置 100x100 200x200 100x100&scale=2
電腦
(height="100px" 和
width="100px"，
img)
高解析度
(模擬)

要進一步瞭解如何針對行動裝置和高解析度螢幕進行開發，請參閱下列文章：

圖片格式

圖片能以多種常見的網路圖形格式傳回：GIF、JPEG 和 PNG。format 參數可採用下列其中一個值：

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

以下範例要求以 gif 和 png 格式進行對應：

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

jpg 和 jpg-baseline 通常會提供最小的圖片大小，但透過「有損」的壓縮方式進行，可能會降低圖片的品質。gif、png8 和 png32 提供無損壓縮。

大多數 JPEG 圖片都是漸進式的，表示它們會提前載入較粗的圖片，然後再隨著資料量增加而縮小圖片解析度。這樣一來，圖片就能快速載入網頁，這是目前 JPEG 的最廣泛使用。不過，部分 JPEG 用途需要非漸進式 (基準) 圖片。在這類情況下，建議您使用 jpg-baseline (非漸進式) 格式。

地圖類型

Maps Static API 建立了多種格式的地圖，如下所示：

  • roadmap (預設) 會指定標準道路地圖圖片，如 Google 地圖網站一般所示。如未指定 maptype 值，Maps Static 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&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

曼哈頓法線圖  曼哈頓地形圖

混合地圖會使用衛星影像和醒目的藍圖功能來建立組合圖。下列範例顯示衛星與混合地圖類型：

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

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

樣式化地圖

套用自己的樣式，自訂標準 Google 地圖的呈現方式。請參閱地圖樣式設定指南。

標記

markers 參數可在一組位置定義一組一或多個標記 (地圖圖釘)。單一 markers 宣告中定義的每個標記都必須顯示相同的視覺樣式；如果您想顯示不同樣式的標記，則必須提供多個 markers 參數，並分別提供樣式資訊。

markers 參數接受下列格式的一組值指派 (標記描述元)：

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

這一組 MarkerStyles 會在 markers 宣告開頭宣告，且包含零或多個以直立線字元 (|) 分隔的樣式描述元，後面接著一組或一組以上的位置，並以直立線字元 (|) 分隔。

由於樣式資訊和位置資訊都是以直立線字元分隔，因此樣式資訊必須優先顯示在任何標記描述元中。一旦 Maps Static 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 標記無法顯示英數字元。

標記縮放

將 scale 值乘以標記圖片大小，即可產生標記的實際輸出大小 (以像素為單位)。預設調整比例值為 1；接受的值為 1、2 和 4。

套用縮放比例之後，系統會套用圖片的像素大小限制。舉例來說，如果標記設為 scale:2，則標記可以大於 4096 像素的最大大小，但前提是縮放後必須小於 4096 像素。在顯示高解析度地圖時，搭配使用標記縮放和地圖縮放功能。

標記位置

每個標記描述元必須包含一組以上的位置，用來定義標記在地圖上的位置。這些位置可以指定為 緯度/經度 值或是位址。這些位置以直立線字元 (|) 分隔。

注意：如果您選擇使用需要地理編碼的方法來指定標記位置，例如使用者可理解的地址字串或折線，則要求最多只能包含 15 個標記。這項限制僅適用於需要進行地理編碼的標記位置。不適用於以緯度/經度座標指定的標記位置。

這個位置參數會定義標記在地圖上的位置。如果位置不在地圖上，只要提供 center 和 zoom 參數，標記就會出現在建構的圖片中。然而，如未提供這些參數，Maps Static 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&signature=YOUR_SIGNATURE

三個布魯克林郵遞區號

如要定義不同樣式的標記，我們必須提供多個 markers 參數。這組 markers 參數定義了三個標記：一個標有「S」的藍色標記在 62.107733 至 -145.5419 處這些標記如以下範例所示：

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&signature=YOUR_SIGNATURE

三個阿拉斯加小鎮，不同的標記

自訂圖示

您可以改用自訂圖示，而不需使用 Google 的標記圖示。請使用 markers 參數中的 icon 描述元來指定自訂圖示。例如：

markers=icon:URLofIcon|markerLocation

使用網址指定 icon (應採用網址編碼)。您可以使用網址縮短服務建立的網址，例如 https://goo.gl。大多數網址縮短服務都會採用自動編碼網址的方式。

您可以為自訂圖示指定錨點。錨點可設定圖示相對於指定 markers 位置的位置。根據預設，自訂圖示的錨點是圖示圖片的正下方。您可以使用 anchor 描述元與 icon 來指定不同的錨點。將 anchor 設為圖示的 x、y 點 (例如 10,5)，或者使用下列其中一個值作為預先定義的對齊方式：top、bottom、left、right、center、topleft、topright、bottomleft 或 bottomright。例如：

markers=anchor:bottomright|icon:URLofIcon|markerLocation1|markerLocation2

每個要求最多可以使用五個不同的自訂圖示。此限制並不代表地圖上只能顯示 5 個標示位置。每個不重複的圖示可以在地圖上使用多個 markers 位置。

圖示格式：

  • 圖示圖片可以是 PNG、JPEG 或 GIF 格式，但建議使用 PNG。
  • 圖示最大大小可達 4096 像素 (正方形圖片為 64x64)。
自訂圖示範例

範例 1：建立自訂圖示並使用錨點圖示。

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=anchor:32,10%7Cicon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=anchor:topleft%7Cicon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=anchor:topright%7Cicon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY
&signature=YOUR_SIGNATURE

三個澳洲小鎮，不同地域都有自訂錨點圖示。

範例 2 建立與範例 1 相同的自訂圖示，但未使用底部中心的預設錨點設定圖示位置。

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=icon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=icon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=icon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

三個澳洲小鎮，採用不同的自訂圖示及預設定位。

Maps Static API 路徑

path 參數定義了一組由路徑連結的一或多個位置，以重疊在地圖影像上。path 參數接受下列格式的值指派 (路徑描述元)：

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

請注意，這兩個路徑點會以直立線字元 (|) 分隔。由於樣式資訊和點資訊都以直立線字元分隔，因此樣式資訊必須優先顯示在任何路徑描述元中。一旦 Maps Static 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: (選用) 表示路徑會標記多邊形區域，並指定要在該區域內的疊加層使用而填滿填滿色彩。這組位置不必是「封閉的」迴圈；Maps Static API 伺服器會自動加入第一個和最後一個點。不過請注意，除非您特別提供開始與結束位置的明確位置，否則已填滿區域外的所有筆觸不會關閉。
  • geodesic: (選用) 表示所要求的路徑應解譯為遵循地球彎曲的測地線。設為 False 時，路徑會在螢幕空間中以直線呈現。預設值為 false。

部分路徑定義範例：

  • 細藍線，50% 不透明度：path=color:0x0000ff80|weight:1
  • 實線：path=color:0xff0000ff|weight:5
  • 實心粗實線：path=color:0xffffffff|weight:10

這些路徑樣式為選用項目。如果需要預設屬性，您可以略過路徑屬性的定義；在這種情況下，路徑描述元的第一個「引數」就會由第一個宣告的點 (位置) 組成。

路徑點

為了繪製路徑，path 參數也必須傳遞兩個以上的點。然後，Maps Static API 會根據指定順序，沿著這些點連結路徑。每個 pathPoint 都會以 pathDescriptor 標示，並以 | (直立線) 字元分隔。

以下範例定義藍色路徑，預設透明度為 50%，從紐約聯合國廣場 (Union Square NY) 到紐約時代廣場 (Times Square, NY)。

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

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: 前置字元，改為將路徑宣告為編碼折線，而非一系列的位置。

下方範例概略說明阿拉斯加公路從 BC 的 Dawson Creek 公路到 Alt Junction, AK 的編碼路徑。

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=59.900503,-135.478011&zoom=4
&path=weight:3%7Ccolor:orange%7Cenc:_fisIp~u%7CU}%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA}f[roaAynd@%7CvXxiAt{ZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k{g@i`]o%7CF}vXaj\h`]ovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh`]v%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez\_{Km_`@~re@ew^rcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr{ZlwBrvdAmtHrmT{rOt{Zz}E%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@``NrfQpcHrb^k%7CDh_z@nwB%7Ckb@a{R%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY}t]huf@e%7CFria@o}GfezAkdW%7C}[ocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C`l@uoJrvdAgq@fppAsjGhg`@%7ChQpg{Ai_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C}[mv`@t_NitSfjp@c}Mhg`@sbChyYq}e@rwg@atFff}@ghN~zKybk@fl}A}cPftcAite@tmT__Lha@u~DrfQi}MhkSqyWivIumCria@ciO_tHifm@fl}A{rc@fbjAqvg@rrqAcjCf%7Ci@mqJtb^s%7C@fbjA{wDfs`BmvEfqs@umWt_Nwn^pen@qiBr`xAcvMr{Zidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

阿拉斯加公路

與標準路徑一樣，如果將 fillcolor 引數傳遞至 path 參數，編碼折線路徑也可用於區分多邊形區域。

下方範例繪製了紐約布魯克林的多邊形區域：

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=40.653279,-73.959816&zoom=11
&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:}zswFtikbMjJzZ%7CRdPfZ}DxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz@bIx{A%7CPfYlvApz@bl@tcAdTpGpVwQtX}i@%7CGen@lCeAda@bjA%60q@v}@rfAbjA%7CEwBpbAd_@he@hDbu@uIzWcWtZoTdImTdIwu@tDaOXw_@fc@st@~VgQ%7C[uPzNtA%60LlEvHiYyLs^nPhCpG}SzCNwHpz@cEvXg@bWdG%60]lL~MdTmEnCwJ[iJhOae@nCm[%60Aq]qE_pAaNiyBuDurAuB }}Ay%60@%7CEKv_@?%7C[qGji@lAhYyH%60@Xiw@tBerAs@q]jHohAYkSmW?aNoaAbR}LnPqNtMtIbRyRuDef@eT_z@mW_Nm%7CB~j@zC~hAyUyJ_U{Z??cPvg@}s@sHsc@_z@cj@kp@YePoNyYyb@_iAyb@gBw^bOokArcA}GwJuzBre@i\tf@sZnd@oElb@hStW{]vv@??kz@~vAcj@zKa%60Atf@uQj_Aee@pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Brooklyn 編碼的折線，含簽名

檢視區

您可以使用 visible 參數指定可見位置，藉此指定圖片的「可視區域」。visible 參數會指示 Maps Static 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&signature=YOUR_SIGNATURE

劍橋地圖

隱式定位地圖

通常，您必須指定 center 和 zoom 網址參數，才能定義所產生地圖的位置和縮放等級。不過，如果您提供 markers、path 或 visible 參數，可以改為讓 Maps Static API 根據對這些元素的位置評估，以隱含方式判斷正確的中心和縮放等級。

如果提供兩個以上的元素，Maps Static 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&signature=YOUR_SIGNATURE

道路地圖

圖片大小較大

如果您需要大於 640 x 640 像素 (或縮放大小為 2 的 1280 x 1280 像素) 的圖片，請與支援團隊聯絡，並提供以下資訊：

  1. 您的用途和需要大尺寸圖片的原因。
  2. 無論您考慮使用其他 Google 地圖平台 API (Maps JavaScript API、Maps Embed API、Maps SDK for Android 或 Maps SDK for iOS)，以及這些 API 為何都不符合您的需求。
  3. 如何使用大型圖片的螢幕截圖、模擬畫面或樣品。
  4. 大型圖片的每月預估用量。

我們會依據您提供的資訊來審查要求，然後確認您的用途是否符合《Google 地圖平台服務條款》。

系統支援的大小上限為 2048 x 2048 像素。

疑難排解與支援

如要進一步瞭解如何使用 Maps Static API，請參閱支援頁面。

當發生問題時，Maps Static API 可能會發出錯誤或警告。如果您發現地圖上有遺漏的內容，請特別留意警告。建議您在啟動新的應用程式之前，先檢查警告。請注意，警示可能會立即顯示在 HTTP 標頭中，因此可能不會立即顯示。詳情請參閱錯誤和警告指南。