街景请求和响应

欧洲经济区 (EEA) 开发者

街景图片请求是采用以下格式的 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 表示相机的罗盘方向。可接受的值介于 0360 之间(这两个值均表示“北”,值 90 表示“东”,值 180 表示“南”)。如果您没有指定罗盘方向,系统会计算出一个值,以便使相机从进行最近距离的拍摄时所处的那个点朝向指定的 location
  • fov(默认值为 90) 用于确定图像的水平视角(以度为单位),允许的最大值为 120。 处理固定大小的视口(例如固定大小的街景图像)时,视野实际上表示缩放比例,数值越小表示缩放比例越高。


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

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

以下是示例请求。

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 错误,而不是通用的灰色图像。
  • 请求街景图像元数据,以确定在发送请求之前指定位置是否有可用的图像。