街景图像元数据

简介

Street View Static API 元数据请求可提供有关街景全景图片的数据。使用元数据，您可以了解给定位置是否有街景图像，以及通过程序化方式获取经纬度坐标、全景 ID、照片拍摄日期和图像的版权信息。通过访问此元数据，您可以自定义应用中的错误行为。

街景 Static API 元数据请求免费提供。请求元数据时不会消耗配额。 只有在您使用Street View Static API 加载图片时，才会消耗配额。

发出街景图像元数据请求时，全景图像的精确度为 50 米。

访问图像元数据

街景图像元数据请求是一个 HTTP 网址，其格式如下：

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

依照网址的标准，所有参数都使用“与”符号 (&) 分隔。

元数据请求的必需参数

元数据请求接受与 Street View Static API 图像请求相同的网址参数，但只有以下参数是必需的：

采用以下任一方式：

  • location - 可以是文本字符串（例如 Chagrin Falls, OH），也可以是以逗号分隔的纬度和经度坐标对 (40.457375,-80.009353)。

或者：

  • pano - 特定全景图片 ID。全景图片的 ID 可能会随时间而变化，因此请勿保留此 ID。而应保存位置地址或经纬度坐标，以便刷新全景图片 ID。如需了解详情，请参阅刷新已删除的全景图片 ID。

以及：

  • key 和 signature - 需要使用 API 密钥对请求进行身份验证。在某些情况下，数字签名也是必需的，并且始终建议使用。如需了解详情，请参阅获取密钥和签名。

您的元数据请求（仅包含必需参数）如下所示：

https://maps.googleapis.com/maps/api/streetview/metadata?location=&key=YOUR_API_KEY&signature=<YOUR_SIGNATURE>

或如下所示：

https://maps.googleapis.com/maps/api/streetview/metadata?pano=&key=YOUR_API_KEY&signature=<YOUR_SIGNATURE>

刷新已删除的全景图片 ID

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

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

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

元数据请求的可选参数

您可以在元数据请求中包含以下参数：size、heading、fov 和 pitch。请注意，这些参数不会影响全景图片的相关数据，也不会影响找到的全景图片。该 API 允许添加与图像请求相同的参数，以便更轻松地构建与特定图像请求相关的元数据请求，但对于元数据请求，该 API 会忽略可选参数及其值。如需了解如何使用这些参数，请参阅 街景 Static API 开发者指南。

回答格式

元数据响应只以 JSON 格式返回。

示例

示例 1：找到全景图片

以下网址可成功请求同一全景图片的元数据和图片。

元数据请求和响应

https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
 
{
   "copyright" : "© 2017 Google",
   "date" : "2016-05",
   "location" : {
      "lat" : 48.85783227207914,
      "lng" : 2.295226175151347
   },
   "pano_id" : "tu510ie_z4ptBZYo2BGEJg",
   "status" : "OK"
}

图片请求和响应，其中应包含缺失的图片。

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
埃菲尔铁塔

示例 2：未找到全景图片

以下网址请求获取在指定位置或其附近找不到的全景图片的元数据和图片。

元数据请求和响应

https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
 
{
   "status" : "ZERO_RESULTS"
}

图像请求和响应

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
No Imagery Here Placeholder

状态代码

元数据响应对象中的 status 字段包含请求的状态，可能还包含调试信息，以帮助您排查街景请求无法正常工作的原因。status 字段可能包含以下值：

状态 说明
"OK" 表示未出现任何错误；已找到全景图片并返回了元数据。
"ZERO_RESULTS" 表示在提供的位置附近找不到全景图片。 如果您提供的全景 ID 不存在或无效，则可能会出现此响应。 请参阅 [刷新已删除的全景 ID](#refresh-pano)。
"NOT_FOUND" 表示找不到 location 参数中提供的地址字符串。如果提供了不存在的地址，则可能会出现此消息。
"OVER_QUERY_LIMIT" 表示您已超出此 API 的每日配额或每秒配额。
"REQUEST_DENIED" 表示您的请求已遭拒。如果您未授权请求，或者包含 API 密钥的 Google Cloud 控制台项目中未激活 Street View Static API，则可能会出现此消息。
"INVALID_REQUEST" 通常表示缺少查询参数（地址、经纬度坐标或组件）。
"UNKNOWN_ERROR" 表示因服务器错误而无法处理该请求。 此问题通常是暂时性的。如果您再试一次，该请求可能会成功。

更多信息

如需详细了解如何使用 Street View Static API 或其他 Google 地图 API 产品，请务必查看地图 API 支持页面。