簡介
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。這通常是固定的,但全景會隨著圖像更新而改變。
此外,
key
和signature
:必須使用 API 金鑰來驗證要求。在某些情況下,系統也支援數位簽章,因此建議您一律使用。詳情請參閱「取得金鑰和簽名」一節。
中繼資料要求 (僅含必要參數),如下所示:
https://maps.googleapis.com/maps/api/streetview/metadata?location=<STRING>&key=YOUR_API_KEY&signature=<YOUR_SIGNATURE>
或像這樣:
https://maps.googleapis.com/maps/api/streetview/metadata?pano=<STRING>&key=YOUR_API_KEY&signature=<YOUR_SIGNATURE>
中繼資料要求的選用參數
您可以在中繼資料要求中加入下列參數: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 不存在或無效,就有可能發生這種情況。 |
"NOT_FOUND" |
表示找不到 location 參數中提供的地址字串。如果提供的地址不存在,就可能發生這種情形。 |
"OVER_QUERY_LIMIT" |
表示您已超過這個 API 的每日配額或每秒配額。 |
"REQUEST_DENIED" |
表示您的要求遭拒。如果您沒有授權要求,或是 Google API 控制台專案內的 API 金鑰未啟用 Street View Static API,就可能發生這種問題。 |
"INVALID_REQUEST" |
這通常表示缺少查詢參數 (地址、latlng 或元件)。 |
"UNKNOWN_ERROR" |
表示伺服器發生錯誤,因此無法處理要求。這通常是臨時狀態。如果您再試一次,可能會成功進行要求。 |
更多資訊
如要進一步瞭解如何使用 Street View Static API 或其他 Google Maps API 產品,請務必查看 Maps API 「支援」頁面。