開始使用

簡介

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

Maps Static API 圖片內嵌於 <img> 標記的 src 屬性中,或其他程式設計語言的對等項目中。

本文件將說明 Maps Static API 網址的必要格式以及可用的參數,此外,也會列出一些指定網址的訣竅與技巧。

事前準備

本文件的目標讀者是網站和 Google 行動服務的開發人員,希望將 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。可接受的值為 12。詳情請參閱「比例值」一節。
  • format (選用) 定義產生的圖片格式。根據預設,Maps Static API 會建立 PNG 圖片。另外還有幾種格式,包括 GIF、JPEG 和 PNG 類型。您可以依照希望的圖片呈現方式,決定要使用的圖片格式。JPEG 通常可以壓縮,而 GIF 和 PNG 則提供更精細的資訊。詳情請參閱「圖片格式」。
  • maptype (選用) 定義要建構的地圖類型。有多個可能的地圖類型值,包括 roadmapsatellitehybridterrain。詳情請參閱 Maps Static API 地圖類型
  • language (選用) 定義地圖圖塊上標籤的顯示語言。請注意,這個參數僅適用於部分國家/地區圖塊;如果圖塊集不支援要求的特定語言,就會使用該圖塊的預設語言。
  • region (選用) 會根據地理政治敏感度,定義要顯示的適當邊框。接受區碼指定為雙字元 ccTLD (「頂層網域」) 值的區碼。如需支援區域的相關資訊,請參閱 Google 地圖平台涵蓋範圍詳細資料

功能參數

  • map_id (選用) 指定特定地圖的 ID。地圖 ID 會將地圖與特定樣式或地圖項目建立關聯,且所屬專案必須與初始化地圖的 API 金鑰相同。詳情請參閱使用地圖 ID 一文。
  • markers (選用) 會定義一或多個標記,以附加至圖片的指定位置。這個參數接受單一標記定義,其中參數以直立線字元 (|) 分隔。只要標記的樣式相同,即可在同一個 markers 參數中放置多個標記;您可以新增其他 markers 參數來新增不同樣式的其他標記。請注意,如果您是為地圖提供標記,則不需要指定 centerzoom 參數 (通常為必要參數)。詳情請參閱 Maps Static API 標記
  • path (選用) 定義兩個或多個相鄰點的單一路徑,在指定位置疊加圖片。這個參數接受以直立線字元 (|) 分隔的點定義字串,或是在路徑位置宣告中使用 enc: 前置字元的編碼折線。如要提供其他路徑,您可以新增額外的 path 參數。請注意,如果您是為地圖提供路徑,則不需要指定 centerzoom 參數 (通常為必要參數)。詳情請參閱 Maps Static API 路徑
  • visible (選用):指定一或多個應在地圖上持續顯示的位置,但不會顯示任何標記或其他指標。使用這個參數,即可確保 Maps Static API 顯示特定地圖項目或地圖位置。
  • style (選用) 會定義自訂樣式,以修改地圖上特定地圖項目 (道路、公園和其他地圖項目) 的呈現方式。這個參數使用 featureelement 引數,識別要設定樣式的地圖項目,並使用一組樣式作業套用至所選地圖項目。如要提供多種樣式,只需新增額外的 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 會使用數字 (經緯度值) 或字串 (地址) 來指定這些位置。這些值可用來識別地理編碼位置。

許多參數 (例如 markerspath 參數) 都會採用多個位置。在這種情況下,系統會以直線 (|) 字元分隔位置。

緯度和經度

緯度和經度是在以半形逗號分隔的文字字串中使用數值定義的,精準度為小數點後 6 位。例如,「40.714728,-73.998672」是有效的地理編碼值。系統會忽略超過 6 位小數後的精確度。

經度值是根據距離本初子午線發明家英國格林威治的距離。由於格林威治位於緯度 51.477222,我們可以輸入 51.477222,0center 值,將地圖中心設為格林威治:

格林威治,英國

緯度和經度值必須對應地球表面的有效位置。緯度可接受 -9090 之間的任何值,而經度值則可接受介於 -180180 之間的任何值。如果指定的經緯度值無效,系統會將要求視為錯誤要求遭拒。

地址

大部分的人都不會使用經緯度,而會使用「地址」來表示位置。將地址轉換成地理點的程序稱為「地理編碼」;如果您提供有效地址,Maps Static API 服務即可為您執行地理編碼。

