My favorites | 中文(繁體) | Sign in
英文版或許有比此中譯版新的內容

Google 靜態地圖 API

  • Google 靜態地圖 API

    • 開發人員指南

Google 地圖 API 專業版

包括企業授權和支持

靜態地圖 API 開發人員指南

歡迎使用「Google 靜態地圖 API」的開發人員使用說明！「Google 靜態地圖 API」可讓您在自己的網頁中嵌入「Google 地圖」圖片，完全不需 JavaScript 或任何動態頁面載入。「Google 靜態地圖」服務會根據透過標準 HTTP 要求傳送的網址參數，來建立您的地圖，並傳回該地圖，做為您可以顯示在網頁上的圖片。

「Google 靜態地圖 API」需要「地圖 API 金鑰」。如果您尚未取得金鑰，請申請免費的 API 金鑰。

最新！Google 靜態地圖 API 現在具有衛星和地形地圖方塊功能！

快速範例

下列範例的網址中包含靜態地圖圖片，顯示如下：

# Note that this URL wraps at the '\' character.
# You can copy the URL from the image below, however.
# For clarity, we don't write the actual API key in use.
#
http://maps.google.com/staticmap?center=40.714728,-73.998672&zoom=14&size=512x512&maptype=mobile\
&markers=40.702147,-74.015794,blues%7C40.711614,-74.012318,greeng%7C40.718217,-73.998284,redc\
&key=MAPS_API_KEY&sensor=false

Lower Manhattan 中的查詢地點

請注意，您不需要執行任何「特殊」動作，就可以在網頁上顯示圖片。連 JavaScript 都不需要。唯一要做的就是建立網址，再將網址放在 <img> 標籤中。在您的網頁上，只要是可以放圖片的地方，就可以放置「Google 靜態地圖」。

內容

  1. 目標讀者
  2. 使用限制
  3. 總覽
  4. 網址參數
  5. 參數使用
  6. 更多資訊

目標讀者

本說明文件的適用對象，是要將「Google 靜態地圖 API」圖片放在網頁中的網站以及行動裝置開發人員。文件中會介紹如何使用此 API，並提供可用參數的參考文件。

使用限制

要使用「靜態地圖 API」，必須先註冊免費的地圖 API 金鑰。「地圖 API」金鑰可讓您使用「靜態地圖 API」以及標準的「地圖 API」。

「Google 靜態地圖 API」的使用有其限制，每位檢視者每天只能要求 1000 張不同的圖片。因為此限制的配額是每個「檢視者」而不是每個「金鑰」，因此大部分的開發人員應該都不需要擔心超過其配額。此外請注意，如果要求的是相同的圖片，一般而言就只會算成一張。

如果使用者超出上述的限制，則會顯示下列圖片，以指出超出配額：

之所以要有這個限制，是為了避免有人濫用「靜態地圖 API」和 (或) 用在其他目的。此限制以後如有變更，恕不另行通知。如果您已超過 24 小時內的使用上限，或是濫用服務，則會暫時無法使用「靜態地圖 API」。如果您持續超過上限，則會遭到封鎖，無法使用「靜態地圖 API」。

總覽

透過網址收到 HTTP 要求後，「Google 靜態地圖 API」會傳回圖片 (可能是 GIF、PNG 或 JPEG) 加以回應。針對每個要求，您可以指定地圖的位置、圖片的大小、縮放等級、地圖類型以及選用標記在地圖上放置的位置。還可以使用英數字元來標示您的標記，就能在「金鑰」中加以參照。

您可以將「靜態地圖 API」圖片內嵌在 <img> 標籤的 src屬性。顯示該網頁時，瀏覽器就會向「靜態地圖 API」要求圖片，然後在圖片位置呈現。

本文件會說明「靜態地圖 API」網址的必要格式以及可用的參數，另外也會提出一些指定網址的提示和小技巧。

網址參數

「Google 靜態地圖 API」的網址格式如下：

http://maps.google.com/staticmap?parameters

某些參數是必要的，而某些參數則為選用。跟 HTTP 的要求標準一樣，這裡的所有參數都使用 & 字元隔開。參數的清單及其可能的值都列舉在下面。

