会话令牌是在 REST 调用中用来标识会话(一系列相关的消息交换)的一段数据 (UUID)。您必须在针对 2D 图块和街景图像的所有请求中添加会话令牌。您可以将它作为 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
基本地图的类型。这个值可以是以下值之一:
language
IETF 语言标记,用于指定在图块上显示信息时所用的语言。例如,
en-US
表示美国用户所用的英语。region
通用语言区域数据存储库的区域标识符(两个大写字母),表示用户的实际位置。例如
US
。
可选字段
imageFormat
- 指定要返回的文件格式。有效值为
jpeg
或png
。 JPEG 文件不支持透明度,因此不建议将其用于叠加层图块。如果您未指定imageFormat
,系统会自动为功能块选择最佳格式。 scale
放大地图元素(例如道路标签)的大小,同时保留默认图块的图块大小和覆盖区域。增加缩放级别也会减少地图上的标签数量,从而减少混乱。以下值为有效的
scale
值:scaleFactor1x
:默认值。scaleFactor2x
:将标签大小加倍并移除次要特征标签。scaleFactor4x
:将标签大小提高至原来的四倍并移除次要特征标签。
以下示例展示了缩放地图元素的效果。
缩放比例 1x | 缩放比例 2 倍 |
---|---|
highDpi
- 指定是否返回高分辨率图块。如果缩放比例增加,则使用
highDpi
来增加功能块的大小。通常,增加缩放比例会将生成的图块放大为大小相同的图片,这会降低质量。使用highDpi
时,生成的大小也会增加,从而保持质量。DPI 代表每英寸的点数,高 DPI 表示图块每英寸使用比正常更多的点进行渲染。如果为true
,则将 x 和 y 这两个维度中的像素数乘以缩放比例(即 2x 或 4x)。功能块的覆盖区域保持不变。此参数仅适用于 2x 或 4x 的scale
值。它对 1 倍缩放的图块没有影响。
缩放比例 1x | 缩放比例:2 倍高 DPI |
---|---|
layerTypes
值的数组,用于指定添加到地图的图层类型。有效值包括:
layerRoadmap
- 如果指定
terrain
作为地图类型,则为必需。也可以根据需要叠加到satellite
地图类型上。对路线图图块没有影响。 layerStreetview
- 在地图上使用蓝色轮廓显示支持街景的街道和位置。
layerTraffic
- 显示当前路况。
styles
一个 JSON 样式对象数组,用于指定地图项(如道路、公园和建成区)的外观和细节级别。样式用于自定义标准 Google 基本地图。
styles
参数仅在地图类型为roadmap
时有效。如需了解完整的样式语法,请参阅样式参考。overlay
一个布尔值,用于指定是将
layerTypes
渲染为单独的叠加层,还是与基础图像结合使用。如果为true
,系统不会显示基本地图。如果您未定义任何layerTypes
,系统会忽略此值。
例如,请求具有 layerRoadmap
图层且 overlay
设置为 false
的 satellite
地图类型会导致图块等效于 Maps JavaScript API 中使用的 hybrid
地图类型(左侧图片)。overlay
设置为 true
的相同地图和图层类型会生成具有地图叠加层的透明图块,并适当地设置样式以便叠加在卫星图像上(右图)。
overlay :false |
overlay :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
- 一个字符串,包含令牌过期的时间(以秒为单位),自纪元起算。会话令牌的有效期为自创建之日起两周,但此政策可能会发生更改,恕不另行通知。
tileWidth
- 图块的宽度(以像素为单位)。
tileHeight
- 图块的高度(以像素为单位)。
imageFormat
- 图片格式,可以是
png
或jpeg
。