街景请求和响应

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

街景图像请求是采用以下格式的 HTTP 网址:

https://maps.googleapis.com/maps/api/streetview?parameters

系统会使用相关请求的参数指定图像。根据网址的标准,所有参数均使用和号字符 (&) 进行分隔。下面列出了允许的参数及其可能的值。

必需参数

采用以下任一方式:

  • location 可以是文本字符串(例如 Chagrin Falls, OH)或纬度/经度值 (40.457375,-80.009353),并且应进行网址编码,因此在请求签名之前,应将“City Hall, New York, NY”这样的地址转换为“City+Hall,New+York,NY”。Street View Static API 将贴靠离该位置最近拍摄的全景图片。提供地址文本字符串后,该 API 可能会使用其他相机位置,以更好地显示指定位置。提供纬度/经度后,该 API 会在半径为 50 米的范围内搜索最靠近此位置的照片。由于街景图像会定期刷新,并且照片的拍摄位置可能会每次略有不同,因此在图像更新时,您的 location 可能会贴靠到不同的全景图片。

或者:

  • pano 是具体的全景图片 ID。这些值通常很稳定。

以及:

  • size 用于指定图像的输出大小(以像素为单位)。大小指定为 {width}x{height} - 例如,size=600x400 会返回一张宽 600 像素、高 400 像素的图片。
  • 借助 key,您可以在 Google Cloud Console 中监控应用的 API 使用情况,并确保 Google 可以在必要时就应用相关事宜与您联系。如需了解详情,请参阅获取密钥和签名

可选参数

  • signature(推荐)是一种数字签名,用于验证所有使用您的 API 密钥生成请求的网站是否获得了相应授权。不包含数字签名的请求可能会失败。如需了解详情,请参阅获取密钥和签名

    注意:对于之前的 Google Maps Platform 高级计划客户,必须提供数字签名。详细了解高级计划客户的身份验证参数

  • heading 表示相机的罗盘方向。接受的值范围为 0360(这两个值都表示北,90 表示东,180 表示南)。如果未指定航向,系统将计算出一个值,将相机从拍摄最接近照片的点指向指定 location
  • fov默认值为 90)决定了图片的水平视野。视野以度数表示,允许的最大值为 120。 处理固定尺寸的视口时(与处理固定尺寸的街景图像时一样),视野本质上表示变焦,数字越小表示变焦级别越高。


    各种视野的屏幕截图,显示了水族馆内的天花板、墙壁、地板和水箱窗口。 近景镜头的屏幕截图,显示了水族馆内街景照片的放大细节。
    (左侧:fov=120;右侧:fov=20

  • pitch(默认为 0)指定相机相对于街景拍摄车的向上或向下倾斜角度()。该角度通常(但并不总)是水平的。正值表示相机向上倾斜(90 度表示相机垂直向上);负值表示相机向下倾斜(-90 表示相机垂直向下)。
  • radius默认值为 50)设置半径(以米为单位),要在此范围内搜索全景,以给定纬度和经度为中心。有效值为非负整数。
  • return_error_code 表示 API 是否应在找不到图片 (404 NOT FOUND) 时返回错误代码,或者在响应无效请求 (400 BAD REQUEST) 时返回错误代码。有效值为 truefalse。如果设置为 true,系统会返回一条错误消息以替换通用的灰色图片。这样就无需进行单独的调用来检查映像可用性。
  • source(默认为 default)将街景搜索限制为所选来源。有效值包括:
    • default 使用默认街景来源;搜索不限于特定来源。
    • outdoor将搜索范围限制为户外集合。室内搜索结果不会显示在搜索结果中。请注意,指定位置可能不存在室外全景图片。另请注意,搜索只能确定可能处于室内或室外的全景图片。例如,系统不会返回 PhotoSpheres,因为不知道室内还是室外。

这是一个请求示例。

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=46.414382,10.013988&heading=151.78&pitch=-0.76&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
显示电子化铁轨的街道观景点照片的屏幕截图。

无图像可用

对于没有街景图像的地点,Street View Static API 会返回灰色的通用图片,并显示“抱歉,我们这里没有图片”。示例如下:

指定位置无可用图像时显示的通用图片的屏幕截图。背景为浅棕色,并显示“抱歉,此处没有图像”的文本。
图:指定位置无可用图像时显示的通用图像。

仅显示有效图片

为避免显示通用图片,并确保您的网页仅显示有效的 Street View Static API 图片,请遵循以下建议:

  • return_error_code 参数设置为 true。 这会使 Street View Static API 在没有可用于指定位置的图片时返回 404 NOT FOUND 错误,而不是通用的灰色图片。
  • 在发送请求之前,请求街景图片元数据以确定指定位置是否有可用图像。