「靜態地圖 API」用以定義地圖圖片的網址參數如下：

  • center (如果沒有標記，則需使用此參數) 定義地圖的中心，讓地圖與所有邊緣等距離。此參數接受逗號分隔的 {緯度,經度} 組 (例如「40.714728,-73.998672」)，來找出地球表面的某特定位置。如需詳細資訊，請參閱下面的緯度和經度。
  • zoom (如果沒有標記，則需使用此參數) 定義地圖的縮放等級，這可以決定地圖的放大等級。此參數接受一個數字值，該值對應至指定區域的縮放等級。如需詳細資訊，請參閱下面的縮放等級。
  • size (必要) 定義地圖圖片的矩形維度。此參數接受 valuexvalue 格式的字串，其中先指出水平像素，再指出垂直像素。例如，500x400 定義地圖寬為 500 個像素，而高為 400 個像素。如果您建立的地圖寬小於或等於 100 個像素，則會自動縮小「Google 技術提供」標誌的尺寸。
  • format (選用) 定義結果圖片的格式。按照預設，「靜態地圖 API」是建立 GIF 圖片，但也可選用 GIF、JPEG 以及 PNG 類型。要使用哪一種格式，取決於您希望的圖片效果為何。通常 JPEG 壓縮較大，但 GIF 和 PNG 較細緻。如需詳細資訊，請參閱的圖片格式。
  • maptype (選用) 定義要建構的地圖類型。可用的地圖類型包括 satellite、terrain、hybrid 以及 mobile。如需詳細資訊，請參閱下面的靜態地圖 API 地圖類型。
  • markers (選用) 定義一或多種標記，附加至圖片的指定位置。此參數接受由管道字元 (|) 分隔的標記定義字串。請注意，如果您為地圖提供標記，則不需要指定 center 和 zoom 參數 (這兩個參數通常是必要的)。如需詳細資訊，請參閱下面的靜態地圖標記。
  • path (選用) 定義兩個或多個相鄰點的單一路徑，在指定位置疊加圖片。此參數接受由管道字元 (|) 分隔的點定義字串。請注意，如果您為地圖提供路徑，則不需要指定 (通常是需要的) center 和 zoom 參數。如需詳細資訊，請參閱下面的靜態地圖路徑。
  • span (選用) 以緯度和經度組定義出地圖的最小「檢視區」。靜態地圖服務接受此值，據以產生適當縮放等級的地圖，從地圖的中心點涵蓋整個提供的 span 值。請注意，依地圖的矩形維度不同，最後顯示的緯度或經度可能範圍較大。如果已指定 zoom，就會忽略 span 參數。
  • frame (選用) 指定產生的圖片要使用藍色的邊框框起來。該框架為 5 個像素、透明度 55% 的藍色邊框。
  • hl (選用) 定義地圖方塊上標籤的顯示語言。請注意，只有部分國家/地區地圖方塊支援此參數；如果指定的語言不支援該國家/地區地圖方塊集，則該地圖方塊會使用預設的語言。
  • key (必要) 針對發生網址要求的網域，指出該網域的「地圖 API」金鑰。如果您沒有「地圖 API」金鑰，可以免費申請。
  • sensor (必要) 標明要求靜態地圖的應用程式是否使用感應器來判斷使用者的位置。現在所有的靜態地圖要求都需要使用此參數。如需詳細資訊，請參閱下面的感應器。

參數使用

「靜態地圖 API」就只是具有參數的網址，因此十分容易使用。本章節說明如何使用這些參數來建構您的網址。

指定位置

「靜態地圖 API」必須能夠精確指出地圖上的位置，一方面是要讓地圖能夠對準正確位置 (使用 center 參數)，另一方面則是要在地圖上不同位置放置選用的地標 (使用 markers 參數)。「靜態地圖 API」是使用緯度和經度值來指定位置。這些值放在一起，就可指出「地理編碼」的位置。

如果您的裝置使用「感應器」(例如 GPS 裝置) 來判斷裝置或使用者的位置，則同時必須在您的「靜態地圖 API」要求網址中傳送 sensor=true。如果您的應用程式沒有使用感應器，請傳送 sensor=false。

緯度和經度

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

