街景图块与 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 个营业地点。返回带图像的所有位置的全景图 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"
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 表示最大视野。
缩放级别 | 大致视野范围 |
---|---|
0 | 360° |
1 | 180° |
2 | 90° |
3 | 45° |
4 | 22.5° |
5 | 11.25° |
街景图块响应
成功的街景图块请求将返回一个具有您在 createSession
响应中指定的格式和大小的图像。
缩放级别为零时,整个全景图片的尺寸将调整为尺寸为 tileWidth
x tileHeight
的图块。由于全景图的 x 尺寸较大,图块将在 y 尺寸中包含空白:
缩放级别为 5 时,将使用完整尺寸的全景图片,并将其分为多个图块。
版权信息
您必须在每个街景全景图中显示版权信息。要显示的字符串可能因全景图的不同而有所差异。如需获取版权信息,您必须请求街景元数据,然后才能引用响应的 copyright
字段。如需了解详情,请参阅数据提供方说明。