Maps Static API 可能會在發生問題時發出錯誤或警告。本指南將說明每則錯誤訊息,並提供錯誤解決更多操作說明。
無效請求
如果要求無效,Maps Static API 會傳回 HTTP 4xx
狀態碼和說明問題的訊息。以下列舉這類錯誤狀況的例子。注意:此處僅列舉部分可能的錯誤,請查看 API 傳回的實際錯誤代碼和訊息,進一步瞭解特定問題。
錯誤條件範例 | 狀態碼 |
---|---|
要求含有無效參數,或缺少必要參數。舉例來說,size 參數不在預期數值範圍內,或要求中缺少。 |
400 BAD REQUEST |
要求中包含的 API 金鑰無效。 | 403 FORBIDDEN |
導致地圖無法顯示的錯誤
如果要求有效,但發生另一項導致地圖無法顯示的錯誤,Maps Static API 會根據錯誤傳回文字或錯誤圖片,而不是地圖。應用程式超過用量限制時,就屬於這類錯誤狀況的一個例子。
![顯示錯誤圖片 (而非地圖)](https://developers.google.cn/static/maps/documentation/maps-static/images/error-image-generic.png?authuser=6&hl=zh-tw)
API 金鑰和帳單相關錯誤
如果您在沒有 API 金鑰的情況下使用 Maps Static API,或是帳戶未啟用計費功能,則頁面會顯示錯誤圖片,而非地圖,並附上指出錯誤類型的連結。例如「g.co/staticmaperror/key」。
無金鑰錯誤和解決方案 | |
---|---|
![]() |
您目前使用 Maps Static API,但沒有 API 金鑰。如要解決這個問題,您必須採取以下步驟: |
![]() |
您的要求缺少數位簽章 (必要)。如要解決這個問題,請 簽署網址 |
警告
針對某些錯誤狀況,API 會傳回地圖,但地圖中可能會缺少部分資訊。發生這種情況時,系統會透過兩個條件通知您警示。
- 其中一個方法是顯示地圖,但疊加在地圖的上方有黃色錯誤列,並顯示「地圖錯誤:g.co/staticmaperror」。
- 第二,API 會以名為
X-Staticmap-API-Warning
的 HTTP 標頭形式傳回警告。
例如,下列網址的 markers
參數含有非預期值:
https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&scale=1&size=400x400&markers=sdgaags&key=YOUR_API_KEY
API 傳回地圖,但會在圖片上疊加黃色錯誤列,並顯示「地圖錯誤:g.co/staticmaperror」:
![地圖顯示,但發生地圖錯誤:g.co/staticmaperror](https://developers.google.cn/static/maps/documentation/maps-static/images/map-warning.png?authuser=6&hl=zh-tw)
API 也會傳回以下 HTTP 標頭:
X-Staticmap-API-Warning:Error geocoding: marker 1
下表說明 API 可能會以 HTTP 標頭形式發出的警告:
X-Staticmap-API-Warning 標頭中的警告
|
|
---|---|
Error geocoding:
[center, ][marker #number, ][visible #num, ][path #num, ]* |
嘗試為要求進行地理編碼時發生錯誤。這則訊息有多種變化形式,視地理編碼失敗的元素 (中間、標記、可見或路徑) 及失敗的元素數量而定。這項警告的其中一個例子是 X-Staticmap-API-Warning:Error geocoding: marker 1 ,如上例所示。 |
Too many geocoded markers requested (max is 15). |
要求指定的標記數量超過對人類可讀地址的數量上限。上限為 15 個。請注意,這項限制僅適用於指定為人類可讀地址且需要地理編碼的標記。不適用於指定經緯度座標的標記。 |
Too many geocoded polyline vertices requested (max is 15). |
該要求指定的折線數量超過對人類可讀地址的數量上限。上限為 15 個。請注意,這個限制僅適用於具有指定端點且需要進行地理編碼的端點的折線。不適用於透過經緯度座標指定的折線。 |
您可以在 Chrome 開發人員工具控制台、Firefox 網頁控制台或其他瀏覽器中,查看 HTTP 標頭警告。