街景图块

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

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

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

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

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

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

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

3. 使用 panoId 搜索响应中的全景图片标识符获取以下内容：

   1. 街景元数据。您还可以通过传递一组坐标和半径来获取街景元数据。

   2. 街景缩略图。

   3. 街景图块。

街景方法

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

街景 panoId 搜索

您可以通过将一个或多个地理位置的坐标 (lat, lng) 传递给 panoIds 方法，找到这些地理位置的 360 度全景图标识符。请求正文是一个 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 是瞬时 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 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 表示最大视野。

街景图块响应

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

在缩放级别为 0 时，整个全景图将调整为尺寸等于 tileWidth x tileHeight 的图块。由于全景图的 x 尺寸较大，图块将在 y 尺寸中包含空白：

在缩放级别为 5 时，将使用全尺寸全景图并将其分成多个图块。

版权信息

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