「街景服務圖片」要求是一種 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 已經刪除,必須重新整理。
儲存用來取得全景 ID 的位置地址或經緯度座標,以便視需要重新整理。
當您偵測到全景 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 要求) 時是否傳回錯誤代碼。有效值為true
和false
。如果設為true
,系統會傳回錯誤訊息來取代一般灰色圖片。這樣就不必另外呼叫檢查圖片可用性。source
(預設值為default
) 會將街景服務搜尋範圍限制在所選來源。有效值如下:default
會使用街景服務的預設來源。搜尋範圍不限於特定來源。outdoor
會將搜尋範圍限制在室外集錦。搜尋結果不會包含室內集錦。請注意,室外全景可能不適用於特定位置。此外請注意,搜尋只會傳回可判斷其位於室內或室外的全景。舉例來說,系統不會傳回 PhotoSpheres,因為系統無法確認其位於室內或室外。
這是要求範例,
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 錯誤,而非一般灰色圖片。 - 在傳送要求之前,請先要求街景服務圖片中繼資料,確認特定地點是否有圖像可用。