街景图块

欧洲经济区 (EEA) 开发者

街景图块示例

街景图块与 2D 图块类似，但其中包含在街道层级拍摄的全景图像。利用街景功能，您可以身临其境地领略世界各地的地标、探索自然奇观、参观博物馆和竞技场，还可以逛逛大街小巷的餐馆和小商店等。通过此 API 端点，您可以访问：

Google 地图街景图块
街景元数据
街景缩略图

您可以将街道层级拍摄的图像图块拼接在一起，营造出逼真的全景效果。此外，您还可以针对一组地点（例如路线）查询最多 100 个全景图片 ID，并获取有关相机位置的更深入的元数据。

拼接街景图块需要使用查看器。例如，街景自定义全景图片查看器。

获得 API 密钥后，您可以按照以下步骤访问街景图像。

获取会话令牌。请务必将 mapType 的值设置为 streetview。
使用会话令牌来获取一个或多个地理位置的全景图片标识符 (panoId)。
使用 panoId 搜索响应中的全景图片标识符获取：
1. 街景元数据。您还可以通过传递一组坐标和一个半径来获取街景元数据。
2. 街景缩略图。
3. 街景图块。

街景方法

您可以调用以下四种方法之一来访问街景图像和元数据。

方法	说明
`https://tile.googleapis.com/v1/streetview/tiles`	返回各个街景图块。您可以检索六个缩放级别的街景图块：从 512 像素到 13,312 像素。
`https://tile.googleapis.com/v1/streetview/panoIds`	让您能够批量搜索最多 100 个地点。返回所有包含图像的地点对应的全景图片 ID。
`https://tile.googleapis.com/v1/streetview/thumbnail`	返回街景场景的缩略图 JPEG 图像。让您能够提供航向、俯仰角、尺寸和视野范围。最小尺寸为 16x16 像素。最大尺寸为 250x600 像素。
`https://tile.googleapis.com/v1/streetview/metadata`	提供有关指定全景图片的详细信息。详细信息包括相关地址以及指向相邻全景图片的链接。

街景 panoIds 搜索

您可以通过将一个或多个地理位置的坐标 (lat、lng) 传递给 panoIds 方法来查找这些地理位置的全景图片标识符。请求正文是一个 JSON 对象，其中包含 locations 数组，还可以选择性地包含 radius，如以下 JSON 代码示例所示。

curl -X POST -d '{
  "locations": [
    {"lat": -33.883837, "lng": 151.209307},
    {"lat": -33.883700, "lng": 151.210307},
    {"lat": 0, "lng": 0}
  ],
  "radius": 50
}' \
-H 'Content-Type: application/json' \
"https://tile.googleapis.com/v1/streetview/panoIds?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY"

locations: locations 数组必须包含至少一组坐标值，但您可以包含更多坐标值，最多 100 组。
radius: radius 值（以米为单位）定义了给定位置周围的圆的半径，用于指定要在多大半径范围内搜索全景图片。默认值为 50 米。

PanoId 响应

Map Tiles API 会尝试查找距离每个地点最近的全景图片，然后返回这些全景图片的全景图片 ID。成功的 panoIds 请求会返回一个 JSON 对象，其中包含 panoIds 数组。该数组包含一个全景图片 ID 列表，这些 ID 的顺序与您请求的顺序相同。如果 Map Tiles API 找不到您请求的地点对应的任何全景图片，则系统会在数组中相应地点的位置返回一个空字符串。如需查看示例，请参阅以下 JSON 代码。

{
  "panoIds": [
    "ACfH-n2HcBvRry_3oc9grw",
    "f5DJZatBAAAXHlooS2wKbw",
    ""
  ]
}

您可以使用 panoIds 执行以下操作：

请求街景元数据
请求街景缩略图
请求街景图块

街景元数据

街景元数据请求用于检索有关全景图片的信息。街景元数据请求是 HTTPS GET 请求。您可以通过以下两种方式之一检索有关全景图片的信息：

如果您传递 pano_id，则 Map Tiles API 会返回该全景图片的元数据。
但如果您传递 lat 和 lng，则 Map Tiles API 会返回给定搜索半径内最近的全景图片的元数据。

传递一组坐标和一个半径

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=lat&lng=lng&radius=meters"

由于全景图片 ID 是临时的，因此我们建议您在初始街景元数据请求中传递一组坐标和一个 radius 值。如需查看示例，请参阅以下代码段。

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=47.62066&lng=-122.34923&radius=50"

传递街景图像的 panoId

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

元数据响应

以下 JSON 代码是典型元数据响应的示例。

{
 "panoId": "rZ9KeTyhA11i0VppYNzsSg",
 "lat": 37.420864219339165,
 "lng": -122.08446528377291,
 "imageHeight": 6656,
 "imageWidth": 13312,
 "tileHeight": 512,
 "tileWidth": 512,
 "heading": 94.35,
 "tilt": 88.39652,
 "roll": 1.7181772,
 "imageryType": "outdoor",
 "date": "2023-01",
 "copyright": "© 2023 Google",
 "reportProblemLink": "https://cbks0.googleapis.com/cbk?output=report&panoid=rZ9KeTyhA11i0VppYNzsSg&cb_client=api&cbp=1,0,,0,0&hl=en-US&gl=us",
 "addressComponents": [
  {
   "longName": "United States",
   "shortName": "United States",
   "types": [
    "country"
   ]
  },
  {
   "longName": "Mountain View, California",
   "shortName": "Mountain View, California",
   "types": [
    "locality"
   ]
  },
  {
   "longName": "Charleston Rd",
   "shortName": "Charleston Rd",
   "types": [
    "route"
   ]
  },
  {
   "longName": "1635",
   "shortName": "1635",
   "types": [
    "street_number"
   ]
  }
 ],
 "links": [
  {
   "panoId": "Yw4pqzA4FEq1qs-BwZSvSQ",
   "heading": 274.47998046875,
   "text": "Charleston Rd"
  },
  {
   "panoId": "1cODYwFRw1aZ45IignDIMw",
   "heading": 94.47999572753906,
   "text": "Charleston Rd"
  }
 ]
}

