搭配 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

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

選填欄位

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

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

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

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

比例因數 1 倍 比例因數 2 倍
顯示比例因數 1 倍的地圖 顯示比例係數 2 倍的地圖
highDpi
指定是否要傳回高解析度圖塊。如果增加縮放比例係數，系統會使用 highDpi 增加圖塊的大小。一般來說，增加比例係數會將產生的圖塊放大為大小相同的圖片，進而降低品質。使用 highDpi 時，結果大小也會提高，並保留品質。DPI 代表每英寸像素數，而高 DPI 表示圖塊的每英寸像素數比一般情況多。如果為 true，則每個 x 和 y 維度中的像素數量都會乘以比例係數 (也就是 2x 或 4x)。圖塊的涵蓋區域維持不變。這個參數只適用於 2 或 4 倍的 scale 值。不會影響 1 倍縮放圖塊。
比例因數 1 倍 縮放比例係數 2 倍高 DPI
以一般解析度顯示的地圖 地圖以 2 倍高 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：是
疊加層已設為 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
必須在所有地圖 Tiles API 要求中加入的工作階段符記值。
expiry
字串，包含符記的到期時間時間 (以秒為單位)。工作階段符記從建立時間起算的兩週內有效，但這項政策可能會有變動，恕不另行通知。
tileWidth
圖塊的寬度 (以像素為單位)。
tileHeight
圖塊的高度 (以像素為單位)。
imageFormat
圖片格式，可以是 png 或 jpeg。