搭配 Map Tiles API 使用工作階段符記

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

工作階段權杖是一段資料 (UUID)，用於 REST 呼叫，以識別工作階段 (一系列相關訊息交換)。所有 2D 圖塊和 Street View 圖像的要求都必須包含工作階段權杖。您會將這個值做為 session 參數的值，附加至所有要求網址。

在 Map Tiles API 中，工作階段權杖代表一組已定義的顯示選項。這表示您不必在每個圖塊要求中傳遞一組顯示選項。您可以在多個用戶端中使用相同的工作階段權杖。工作階段權杖目前在核發後兩週內有效，但這項規定可能會變更。如要查看工作階段權杖的到期時間，請查看回應訊息中的 expiry 欄位。

工作階段符記要求

如要要求會期權杖，請向 createSession 端點傳送 HTTPS POST 要求，如下列範例所示。您必須傳送附帶 Content-Type: application/json 標頭的要求。

curl -X POST -d '{
  "mapType": "streetview",
  "language": "en-US",
  "region": "US"
}' \
-H 'Content-Type: application/json' \
"https://tile.googleapis.com/v1/createSession?key=YOUR_API_KEY"

必填欄位

mapType

基本地圖類型。這個值可以是下列其中之一：

roadmap
標準 Google 地圖彩繪地圖圖塊。
satellite
衛星圖像。
terrain
地形圖像。選取 terrain 做為地圖類型時，您也必須加入 layerRoadmap 圖層類型 (如「選用欄位」一節所述)。
streetview
街景服務全景。詳情請參閱「街景服務圖塊」。
language

IETF 語言標記，指定用於顯示動態磚資訊的語言。舉例來說，en-US 指定的是美國境內使用的英文。

region

代表使用者實際位置的通用地區設定資料儲存庫區域 ID (兩個大寫字母)。例如 US。

選填欄位

imageFormat
指定要傳回的檔案格式。有效值為 jpeg 或 png。 JPEG 檔案不支援透明度，因此不建議用於疊加圖塊。如未指定 imageFormat，系統會自動選擇最適合圖塊的格式。
scale

放大地圖元素 (例如道路標籤) 的大小，同時保留預設圖塊的圖塊大小和涵蓋範圍。提高比例也會減少地圖上的標籤數量，減少雜亂感。以下為有效的 scale 值：

  • scaleFactor1x：預設值。
  • scaleFactor2x：將標籤大小加倍，並移除次要的特徵標籤。
  • scaleFactor4x：將標籤大小放大四倍，並移除次要特徵標籤。

以下範例會示範縮放地圖元素的效果。

縮放比例係數 1x 縮放比例係數 2 倍
顯示縮放比例係數 1x 的地圖 顯示縮放比例係數為 2 倍的地圖
highDpi
指定是否傳回高解析度圖塊。如果比例因數增加，highDpi 會用於增加圖塊大小。一般來說，提高縮放比例會將產生的圖塊放大為相同大小的圖片，但品質會降低。使用 highDpi 時，產生的檔案大小也會增加，但品質不變。DPI 是指每英吋點數，高 DPI 代表圖塊的每英吋點數比平常多，如果是 true，則 x 和 y 維度中的像素數會乘以縮放比例 (即 2 倍或 4 倍)。圖塊的涵蓋範圍維持不變。 這個參數僅適用於 2 倍或 4 倍的 scale 值。這項設定不會影響 1 倍縮放比例的動態磚。
縮放比例係數 1x 縮放比例係數 2 倍高 DPI
以一般解析度顯示的地圖 以 2 倍高 DPI 解析度顯示的地圖
layerTypes

指定新增至地圖的圖層類型值陣列。有效值如下：

layerRoadmap
如果指定 terrain 做為地圖類型，則為必要屬性。也可以選擇性地疊加在 satellite 地圖類型上。不會影響路線圖圖塊。
layerStreetview
地圖上以藍色輪廓標示支援街景服務的街道和地點。
layerTraffic
顯示目前的車流量狀況。
styles

JSON 樣式物件陣列，用於指定地圖項目的外觀和詳細程度，例如道路、公園和建築物密集區。樣式用於自訂標準 Google 基本地圖。只有在地圖類型為 roadmap 時，styles 參數才有效。如需完整樣式語法，請參閱樣式參考資料。

overlay

布林值，用於指定 layerTypes 應以獨立疊加層的形式算繪，還是與基礎圖像合併。如果 true，系統就不會顯示基本地圖。如果未定義任何 layerTypes，系統會忽略這個值。

舉例來說，如果要求 satellite 地圖類型搭配 layerRoadmap 圖層，並將 overlay 設為 false，產生的圖塊就會等同於 Maps JavaScript API 中使用的 hybrid 地圖類型 (左圖)。如果將 overlay 設為 true，相同地圖和圖層類型會產生透明圖塊，並疊加地圖，樣式也經過適當調整，可疊加在衛星影像上 (右側圖片)。

overlay：false overlay：true
疊加層設為 false 疊加層設為 true

下列 JSON 範例是包含必要和選用欄位的典型要求主體。

{
  "mapType": "satellite",
  "language": "en-US",
  "region": "us",
  "layerTypes": [ "layerRoadmap", "layerStreetview" ],
  "overlay":  true,
  "scale": "scaleFactor1x",
  "styles": [
    {
      "stylers": [
        { "hue": "#00ffe6" },
        { "saturation": -20 }
      ]
    },{
      "featureType": "road",
      "elementType": "geometry",
      "stylers": [
        { "lightness": 100 },
        { "visibility": "simplified" }
      ]
    }
  ]
}

這個範例提供的疊加層適合與衛星圖像合併使用。這個範例包含路線圖和街景服務疊加層。因此產生的地圖會以英文顯示名稱和資料，因為這是美國使用的語言。

工作階段符記回應

以下是回應主體的 JSON 範例。

{
  "session": "IgAAAHGU9jnAU4KOAfwY3Bcd6eH_WxQsyocSBAdUnAr9pnvTTNXtF9c_27RBo94ytEXTDg",
  "expiry": "1361828036",
  "tileWidth": 256,
  "tileHeight": 256,
  "imageFormat": "png"
}

以下清單包含回應主體中欄位的定義。

session
您必須在所有 Map Tiles API 要求中加入的工作階段權杖值。
expiry
字串，內含權杖到期時間 (自 Epoch 起算的秒數)。工作階段權杖的效期為建立時間起算的兩週，但這項政策可能會變更，恕不另行通知。
tileWidth
以像素為單位測量的圖塊寬度。
tileHeight
以像素為單位測量的圖塊高度。
imageFormat
圖片格式，可以是 png 或 jpeg。