街景服務要求與回應

「街景服務圖片」要求是 HTTP 網址，格式如下：

https://maps.googleapis.com/maps/api/streetview?parameters

圖像是使用 request 參數而設定的。依照網址標準，所有參數都會以 & 字元分隔。以下列出允許的參數以及可能的值。

必要參數

請採取下列任一項做法：

  • location 可以是文字字串 (例如 Chagrin Falls, OH) 或經緯度座標組合 (40.457375,-80.009353)，且必須經過網址編碼。因此，請在傳送要求前，將「City Hall, New York, NY」等地址轉換為「City+Hall,New+York,NY」。Street View Static API 會對齊最靠近位置的全景相片。提供地址文字字串時，API 可能會使用其他相機位置，更準確地顯示指定位置。提供經緯度座標時，API 會搜尋 50 公尺半徑範圍，找出最靠近相片的位置相片。由於街景服務圖像會定期更新，而且每次拍攝的位置可能稍有不同，因此圖像更新後，location 可能會對齊其他全景。

或：

  • pano 是特定的全景 ID。全景可能會隨著時間變更 ID，因此請勿保留這組 ID。請改為儲存位置地址或經緯度座標，以便重新整理全景 ID。詳情請參閱「重新整理已刪除的全景 ID」一節。

以及：

  • size 會指定圖片的輸出大小 (以像素為單位)。大小指定為 {width}x{height}；例如，size=600x400 會傳回寬度 600 像素、高 400 的圖片。
  • key 可讓您在 Google Cloud 控制台中監控應用程式的 API 用量，並確保 Google 能在必要時針對應用程式與您聯絡。詳情請參閱「取得金鑰和簽名」。

重新整理已刪除的全景 ID

如果您嘗試擷取全景 ID 但取得 ZERO_RESULTS 或沒有值，則全景 ID 已遭刪除，必須重新整理。

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

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

自選參數

  • signature (建議) 是一個數位簽章，可以驗證使用您 API 金鑰產生要求的所有網站是否已獲得授權。不含數位簽章的要求可能會失敗。詳情請參閱「取得金鑰和簽名」。

    注意：先前的 Google 地圖平台付費方案客戶必須提供數位簽名。進一步瞭解付費方案客戶的驗證參數。

  • heading 表示攝影機的指南針方向。可接受的值為 0 到 360 (這兩個值均表示北方，90 表示東方，180 表示南方)。如果未指定方向，系統會計算值，將相機指向指定的 location，從最接近的相片拍攝地點開始。
  • fov (預設為 90) 會決定圖片的水平視野，以度為單位，最大值為 120。處理固定大小的可視區域時 (就像處理固定大小的街景服務圖片一樣)，基本上視野代表縮放，數字越小表示縮放等級越高。


    寬廣視野的螢幕截圖，當中展示水族箱內的天花板、牆壁、地板和坦克窗。 特寫鏡頭的螢幕截圖，顯示水族箱內部的街景服務相片放大細節。
    (左：fov=120；右：fov=20)

  • pitch (預設值為 0) 會指定相機相對於街景服務車輛的向上或向下角度。這通常是水平角色，不過不總是如此。正值角度使相機向上 (90 度表示直線向上)；負值角度使相機向下 (-90 表示直線向下)。
  • radius (預設為 50) 設定半徑 (以公尺為單位)，以指定經緯度為中心搜尋全景。有效值是非負整數。
  • return_error_code 表示 API 在找不到圖片時是否應傳回錯誤代碼 (404 NOT FOUND)，或是為了回應無效要求 (400 BAD REQUEST)。有效值為 true 和 false。如果設為 true，系統會傳回錯誤訊息，取代一般的灰色圖片。如此一來，就不必另外呼叫來檢查映像檔是否可用。
  • source (預設為 default) 限制街景服務只搜尋所選來源。有效值如下：
    • default 會使用街景服務的預設來源。搜尋範圍不限於特定來源。
    • outdoor 會將搜尋範圍限制在室外集錦。搜尋結果不會包含室內集錦。請注意，室外全景可能不適用於特定位置。此外，請注意，搜尋作業只會傳回可判斷其位於室內或室外的全景。舉例來說，系統不會傳回 PhotoSphere，因為系統無法辨識其是否位於室內。

這是要求範例。

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=46.414382,10.013988&heading=151.78&pitch=-0.76&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
街道視角相片的螢幕截圖，顯示受電動的鐵路軌道。

沒有可用的圖像

針對無法取得街景服務圖像的地點，Street View Static API 會傳回一般的一般圖片，並顯示文字「很抱歉，這裡沒有圖像」。如以下範例所示：

在指定地點沒有可用圖像的情況下顯示的一般圖片螢幕截圖。背景是淺棕色，顯示文字「很抱歉，這裡沒有圖像」。
圖：當指定地點沒有圖像時，會顯示通用圖片。

僅顯示有效的圖片

如要避免顯示通用圖片，並確保您的網頁只顯示有效的 Street View Static API 圖片，請遵循下列建議：

  • 將 return_error_code 參數設為 true。如果指定地點沒有可用的圖片，這會導致 Street View Static API 傳回 404 NOT FOUND 錯誤，而不是一般的灰色圖片。
  • 在傳送要求之前，要求街景服務圖片中繼資料，判斷指定地點是否可使用圖像。