以下列表包含响应正文中字段的定义。

panoId: 此全景图片的唯一 ID。请勿依赖于全景图片 ID 在单个用户会话之外保持有效。
lat、lng: 全景图片的坐标（纬度和经度）。这些值可能与您在请求中传递的坐标不同，因为位置会“吸附”到最近的全景图片。
imageHeight、imageWidth: 拼接的全景图像的尺寸。
tileHeight、tileWidth: 单个全景图片图块的尺寸。
heading: 罗盘航向角，以从北顺时针旋转的度数表示。返回的航向角在 [0,360] 范围内，其中 0 表示正北。
tilt: 全景图片的倾斜度，以从全景图片的南极到地平线的度数表示。返回的值在 [0, 180] 范围内。值为 90 度表示地平线已与全景图片的赤道对齐。
roll: 围绕视线顺时针旋转的角度，用于将全景图片的地平线调平。返回的值在 [0, 360] 范围内。
imageryType: 表示图像的类型。有效值为 indoor 和 outdoor。
date: 拍摄图像的日期。并非所有图像都有日期数据。但如果有日期数据，此字段会包含年份 (YYYY) 和月份 (MM) 的组合。例如：2023-05 或 2024。
copyright: 您必须显示为归属信息的版权文本，并将其与街景图像一起显示。
reportProblemLink: 供用户报告此街景图块存在的问题的超链接。您必须在图像的右下角显示此超链接，并且必须包含链接文本，例如“报告此图像存在的问题”。
addressComponent: 结构化地理编码其中包含有关全景图片地址的详细信息。如需了解详情，请参阅 Geocoding 请求和响应 Geocoding API 文档中的内容。
links: 指向此全景图片的链接的全景图片 ID 列表。还包含找到链接的航向。例如，如果航向为 180°，则链接的全景图片位于当前全景图片的正南方。请注意，由于全景图片 ID 的临时性，您不应依赖于这些 ID 在单个用户会话之外保持有效。

街景缩略图

您可以请求 thumbnail 格式的街景图像。缩略图是未分块的图像，具有用户定义的大小、航向、俯仰角和视野范围。缩略图图像的分辨率低于图块，文件大小也较小。您可以通过向 thumbnail 端点发送 GET 请求来发出缩略图请求，如以下代码原型所示。

curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId&height=FROM_16_TO_250&width=FROM_16_TO_600&pitch=FROM-90_TO_90&yaw=FROM-360_TO_360&fov=FROM_30_TO_120"

请看以下代码示例，该示例会下载在加拿大惠斯勒拍摄的街景图像的缩略图。

curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=Zzl28rqGJgaL2IdkUleP8A&height=200&width=200&pitch=0&yaw=250&fov=80" --output /tmp/example_thumbnail.png

必需参数

panoId: 您想要的缩略图的唯一 ID。您可以从 panoIds 端点或从 metadata 端点获取全景图片 ID 值，这两个端点都接受地理坐标，并返回相应的 panoId。
session: 有效的会话令牌。
key: 您的 API 密钥。

可选参数

height: 指定缩略图的高度（以像素为单位），范围为 16 像素到 250 像素。如果您未指定高度，则高度默认为允许的最大值 250 像素。如果您指定的值超出范围，则缩略图会“吸附”到最接近的有效值。
width: 指定缩略图的宽度（以像素为单位），范围为 16 像素到 600 像素。如果您未指定宽度，则宽度默认为允许的最大值 600 像素。如果您指定的值超出范围，则缩略图会“吸附”到最接近的有效值。
pitch: 指定相机沿垂直轴的角度。有效值在 -90 到 90（含）范围内。默认值为 0。
yaw: 指定相机沿水平轴的方向。有效值在 -360 到 360（含）范围内。默认值为 0。
fov: 指定水平视野范围，以度为单位表示，最大值为 120。在处理固定大小的视口（例如固定大小的街景图像）时，视野范围表示缩放比例；值越小，缩放级别越高。默认值为 90。

街景图像图块

获得 panoId 后，您可以请求街景图像图块。图块请求是 HTTPS GET 请求。请看以下示例。

curl "https://tile.googleapis.com/v1/streetview/tiles/z/x/y?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

在此代码示例中，z 是缩放级别，而 x 和 y 是您想要的街景图块的图块坐标。街景全景图片的缩放级别必须在 [0,5] 范围内，其中 0 表示最宽的视野范围。

缩放级别	大致视野范围
0	360°
1	180°
2	90°
3	45°
4	22.5°
5	11.25°

街景图块响应

成功的街景图块请求会返回您在 createSession 响应中指定的格式和大小的图像。

成功执行 Tile 请求的结果

在缩放级别为 0 时，整个全景图片会调整为尺寸为 tileWidth x tileHeight 的图块。由于全景图片在 x 维度上较大，因此图块在 y 维度上会包含空白空间：

缩放级别 0

在缩放级别为 5 时，系统会使用全尺寸的全景图片并将其划分为图块。

版权信息

您必须在每个街景全景图片中显示版权信息。要显示的字符串可能因全景图片而异。如需获取版权信息，您必须请求街景元数据，然后可以参阅响应的 copyright 字段。如需了解详情，请参阅数据归属。