街景请求和响应

街景图像请求是一个 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。全景图片 ID 可能会随时间而变化，因此请勿保留此 ID。您可以改为保存位置地址或经纬度坐标，以便刷新全景图片 ID。如需了解详情，请参阅刷新已删除的全景图片 ID。

以及：

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

刷新已删除的全景图片 ID

如果您尝试检索全景图片 ID 但获得的是 ZERO_RESULTS 或没有值，则表示全景图片 ID 已被删除，需要刷新。

  1. 保存您用于获取全景图片 ID 的位置地址或经纬度坐标，以便在需要时刷新。

  2. 当您检测到全景图片 ID 发生更改时，使用原始位置地址或经纬度坐标重新搜索距离该位置最近的全景图片，并获取新的全景图片 ID。

可选参数

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

    注意：对于以前的 Google Maps Platform 专业版方案客户，数字签名是必需的。详细了解专业版方案客户的身份验证参数。

  • heading 表示相机的罗盘方向。可接受的值介于 0 到 360 之间（这两个值均表示北，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) 时返回错误代码。有效值为 true 和 false。如果设置为 true，则会返回错误消息，代替一般的灰色图片。这样您就无需单独调用来检查映像可用性。
  • source（默认值为 default）将街景搜索限制为选定来源。有效值包括：
    • default，使用默认街景来源；搜索范围不限于特定来源。
    • outdoor，仅搜索室外全景图片。室内照片集不会显示在搜索结果中。请注意，指定位置可能不存在室外全景图片。另请注意，搜索仅会返回能确定位于室内还是室外的全景图片。例如，系统不会返回 PhotoSphere，因为我们不知道它们是位于室内还是室外。

这是一个示例请求。

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 会返回一张灰色的通用图片，并显示文本“Sorry, we have no images here.”，如以下示例所示：

指定位置没有可用的图像时显示的通用图像的屏幕截图。背景是浅棕色，并且显示文字“抱歉，我们这里没有图像”。
图：指定位置没有可用的图像时显示的通用图像。

仅显示有效的图片

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

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