街景服務要求與回應

街景圖片要求是採用下列格式的 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 找不到) 或回應無效要求 (400 錯誤要求) 時傳回錯誤代碼。有效值為 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 找不到錯誤，而非一般灰色圖片。
  • 請先要求街景圖像中繼資料，確認指定位置是否有可用的圖像，再傳送要求。