街景服務圖片中繼資料

引言

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」一文。

此外:

  • keysignature:必須使用 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 已經刪除,必須重新整理。

  1. 儲存用來取得全景 ID 的位置地址或經緯度座標,以便視需要重新整理。

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

中繼資料要求的選用參數

您可以在中繼資料要求中包含下列參數:sizeheadingfovpitch。請注意,這些參數不會影響全景相關資料,或找到的全景。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 的支援頁面