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

工作階段符記是一段資料 (UUID)，用於 REST 呼叫來識別「工作階段」，也就是一系列相關的訊息交換。您必須在所有 2D 圖塊和街景圖像要求中加入工作階段權杖。您可以將其納入 session 參數的值，並附加至所有要求網址。

在 Map Tiles API 中，工作階段權杖代表一組定義的顯示選項。這表示您不必在每個資訊方塊要求中傳遞一組顯示選項。您可以在多個用戶端中使用相同的工作階段符記。目前，工作階段權杖自核發時間起算，有效期為兩週，但這可能會有所變動。您隨時可以查看回應訊息中的 expiry 欄位，檢查工作階段權杖的到期時間。

工作階段符記要求

如要要求工作階段權杖，請將 HTTPS POST 要求傳送至 createSession 端點，如以下範例所示。您必須傳送附帶 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

代表使用者實際位置的 Common Locale Data Repository 區域 ID (兩個大寫字母)。例如 US。

選填欄位

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

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

  • scaleFactor1x：預設值。
  • scaleFactor2x：將標籤大小加倍，並移除次要地圖項目標籤。
  • scaleFactor4x：四倍放大標籤大小，並移除次要地圖項目標籤。

以下範例說明縮放地圖元素的效果。

縮放比例係數 1 倍 縮放比例 2x
顯示縮放比例 1x 的地圖 顯示縮放比例 2x 的地圖
highDpi
指定是否傳回高解析度圖塊。如果比例因數增加，系統會使用 highDpi 增加圖塊的大小。一般來說，增加縮放比例係數會將產生的圖塊放大成相同大小的圖片，進而降低品質。使用 highDpi 時，產生的大小也會增加，以保留品質。DPI 代表每英寸的圓點；高 DPI 表示圖塊的每英寸像素數會比一般使用點多。如果為 true，則 x 和 y 各維度的像素數量會乘以縮放因子 (即 2x 或 4x)。資訊方塊的涵蓋範圍則維持不變。這個參數僅適用於 scale 值為 2x 或 4x 的情況。對 1 倍縮放圖塊沒有影響。
縮放比例 1x 縮放比例係數 2x 高 DPI
以一般解析度顯示地圖 以 2x 高 DPI 解析度顯示的地圖
layerTypes

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

layerRoadmap
如果將 terrain 指定為地圖類型，則為必要欄位。也可以選擇疊加在 satellite 地圖類型上。不會對路線圖圖塊造成影響。
layerStreetview
在地圖上以藍色輪廓顯示支援街景服務的街道和地點。
layerTraffic
顯示目前的路況。
styles

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

overlay

布林值，用於指定 layerTypes 應以獨立疊加方式呈現，還是與基本圖像合併。當 true 時，系統不會顯示基本地圖。如果您未定義任何 layerTypes，系統會忽略這個值。

舉例來說，如果您要求含有 layerRoadmap 圖層的 satellite 地圖類型，並將 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" }
      ]
    }
  ]
}

這個範例提供適合與衛星影像結合的疊加圖層。這個範例同時包含路線圖和街景服務疊加圖層。產生的地圖會以英文呈現名稱和資料，因為這是美國的官方語言。

apiOptions：值陣列，指定要套用的其他選項。支援的選項包括：

  • MCYJ5E517XR2JC - 選擇採用新地圖樣式。在選擇加入期間，除非你指定這個值，否則要求將取得現有樣式。

工作階段符記回應

以下 JSON 為回應主體範例。

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

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

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