工作階段符記是一段資料 (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
基本地圖的類型。這個值可以是下列其中一項:
language
IETF 語言代碼指定在圖塊上顯示資訊時所用的語言。例如,
en-US
會指定美國的英文語言。region
代表使用者實際位置的通用本機資料存放區區域 ID (兩個大寫字母)。例如
US
。
選填欄位
imageFormat
- 指定要傳回的檔案格式。有效值為
jpeg
或png
。JPEG 檔案不支援透明度,因此不建議用於疊加圖塊。如未指定imageFormat
,系統會自動選擇資訊方塊的最佳格式。 scale
放大地圖元素 (例如道路標籤) 的大小,同時保留預設圖塊的圖塊尺寸和涵蓋範圍區域。增加縮放比例也會減少地圖上的標籤數量,減少干擾。以下為有效的
scale
值:scaleFactor1x
:預設值。scaleFactor2x
:將標籤大小加倍,並移除次要的特徵標籤。scaleFactor4x
:四元組標籤大小,並移除次要特徵標籤。
下例示範縮放地圖元素的效果。
縮放比例係數 1 倍 | 縮放比例係數 (2 倍) |
---|---|
highDpi
- 指定是否要傳回高解析度圖塊。如果縮放比例係數增加,系統會使用
highDpi
增加資訊方塊的大小。一般來說,增加縮放比例係數會將產生的圖塊放大成相同大小的圖片,進而降低品質。使用highDpi
時,產生的大小也會提高,確保品質。DPI 代表每英寸的圓點;高 DPI 表示圖塊的每英寸像素數會比一般使用點多。如果設為true
,則每個 x 和 y 尺寸中的像素數量乘以比例因數 (即 2x 或 4x)。圖塊的涵蓋範圍會維持不變。這個參數僅適用於 2 倍或 4 倍的scale
值。對 1 倍縮放圖塊沒有影響。
縮放比例係數 1 倍 | 縮放比例係數 2 倍高 DPI |
---|---|
layerTypes
指定加入地圖的圖層類型的值陣列。有效值如下:
layerRoadmap
- 如果將
terrain
指定為地圖類型,則為必要欄位。但也可以視需要在satellite
地圖類型上重疊。不會影響藍圖圖塊。 layerStreetview
- 在地圖上使用藍色外框,顯示已啟用街景服務的街道和地點。
layerTraffic
- 顯示目前路況。
styles
JSON 樣式物件陣列,用於指定道路、公園、高度開發區域等地圖項目的外觀和詳細資料層級。樣式是用來自訂標準 Google 基本地圖。
styles
參數只有在地圖類型為roadmap
時有效。如需完整的樣式語法,請參閱樣式參考資料。overlay
指定
layerTypes
是否應以獨立疊加層呈現,或與基本圖像合併的布林值。設為true
時,不會顯示基本地圖。如果您尚未定義任何layerTypes
,系統就會忽略這個值。
舉例來說,如果要求包含 layerRoadmap
圖層的 satellite
地圖類型,並將 overlay
設為 false
,則圖塊會產生相當於 Maps JavaScript API 中使用的 hybrid
地圖類型 (左圖)。將 overlay
設為 true
的相同地圖和圖層類型,會產生透明圖塊與地圖疊加層,且樣式經過適當設定,可以疊加在衛星圖像上 (右圖)。
overlay :false |
overlay :是 |
---|---|
下列 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
。