街景图块与 2D 图块类似，但包含在街道一级拍摄的全景图片。利用街景功能，您可以身临其境地领略世界各地的标志性建筑、探索自然奇观、参观博物馆和竞技场，还可以逛逛大街小巷的餐馆和小商店等。
通过此 API 端点，您可以访问：
- Google 地图街景图块
- 街景元数据
- 街景缩略图
您可以将从街道级别拍摄的图块图片拼接在一起，以创建逼真的全景效果。此外，您还可以针对一组地点（例如路线）查询最多 100 个全景图 ID，并获取有关相机位置的更深入的元数据。
需要使用查看器将街景图块拼接在一起。例如，街景自定义全景图片查看器。
获得 API 密钥后，您可以按照以下步骤访问街景图像。
获取会话令牌。请务必将
mapType的值设置为streetview。使用会话令牌获取一个或多个地理位置的全景图片标识符 (panoId)。
使用 panoId 搜索响应中的全景图标识符可获取以下内容：
街景方法
您可以通过调用以下四种方法之一来访问街景图片和元数据。
| 方法 | 说明 |
|---|---|
https://tile.googleapis.com/v1/streetview/tiles |
返回各个街景图块。您可以检索六种缩放级别的街景图块：从 512 像素到 13,312 像素。 |
https://tile.googleapis.com/v1/streetview/panoIds |
可让您批量搜索最多 100 个营业地点。返回包含图像的所有地理位置的 360 度全景图 ID。 |
https://tile.googleapis.com/v1/streetview/thumbnail |
返回街景场景的 JPEG 缩略图。可让您提供航向、俯仰角、尺寸和视野范围。最小尺寸为 16x16 像素。最大尺寸为 250x600 像素。 |
https://tile.googleapis.com/v1/streetview/metadata |
提供有关指定全景图的详细信息。详细信息包括相关地址和相邻全景图的链接。 |
街景 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"
locationslocations数组必须至少包含一组坐标值，但您也可以添加更多坐标值（最多 100 个）。radiusradius值（以米为单位）用于指定要在指定地点周围多大半径范围内搜索全景图片。默认值为 50 米。
PanoId 响应
Map Tiles API 会尝试查找距离每个位置最近的全景图，然后返回其全景图 ID。成功的 panoIds 请求会返回包含 panoIds 数组的 JSON 对象。该数组包含全景图 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 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 响应中指定的格式和大小的图片。
在缩放级别为零时，整个全景图会调整为尺寸为 tileWidth x tileHeight 的图块。由于全景图在 x 轴上的尺寸较大，因此图块在 y 轴上会包含空白区域：
在缩放级别 5 时，系统会使用完整尺寸的全景图并将其划分为图块。
版权信息
您必须在每个街景全景图片中显示版权信息。要显示的字符串可能会因全景图而异。如需获取版权信息，您必须请求街景元数据，然后才能参阅响应的 copyright 字段。如需了解详情，请参阅数据归因。