街景服務圖片中繼資料
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
簡介
Street View Static API 中繼資料要求會提供街景服務全景的資料。您可以透過中繼資料瞭解特定位置是否有街景服務圖像，並以程式輔助方式存取圖像的經緯度座標、全景 ID、拍攝日期和著作權資訊。存取這項中繼資料可讓您自訂應用程式中的錯誤行為。
Street View 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 已遭刪除，需要重新整理。
請儲存您用來取得全景 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" |
表示您的要求遭拒。如果沒有授權要求，或是 Google Cloud 控制台專案中含有 API 金鑰，但未啟用 Street View Static API，就可能會出現這則訊息。 |
"INVALID_REQUEST" |
通常表示缺少查詢參數 (地址、經緯度座標或元件)。 |
"UNKNOWN_ERROR" |
表示伺服器發生錯誤，因此無法處理要求。
這個問題通常是暫時性的。如果您再試一次，該要求可能會成功。 |
更多資訊
如要進一步瞭解如何使用 Street View Static API 或其他 Google 地圖 API 產品，請務必查看 Maps API 支援頁面。
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-08-29 (世界標準時間)。
[null,null,["上次更新時間：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)."]]
