街景图像元数据
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
简介
Street View Static API 元数据请求可提供有关街景全景图片的数据。借助元数据，您可以了解指定位置是否有街景图片，还可以通过编程方式访问经纬度坐标、全景 ID、照片拍摄日期以及图片的版权信息。通过访问此元数据，您可以自定义应用中的错误行为。
注意： 日期字段的值可能会有所不同：
日期字段对于不同的全景照片可以具有不同的粒度。
例如，某些全景照片的日期字段包含年份和月份，而其他全景照片的日期字段仅包含年份。
如果没有数据，则省略日期字段。
Street View Static API 元数据请求免费提供。请求元数据时不会消耗配额。
只有在使用 Street View Static API 加载图片时，才会
消耗配额 。
在发出街景图像元数据请求时，全景图像的精确度为 50 米。
访问图像元数据
街景图像元数据请求是一个 HTTP 网址，其格式如下：
https://maps.googleapis.com/maps/api/streetview/metadata?parameters 注意 ：元数据请求必须使用 https:// 协议。依照网址的标准，所有参数都使用“与”符号 (&) 分隔。
元数据请求接受与 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 已被删除，需要刷新。
保存用于获取全景图片 ID 的位置地址或纬度和经度坐标，以便在需要时进行刷新。
当您检测到全景图片 ID 发生变化时，请使用原始位置地址或经纬度坐标再次搜索该位置附近的全景图片，并获取新的全景图片 ID。
注意 ： 由于街景图像会定期刷新，并且每次拍摄照片的位置可能略有不同，因此在更新图像或全景图片 ID 时，给定的全景图片 ID 可能会捕捉到不同的全景图片。 您可以在元数据请求中添加以下参数：size、heading、fov 和 pitch。请注意，这些参数不会影响全景图片的相关数据，也不会影响找到的全景图片。
该 API 允许包含与影像请求 相同的参数，以便更轻松地构建与特定影像请求相关的元数据请求，但对于元数据请求，该 API 会忽略可选参数及其值。如需了解如何使用这些参数，请参阅 Street View 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 状态代码
元数据响应对象中的 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 支持页面 。
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可 获得了许可，并且代码示例已根据 Apache 2.0 许可 获得了许可。有关详情，请参阅 Google 开发者网站政策 。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-08-29。
[null,null,["最后更新时间 (UTC)：2025-08-29。"],[[["\u003cp\u003eThe Street View Static API metadata request provides data about Street View panoramas, such as location, date, and panorama ID, without consuming quota.\u003c/p\u003e\n"],["\u003cp\u003eYou need to provide either a \u003ccode\u003elocation\u003c/code\u003e (address or coordinates) or a \u003ccode\u003epano\u003c/code\u003e ID along with your API key to make a metadata request.\u003c/p\u003e\n"],["\u003cp\u003eThe response is in JSON format and includes the status of the request (e.g., \u003ccode\u003eOK\u003c/code\u003e, \u003ccode\u003eZERO_RESULTS\u003c/code\u003e, \u003ccode\u003eNOT_FOUND\u003c/code\u003e).\u003c/p\u003e\n"],["\u003cp\u003ePanorama IDs can change over time, so it's recommended to save the location information to refresh the ID when necessary.\u003c/p\u003e\n"],["\u003cp\u003eWhile optional parameters like \u003ccode\u003esize\u003c/code\u003e, \u003ccode\u003eheading\u003c/code\u003e, \u003ccode\u003efov\u003c/code\u003e, and \u003ccode\u003epitch\u003c/code\u003e are accepted, they do not affect the returned metadata.\u003c/p\u003e\n"]]],["The Street View Static API metadata requests provide panorama data, including location coordinates, panorama ID, photo date, and copyright. These requests are free and don't consume quotas. To access metadata, send an HTTP URL request with required parameters: either a `location` (address or coordinates) or `pano` (panorama ID), plus an API `key` and `signature`. If a panorama ID returns `ZERO_RESULTS`, refresh it using the original location. The response, in JSON, includes a `status` field indicating success or failure.\n"],null,["# Street View Image Metadata\n\nIntroduction\n------------\n\nThe Street View Static API metadata requests provide data about Street\nView panoramas. Using the metadata, you can find out if a Street View image\nis available at a given location, as well as getting programmatic access to\nthe latitude and longitude coordinates, the panorama ID, the date the photo was\ntaken, and the copyright information for the image. Accessing this\nmetadata lets you customize error behavior in your application.\n| **Note:** The value of the date field can vary:\n|\n| - The date field can have a different granularity for different panoramas. For example, the date field for some panoramas contains a year and month, while for others it contains just the year.\n| - The date field is omitted if no data is available.\n\nStreet View Static API metadata requests are available at no\ncharge. No quota is consumed when you request metadata.\n[Quota is only consumed](/maps/documentation/streetview/usage-limits) when you load an image using the\n[Street View Static API](/maps/documentation/streetview/overview).\n\nWhen making Street View imagery metadata requests, the panorama imagery\nis accurate to 50 meters.\n\nAccess the imagery metadata\n---------------------------\n\nA Street View image metadata request is an HTTP URL of the following form: \n\n```html\nhttps://maps.googleapis.com/maps/api/streetview/metadata?parameters\n```\n| **Note** : the **https://** protocol is required for metadata requests.\n\nAs is standard in URLs, all parameters are separated using the ampersand\n(\\&) character.\n\n### Required parameters for metadata requests\n\nThe metadata requests accept the\n[same URL parameters](/maps/documentation/streetview/overview#url_parameters)\nas the Street View Static API imagery requests, although only\nthe following parameters are required:\n\nEither:\n\n- `location` --- can be either a text string (such as `Chagrin Falls, OH`) or a comma-separated pair of latitude and longitude coordinates (`40.457375,-80.009353`).\n\nOr:\n\n- `pano` --- a specific panorama ID. Panoramas may change IDs over time, so don't persist this ID. Instead, save the location address or latitude and longitude coordinates so you can refresh the panorama ID. For details, see [Refresh deleted panorama IDs](#refresh-pano).\n\nAs well as:\n\n- `key` and `signature` --- the API key is required to authenticate the request. The digital signature is also required in certain instances, and always recommended. For more information, see [Get a Key and Signature](/maps/documentation/streetview/get-api-key).\n\nYour metadata request, with only required parameters, looks like this: \n\n```html\nhttps://maps.googleapis.com/maps/api/streetview/metadata?location=&key=YOUR_API_KEY&signature=\u003cYOUR_SIGNATURE\u003e\n```\n\nor like this: \n\n```html\nhttps://maps.googleapis.com/maps/api/streetview/metadata?pano=&key=YOUR_API_KEY&signature=\u003cYOUR_SIGNATURE\u003e\n```\n\n### Refresh deleted panorama IDs\n\nIf you attempt to retrieve a panorama ID and get either `ZERO_RESULTS` or\nno value, then the panorama ID has been deleted and needs to be refreshed.\n\n1. Save the location address or latitude and longitude coordinates you used to\n get a panorama ID so you can refresh when needed.\n\n2. When you detect that a panorama ID has changed, use the original location\n address or latitude and longitude coordinates to search again for the nearest\n panoramas to that location and get a new panorama ID.\n\n| **Note:** Because Street View imagery is periodically refreshed, and photographs may be taken from slightly different positions each time, a given panorama ID may snap to a different panorama when imagery or the panorama ID is updated.\n\n### Optional parameters for metadata requests\n\nYou can include the following parameters in your metadata request: `size`,\n`heading`, `fov`, and `pitch`. Note that these parameters don't influence\nthe data about the panorama, or which panorama is found.\nThe API allows the inclusion of the same parameters as the\n[imagery request](/maps/documentation/streetview/overview#url_parameters)\nto make it easier to construct a metadata request related to a specific imagery\nrequest, but for metadata requests, the API ignores the optional parameters and\ntheir values. For information about using these parameters, see the\n[Street View Static API developer's guide](/maps/documentation/streetview/overview#url_parameters).\n\nResponse format\n---------------\n\nMetadata responses are returned in JSON format only.\n\nExamples\n--------\n\n#### Example 1: Panorama found\n\nThe following URLs successfully request the metadata and image of the same\npanorama.\n\nMetadata request and response \n\n```html\nhttps://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\n``` \n\n```scdoc\n{\n \"copyright\" : \"© 2017 Google\",\n \"date\" : \"2016-05\",\n \"location\" : {\n \"lat\" : 48.85783227207914,\n \"lng\" : 2.295226175151347\n },\n \"pano_id\" : \"tu510ie_z4ptBZYo2BGEJg\",\n \"status\" : \"OK\"\n}\n```\n\nImagery request and response, where the missing image is expected. \n\n```html\nhttps://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\n```\n\n#### Example 2: Panorama not found\n\nThe following URLs request the metadata and image for a panorama that\ncouldn't be found at or near the specified location.\n\n**Metadata request and response** \n\n```html\nhttps://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\n``` \n\n```scdoc\n{\n \"status\" : \"ZERO_RESULTS\"\n}\n```\n\n**Imagery request and response** \n\n```html\nhttps://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\n```\n\nStatus codes\n------------\n\nThe `status` field within the metadata response object contains the status of\nthe request, and may contain debugging information to help you troubleshoot\nwhy the Street View request is not working. The `status` field may contain\nthe following values:\n\n| Status | Description |\n|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `\"OK\"` | Indicates that no errors occurred; a panorama is found and metadata is returned. |\n| `\"ZERO_RESULTS\"` | Indicates that no panorama could be found near the provided location. This response can occur if you provide a non-existent or invalid panorama ID. See \\[Refresh deleted panorama IDs\\](#refresh-pano). |\n| `\"NOT_FOUND\"` | Indicates that the address string provided in the `location` parameter couldn't be found. This message may occur if a non-existent address is given. |\n| `\"OVER_QUERY_LIMIT\"` | Indicates that you have exceeded your daily quota or per-second quota for this API. |\n| `\"REQUEST_DENIED\"` | Indicates that your request was denied. This message may occur if you did not [authorize](/maps/documentation/streetview/get-api-key) your request, or if the Street View Static API is not activated in the Google Cloud console project containing your API key. |\n| `\"INVALID_REQUEST\"` | Generally indicates that the query parameters (address, latitude and longitude coordinates, or components) are missing. |\n| `\"UNKNOWN_ERROR\"` | Indicates that the request couldn't be processed due to a server error. This issue is often temporary. The request may succeed if you try again. |\n\nMore information\n----------------\n\nFor more information on using the Street View Static API, or\nother Google Maps API products, be sure to check out the Maps API\n[Support page](/maps/support)."]]
