街景服務圖片中繼資料

簡介

Street View Static API 中繼資料要求會提供街景服務全景的相關資料。您可以使用中繼資料，瞭解特定位置是否有街景服務圖像，並透過程式輔助方式取得經緯度座標、全景 ID、相片拍攝日期和圖片著作權資訊。存取這類中繼資料，即可自訂應用程式中的錯誤行為。

注意： 日期欄位的值可能不盡相同：

• 日期欄位可針對不同全景設定不同的精細程度。 舉例來說，某些全景相片的日期欄位包含年和月，其他則只包含年。
• 如果沒有可用資料，系統會省略日期欄位。

街景服務 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 已刪除，需要重新整理。

1. 請儲存用於取得全景 ID 的地點地址或經緯度座標，以便在需要時重新整理。

2. 偵測到全景 ID 變更時，請使用原始位置地址或經緯度座標，再次搜尋該位置附近的全景，並取得新的全景 ID。

注意： 由於街景服務圖像會定期更新，且每次拍攝的位置可能略有不同，因此當圖像或全景 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

狀態碼

中繼資料回應物件中的 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 Maps API 產品，請務必查看 Maps API 支援頁面。