将会话令牌与 Map Tiles API 搭配使用

会话令牌是一段数据 (UUID)，在 REST 调用中用于标识会话（一系列相关的消息交换）。您必须在所有 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

基础地图的类型。这个值可以是以下值之一：

roadmap
标准的 Google 地图绘制地图图块。
satellite
卫星图像。
terrain
地形图像。选择 terrain 作为地图类型时，您还必须添加 layerRoadmap 图层类型（相关说明见可选字段部分）。
streetview
街景全景图。如需了解详情，请参阅街景图块。
language

IETF 语言标记，用于指定用于在图块上显示信息的语言。例如，en-US 指定了美国英语。

region

通用语言区域数据代码库区域标识符（两个大写字母），表示用户的实际位置。例如 US。

可选字段

imageFormat
指定要返回的文件格式。有效值为 jpeg 或 png。 JPEG 文件不支持透明度，因此不建议将其用于图块叠层。如果您未指定 imageFormat，系统会自动为功能块选择最佳格式。
scale

放大地图元素（例如道路标签）的大小，同时保持默认图块的图块大小和覆盖区域。增加缩放级别后，地图上的标签数量也会减少，从而降低混乱程度。以下值是有效的 scale 值：

  • scaleFactor1x：默认值。
  • scaleFactor2x：将标签大小加倍并移除次要特征标签。
  • scaleFactor4x：四倍标签大小并移除次要特征标签。

以下示例演示了缩放地图元素的效果。

缩放系数 1x 缩放比例 2x
显示缩放比例为 1x 的地图 显示缩放比例为 2x 的地图
highDpi
指定是否返回高分辨率图块。如果增大缩放比例，系统会使用 highDpi 来增大功能块的大小。通常，增加缩放比例会将生成的功能块放大为相同大小的图片，从而降低质量。使用 highDpi 后，生成的大小也会增加，同时保持质量。DPI 是每英寸的点数，高 DPI 表示功能块的每英寸点数高于正常值。如果为 true，则将 x 和 y 尺寸中的像素数乘以缩放比例（即 2x 或 4x）。功能块的覆盖区域保持不变。此参数仅适用于 2x 或 4x 的 scale 值。对 1x 比例图块没有影响。
缩放系数 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
一个字符串，其中包含令牌到期的时间（与公元纪年之间相隔的秒数）。会话令牌的有效期为自创建起的两周，但此政策可能会随时变更，恕不另行通知。
tileWidth
功能块的宽度（以像素为单位）。
tileHeight
图块的高度（以像素为单位）。
imageFormat
图片格式，可以是 png 或 jpeg。