經度值是根據該處和英國格林威治 (本初子午線的起點) 之間的距離。因為格林威治位於緯度 51.477222，只要將 center 值設為 51.477222,0，地圖就會以格林威治為中心：

英國格林威治

緯度和經度值必須能對應到地球表面確實存在的位置。有效的緯度值介於 -90 和 90 之間，而有效的經度值介於 -180 和 180 之間。如果指定了無效的緯度或經度值，則會被視為錯誤要求而拒絕您的要求。

地理編碼

大部分的人不會使用緯度和經度來指定位置，而是使用「地址」來指出位置。將「地址」轉換為地理位置點的程序稱為「地理編碼」(Geocoding)，在 Google 地圖 API 服務章節中會有詳細討論。請注意，如果要直接使用地理編碼服務，需要使用地圖 API 金鑰。

除了「地理編碼」服務之外，還有很多服務 (甚至包括「Google 地圖」) 都可以取得地理編碼的緯度和經度值。例如，想得知某地址的地理編碼位置時，可以在「Google 地圖」中輸入地址，再按一下地圖右上方的 [連結]，就會跳出一個對話方塊，您可以複製其中的網址，再將該網址貼入瀏覽器，在 ll 參數中就是該地的地理編碼值。

縮放等級

「Google 地圖」上的地圖有整數的「縮放等級」，告訴您目前檢視的解析度。在一般地圖檢視中，縮放等級最低為 0 (可顯示全世界)，最高則為 19 (可看到個別的建築物)。

在「Google 地圖」中，縮放等級 0 能夠顯示整個地球。之後每提升一個縮放等級，水平和垂直維度都會放大兩倍。如需關於如何完成此動作的詳細資訊，請見 Google 地圖 API 使用說明。

注意：並非地球上的所有地點都會顯示所有縮放等級。能使用的縮放等級會視您查看世界的哪個角落而有所不同，某些區域的資料會比其他區域精細。

如果您傳送某個縮放等級的要求，但系統沒有對應的地圖方塊，「靜態地圖 API」就會傳回黑色圖片。

下列兩個範例在相同的 center 值要求 Manhattan 地圖，但是縮放等級分別為 12 和 14：

http://maps.google.com/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=MAPS_API_KEY&sensor=true_or_false
http://maps.google.com/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=MAPS_API_KEY&sensor=true_or_false

Manhattan 遠照  Manhattan 近照

圖片大小

抓取的圖片大小最高可達 640 x 640 像素。size 參數接受由 x 字元分隔的字串。640x640 是允許的最大圖片尺寸。請注意，如果 center 參數搭配 size 參數使用，也會以絕對方式定義地圖的涵蓋區域。

下列範例要求顯示在地球赤道上、縮放等級為 1 的「整條」區域：

http://maps.google.com/staticmap?center=0,0&zoom=1&size=400x50&key=MAPS_API_KEY&sensor=true_or_false

赤道

下列範例要求的是一個小地圖、大小為 100 x 100 像素、以相同區域為中心。請注意 Google 標誌縮小了：

小型赤道地圖

檢視區

圖片可以指定「檢視區」 (由緯度和經度值定義，以度數表示)，傳送 span 參數以顯示指定中心點的附近。如果以此方式定義最小檢視區，就不需要指定實際的縮放等級。靜態地圖服務使用 span 參數搭配 size 參數，建構出使用適當縮放等級的地圖，至少能顯示指定的檢視區。

下列範例要求方形地圖，以經度 0 度和緯度 0 度為中心，寬和高為 20 度：

http://maps.google.com/staticmap?center=0,0&span=20,20&size=512x512&key=MAPS_API_KEY&sensor=true_or_false

赤道方形地圖

下列範例要求地圖以 Manhattan 為中心，寬和高都顯示 1 弧度。請注意，因為此地圖為水平的形狀，水平延伸了 4 度，因此垂直最少可以延伸 1 度。

http://maps.google.com/staticmap?center=40.714728,-73.998672&span=1,1&size=512x128&key=MAPS_API_KEY&sensor=true_or_false

紐約，全方位都是 1 度

圖片格式

圖片可以用幾種常見的網頁圖形格式傳回：GIF、JPEG 以及 PNG。format 參數接受下列值：

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

