開始使用

歐洲經濟區 (EEA) 開發人員

簡介

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

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 (如果沒有標記，則為必要)：定義地圖中心，與地圖所有邊緣等距。這個參數會採用以半形逗號分隔的 {latitude,longitude} 組合 (例如「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 (選用) 定義要建構的地圖類型。maptype 有多個可能的值，包括 roadmap、satellite、hybrid 和 terrain。詳情請參閱「Maps Static API 地圖類型」。
  • colorscheme (選用) 定義地圖的色彩配置。可接受的值為 light (預設) 和 dark。深色色彩配置適用於 roadmap 和 terrain 地圖類型。詳情請參閱「瞭解模式和地圖類型」。
  • language (選用) 定義地圖圖塊上標籤的顯示語言。請注意，只有部分國家/地區的圖塊支援這項參數。如果圖塊集不支援要求的特定語言，系統會使用該圖塊集的預設語言。
  • region (選用) 根據地緣政治敏感度，定義要顯示的適當邊界。接受指定為雙字元 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 控制台中監控應用程式的 API 使用情形，並確保 Google 能在必要時與您聯絡，討論應用程式相關事宜。詳情請參閱「搭配 Maps Static API 使用 API 金鑰」。
  • signature (建議) 是數位簽章，用於驗證使用 API 金鑰產生要求的網站是否已獲得授權。沒有數位簽章的要求可能會失敗。詳情請參閱「使用數位簽章」。

網址大小限制

Maps Static API 網址長度上限為 16384 個字元。在實際情況中，除非您製作的地圖很複雜，包含大量標記和路徑，否則應該不需要超過這個長度的網址。

參數使用

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 服務就能為您執行地理編碼。

在任何可提供經緯度的參數中，您都可以改為指定表示地址的字串。Google 會為地址進行地理編碼，並為 Maps Static API 服務提供經緯度值，用於放置標記或指定位置。字串應經過 URL 編碼，因此「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 地圖 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 像素。在 LCD 電腦螢幕上 (通常每英寸顯示約 100 像素 (ppi))，200x200 的地圖在每個維度上約為 2 英寸。

不過，行動裝置越來越常配備像素密度超過 300ppi 的高解析度螢幕，這會導致：

  • 將 200x200 像素的圖片縮小至 0.7 英寸，導致標籤和圖示太小而無法閱讀。
  • 縮放圖片以提高可讀性，導致圖片模糊或像素化。
太小 太模糊

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

舉例來說，如果比例值為 2，傳回的地圖涵蓋範圍會與未指定比例的要求相同，但每個維度的像素數量會增加一倍。包括道路和標籤，因此在高解析度的小型螢幕上，以及瀏覽器縮放時，都能清楚顯示。

150x150 150x150&scale=2

如果將這類圖片插入 img 或 div 標記，並使用 CSS 設定高度和寬度，在電腦版瀏覽器上也能有良好的顯示效果。瀏覽器會將圖片縮小至正確大小，而不會降低品質。

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

  • 第一個是索取 100x100 圖像，未指定比例值。在電腦上可以正常顯示，但在行動裝置上太小，難以閱讀。
  • 第二個是索取兩倍大小的地圖。在電腦上，CSS 會將圖片調整為指定的 100x100 img 元素，但縮小圖片後，道路和標籤會變得太小。在行動裝置上，圖片大小正確，但道路和標籤同樣難以辨識。
  • 第三個要求是 100x100 的地圖，並使用 scale=2。系統會傳回 200 像素細節的圖片；電腦會完美縮小圖片，因此與原始 100x100 要求無法區分，而行動瀏覽器則可受益於 API 傳回的額外解析度。
圖片要求
裝置 100x100 200x200 100x100&scale=2
電腦版
(
img 標記
含有 height="100px" 和 width="100px")
高解析度
(模擬)

如要進一步瞭解如何開發行動裝置和高解析度螢幕，建議您閱讀下列文章：

圖片格式

傳回的圖片可能採用幾種常見的網頁圖形格式：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；一個位於「Delta Junction, AK」的小型綠色標記；以及一個標示為「C」的中型黃色標記，位於「Tok, AK」。如以下範例所示：

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%。

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

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

以下範例使用編碼折線，勾勒出阿拉斯加公路從英屬哥倫比亞省道森克里克到阿拉斯加州達美交界處的路線：

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%7D%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA%7Df%5BroaAynd@%7CvXxiAt%7BZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k%7Bg@i%60%5Do%7CF%7DvXaj%5Ch%60%5Dovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh%60%5Dv%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez%5C_%7BKm_%60@~re@ew%5ErcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr%7BZlwBrvdAmtHrmT%7BrOt%7BZz%7DE%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@%60%60NrfQpcHrb%5Ek%7CDh_z@nwB%7Ckb@a%7BR%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY%7Dt%5Dhuf@e%7CFria@o%7DGfezAkdW%7C%7D%5BocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C%60l@uoJrvdAgq@fppAsjGhg%60@%7ChQpg%7BAi_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C%7D%5Bmv%60@t_NitSfjp@c%7DMhg%60@sbChyYq%7De@rwg@atFff%7D@ghN~zKybk@fl%7DA%7DcPftcAite@tmT__Lha@u~DrfQi%7DMhkSqyWivIumCria@ciO_tHifm@fl%7DA%7Brc@fbjAqvg@rrqAcjCf%7Ci@mqJtb%5Es%7C@fbjA%7BwDfs%60BmvEfqs@umWt_Nwn%5Epen@qiBr%60xAcvMr%7BZidg@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:%7DzswFtikbMjJzZ%7CRdPfZ%7DDxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz%40bIx%7BA%7CPfYlvApz%40bl%40tcAdTpGpVwQtX%7Di%40%7CGen%40lCeAda%40bjA%60q%40v%7D%40rfAbjA%7CEwBpbAd_%40he%40hDbu%40uIzWcWtZoTdImTdIwu%40tDaOXw_%40fc%40st%40~VgQ%7C%5BuPzNtA%60LlEvHiYyLs%5EnPhCpG%7DSzCNwHpz%40cEvXg%40bWdG%60%5DlL~MdTmEnCwJ%5BiJhOae%40nCm%5B%60Aq%5DqE_pAaNiyBuDurAuB%7D%7DAy%60%40%7CEKv_%40%3F%7C%5BqGji%40lAhYyH%60%40Xiw%40tBerAs%40q%5DjHohAYkSmW%3FaNoaAbR%7DLnPqNtMtIbRyRuDef%40eT_z%40mW_Nm%7CB~j%40zC~hAyUyJ_U%7BZ%3F%3FcPvg%40%7Ds%40sHsc%40_z%40cj%40kp%40YePoNyYyb%40_iAyb%40gBw%5EbOokArcA%7DGwJuzBre%40i%5Ctf%40sZnd%40oElb%40hStW%7B%5Dvv%40%3F%3Fkz%40~vAcj%40zKa%60Atf%40uQj_Aee%40pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

布魯克林編碼折線 (含簽章)

檢視區

圖片可使用 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 像素 (或 1280 x 1280 像素，縮放值為 2) 的圖片，請 與支援團隊聯絡，並提供下列資訊：

  1. 您的用途，以及需要大型圖片的原因。
  2. 您是否考慮過使用其他 Google Maps Platform 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 標頭中，因此可能不會立即顯示。詳情請參閱錯誤和警告指南。