簡介
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=
或如下所示:
https://maps.googleapis.com/maps/api/streetview/metadata?pano=&key=YOUR_API_KEY&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" |
表示您的要求遭拒。如果您未授權要求,或包含 API 金鑰的 Google Cloud 控制台專案未啟用 Street View Static API,就可能出現這則訊息。 |
"INVALID_REQUEST" |
通常表示缺少查詢參數 (地址、經緯度座標或元件)。 |
"UNKNOWN_ERROR" |
表示伺服器發生錯誤,因此無法處理要求。這通常是暫時性的問題。如果您再試一次,可能會成功進行要求。 |
更多資訊
如要進一步瞭解如何使用 Street View Static API 或其他 Google Maps API 產品,請務必查看 Maps API 支援頁面。