jpg 和 jpg-baseline 的圖片檔案通常最小，但這是因為使用了「失真」壓縮，會降低圖片的解析度。gif、png8 以及 png32 則使用不失真的壓縮。

大部分 JPEG 圖片為漸進式，也就是會先載入粗略的圖片，等更多資料到達再增加圖片的解析度。這樣一來，網頁就能快速載入圖片，這也是目前 JPEG 最廣泛的運用。不過，部分 JPEG 的應用 (尤其是列印) 需要非漸進式 (基礎) 的圖片。這個時候可以使用非漸進式的 jpg-baseline 格式。

地圖類型

「Google 靜態地圖 API」建立地圖的格式有以下幾種：

  • roadmap：(預設) 標準道路圖圖片，與一般在「Google 地圖」網站中顯示的一樣。如果沒有另外指定 maptype 值，「靜態地圖 API」就會根據預設使用 roadmap 地圖方塊。
  • mobile：行動裝置道路圖圖片，圖徵和文字字型較大，方便高解析度、小螢幕的行動裝置顯示。
  • satellite：衛星圖片。
  • terrain：實際立體模型地圖圖片，可顯示地形和植被。
  • hybrid：衛星和道路圖的混合圖片，在衛星圖片上顯示一層透明的主要街道和位置名稱。

在下列範例程式碼中，您可以看到一般道路圖和行動裝置道路圖的差異。請注意，這些地圖也都設為 frame=true。

http://maps.google.com/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=MAPS_API_KEY&sensor=true_or_false
http://maps.google.com/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=mobile&key=MAPS_API_KEY&sensor=true_or_false

Manhattan 一般道路圖  Manhattan 行動裝置道路圖

下列範例分別顯示衛星地圖和地形圖：

http://maps.google.com/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=MAPS_API_KEY&sensor=true_or_false
http://maps.google.com/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=MAPS_API_KEY&sensor=true_or_false

Manhattan 衛星地圖  Manhattan 地形圖

標記

markers 參數定義一或多個標記集，以附加至地圖圖片。此參數最多可接受 50 個標記，標記由一組值指派所定義：

markers=markerDescriptor1|markerDescriptor2|markerDescriptor3|... 等等。

請注意，標記描述元彼此之間是以管道字元 (|) 分隔。(注意：如果您正在進行網址編碼，管道字元在 ASCII 中也是 %7C。)

標記描述元

每個標記描述元都有一組字串，定義放置標記的位置、以及顯示標記時要使用的視覺屬性。這些字串包含下列變數值：

  • {latitude} (必要) 緯度值，準確到小數點後 6 位。
  • {longitude} (必要) 經度值，準確到小數點後 6 位。
  • {size} (選用) 從 {tiny, mid, small} 集合中指定標記的大小。如果沒有設定 size 參數，則會以預設 (一般) 大小來顯示標記。
  • {color} (選用) 從 {black, brown, green, purple, yellow, blue, gray, orange, red, white} 集合指定色彩。
  • {alphanumeric-character} (選用) 從 {a-z, 0-9} 集合指定單一小寫英數字元。請注意，要使用預設和 mid 大小的標記，才能顯示 alphanumeric-character 參數。tiny 和 small 標記則無法顯示英數字元。

緯度和經度值會定義標記在地圖上的位置。如果位置不在地圖上，最後建立起的圖片也就無法顯示出標記。

大小、色彩以及英數字元值會定義標記的視覺外觀。如果沒有指定大小值，則會以預設 (一般) 大小來顯示標記。此外，只有一般大小的標記可顯示英數字元。如果沒有指定值 (或值不正確)，則標記會顯示為預設的紅點標記：

標記宣告的範例格式為 {latitude},{longitude},{size}{color}{alphanumeric-character}。請特別注意，字串的大小、色彩以及英數字元值不會以逗號分隔。標記宣告範本顯示如下。

markers=40.702147,-74.015794,blues|40.711614,-74.012318,tinygreen|40.713504,-74.005607,midyellowc&key=MAPS_API_KEY&sensor=true_or_false

