街景图块

欧洲经济区 (EEA) 开发者

街景图块示例

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

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

您可以将采集的街景级图像图块拼接在一起，以创建逼真的全景效果。您还可以查询一组位置（例如路线）的最多 100 个全景图片 ID，并获取有关相机位置的更深入的元数据。

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

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

  1. 获取会话令牌。请务必将 mapType 的值设置为 streetview。

  2. 使用会话令牌获取一个或多个地理位置的全景图片标识符 (panoId)。

  3. 使用 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 提供有关指定全景的详细信息。详细信息包括相关地址，以及指向相邻全景照片的链接。

您可以通过将一个或多个地理位置的坐标 (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 请求会返回一个包含 panoIds 数组的 JSON 对象。该数组包含全景 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 是临时性的，因此建议您在初始的 Street View 元数据请求中传递一组坐标和一个 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 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 时，整个全景图片会调整为尺寸为 tileWidthxtileHeight 的图块。由于全景照片在 x 维度上更大，因此图块在 y 维度上会包含空白空间：

缩放级别 0

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

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