在任何可以提供經緯度的參數中,您都可以改為指定代表「地址」的字串。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

曼哈頓法拉威  曼哈頓特寫

圖片大小

size 參數搭配 center 可定義地圖的涵蓋區域。乘上 scale 值 (預設為 1) 時,也會定義地圖的輸出大小。

這個表格顯示了 size 參數每個 scale 值的允許值上限。

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

在使用 CSS 設定高度和寬度的 imgdiv 標記中,這種圖片同樣也能在電腦版瀏覽器中順利運作。瀏覽器會將圖片縮小為正確的尺寸,不會降低畫質。

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

  • 第一個是索取 100x100 圖像,未指定比例值。標誌可在電腦上正確顯示,但太小而無法在行動裝置上閱讀。
  • 第二個是索取兩倍大小的地圖。在桌上型電腦上,CSS 會調整為指定的 100x100 img 元素,但因為在縮小圖片時,道路和標籤也變得太小。在行動裝置上,圖片的大小正確,但街道和標籤還是難以辨識。
  • 第三個要求是包含 scale=2 的 100x100 地圖。圖片會傳回 200 像素的細節;電腦版會將圖片完全縮小,因此不容易與原始的 100 x 100 要求區分,而行動瀏覽器也因此受益於 API 傳回的其他解析度。
圖片要求
裝置 100x100 200x200 100x100&scale=2
電腦
(在
img標記上使用height="100px"
width="100px")
高解析度
(模擬)

若想進一步瞭解如何開發行動裝置和高解析度螢幕,建議您參閱下列文章:

圖片格式

圖片可能會以幾種常見的網頁圖形格式傳回:GIFJPEGPNGformat 參數會採用下列其中一個值:

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

以下範例要求使用 gifpng 格式的地圖:

  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

jpgjpg-baseline 通常提供的圖片大小最小,但是透過「高失真率」的壓縮,但可能會降低圖片的品質。gifpng8png32 提供無損壓縮。

多數 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 參數。tinysmall 標記無法顯示英數字元。

標記縮放

scale 值會乘以標記圖片大小,以產生標記的實際輸出大小 (以像素為單位)。預設的 scale 值為 1;可接受的值為 1、2 和 4。

套用縮放,圖片的像素尺寸限制將適用。舉例來說,如果標記設為 scale:2,則在縮放後縮減至小於 4096 像素,標記尺寸也可能大於 4096 像素的上限。顯示高解析度地圖時,請搭配使用標記縮放與地圖縮放功能。

標記位置

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

注意:如果您選擇使用需要地理編碼的方法 (例如人類可讀的地址字串或折線) 來指定標記地點,則要求最多僅限 15 個標記。這項限制僅適用於需要地理編碼的標記地點。不適用於以經緯度座標指定的標記位置。

這個位置參數會定義標記在地圖上的位置。如果提供 centerzoom 參數,建構的圖片中就不會顯示該標記,如果位置不在地圖上。然而,如未提供這些參數,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 參數定義了三個標記:一個在 62.107733, -145.5419 標示「S」的藍色標記、在「Delta Junction, AK」的小型綠色標記,以及在「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),或設為使用下列其中一個值預先定義的對齊:topbottomleftrightcentertoplefttoprightbottomleftbottomright。例如:

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

以下範例使用編碼的折線,概略描繪阿拉斯加公路 (Dawson Creek)、BC 到 Delta 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

附有簽名的布魯克林編碼折線

檢視區

圖片可以使用 visible 參數指定可見位置,藉此指定「可視區域」visible 參數會指示 Maps Static API 服務建構地圖,讓現有地點持續顯示。(這項參數也可以與現有標記或路徑結合,藉此定義可見區域)。只要透過這種方式定義可視區域,就不必指定精確的縮放等級。

下一個範例要求一張以麻薩諸塞州波士頓為中心的地圖,其中同時包含麻薩諸塞州劍橋的 MIT 和 Harvard Square:

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

劍橋地圖

不要使用地圖定位

一般來說,您必須指定 centerzoom 網址參數,才能為產生的地圖定義位置和縮放等級。不過,如果您提供 markerspathvisible 參數,可以改為評估這些元素的位置,讓 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 標頭中。詳情請參閱錯誤和警告指南。