此 markers 參數定義三個標記 (以「|」字元分隔)：一個是位於 40.702147,-74.015794 的藍色標記、標示為「S」；一個是位於 40.711614,-74.012318 的小型綠色標記；另一個則是位於 40.713504,-74.005607(市政府) 的中型紅色標記、標示為「C」。這些標記顯示於下列範例：

Lower Manhattan 中的查詢地點

使用標記取得地圖絕對位置

一般而言，您需要指定 center 和 zoom 網址參數，來定義您產生之地圖的位置和縮放等級。然而，如果您提供 markers 參數，就可以讓「靜態地圖 API」評估這些標記位置，以絕對方式來判斷正確的中心和縮放等級。

如果提供的標記在兩個以上，「靜態地圖 API」會找出適當的中心和縮放等級，保留充分餘裕來顯示 markers 參數中的標記。下列範例包含的標記與上方所顯示的相同，但是移除了 center 和 zoom 參數，可以讓地圖的中心更靠近這兩個標記。

絕對位置

靜態地圖路徑

path 參數定義一組包含一或多條路徑的路徑集，可疊加至地圖圖片上。此參數接受一系列的路徑，路徑由一組值指派所定義：

path=pathColorType:pathColorValue,weight:pathWeight|pathPoint1|pathPoint2|pathPoint3|... 等等。

請注意，路徑點會使用管道字元 (|) 將彼此分隔。(如果您正在進行網址編碼，管道字元在 ASCII 中也是 %7C。)

路徑屬性

每個 path 參數可用選用的字串開頭，以指定路徑的屬性，包括 pathColorType 和其值 (以分號分隔)。但如果想使用預設的路徑屬性，在路徑描述元之中就可以省略路徑屬性首碼；在此情況下，路徑描述元的第一個引數就是路徑宣告所描述的第一個點。(請參閱下面的路徑點。)

pathColorType 可能有兩種：

  • rgb：標準的 RGB 色彩配置，使用 24 位元、十六進位色彩值的格式 (0xffffff) 做為 pathColorValue。rgb 路徑的預設透明度為 50%。
  • rgba：以 32 位元色彩值的格式 (0xffffffff) 做為 pathColorValue，其中第四個位元組 (即最後兩個字元) 會指定「Alpha 色板」透明度。如果使用 rgba，您就可以變化自己建立的任何路徑的透明度。

除了色彩之外，weight 會指定給定路徑的寬度 (以像素為單位)。

下面顯示部分路徑定義的範例：

  • 藍色細線條，透明度 50%：path=rgb:0x0000ff,weight:1
  • 實心紅色線條：path=rgba:0xff0000ff,weight:5
  • 實心黑色粗線條：path=rgba:0xffffffff,weight:10

路徑描述元中路徑屬性的規格是選用的。如果想用預設的屬性，您可以不需要定義路徑屬性；在此情況下，路徑描述元的第一個「引數」就會由第一個已宣告的點組成。

路徑點

為了繪製路徑，也必須傳送兩個以上的點給 path 參數。然後，「Google 靜態地圖 API」會以指定的順序，沿著這些點將路徑連接起來。每個 pathPoint 會以 pathDescriptor 表示，並以 | (管道) 字元分隔。如同標記，「Google 靜態地圖 API」也會根據所提供路徑的絕對位置，試著判斷預設的中心和地圖的縮放情況。目前，任何指定的路徑的點數限制為 100 個。

下列範例以預設 50% 透明度定義藍色路徑，從紐約 Union 廣場到紐約 Times 廣場。請注意，我們並不需要提供 center 或 zoom 參數。

從 Union 廣場到 Times 廣場的路徑

path 參數的實際情況顯示如下：

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

下列範例定義相同的路徑，但以透明度 100% 的實心紅色線條來定義：

從 Union 廣場到 Times 廣場的路徑

path 參數的實際情況顯示如下：

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

更多資訊

如果「程式設計編碼」讓您感到頭痛，Google 靜態地圖精靈提供簡單的 UI 驅動方式，透過簡易的 UI 介面就能產生靜態地圖。

如需關於使用「靜態地圖 API」、或其他「Google 地圖 API」產品的詳細資訊，您一定要來參考 Google 地圖 API 網上論壇。