疑難排解

錯誤

如果發生錯誤，系統會傳回標準格式的錯誤回應內文，並將 HTTP 狀態碼設為錯誤狀態。

回應包含一個物件，其中含有單一 error 物件，並具有下列鍵：

  • code：這與回應的 HTTP 狀態相同。
  • message：錯誤的簡短說明。
  • status：指出錯誤性質的狀態碼。

舉例來說，傳送無效的 placeId 參數會傳回下列錯誤：

{
  "error": {
    "code": 400,
    "message": "\"placeId\" value is malformed: \"aChIJqaknMTeuEmsRUYCD5Wd9ARM\"",
    "status": "INVALID_ARGUMENT"
  }
}

可能出現的錯誤包括：

程式碼 狀態 訊息 疑難排解
400 INVALID_ARGUMENT 您提供的金鑰無效。 您的 API 金鑰無效或未納入要求中。 請確認您已加入完整金鑰，並為這個金鑰啟用 API。
400 INVALID_ARGUMENT 「\"path\" 參數包含無效值：☃」 您的要求包含無效引數。造成這項錯誤最可能的原因如下：
  • path 參數有問題。
    請確保至少有 1 個點，且點數少於 100 個。每個點都應是以半形逗號分隔的數字組合，例如：48.409114,-123.369158。點數應以直立線「|」分隔。
  • 您的要求包含無效的 placeId。
  • 您的要求包含 placeId 和 path。每個要求只能指定其中一個參數。

如果傳遞的 placeId 對象是已不存在的道路，或是並非道路的地點，系統不會傳回這項錯誤。
403 PERMISSION_DENIED 系統已封鎖未註冊的要求。請使用 Google Developers Console 註冊。 要求遭拒的原因如下：
  • API 金鑰遺失或無效。
  • 您的帳戶尚未啟用帳單功能。
  • 超過自行設定的用量上限。
  • 您提供的付款方式已失效 (例如信用卡已過期)。

如要使用 Google 地圖平台的各項產品，帳戶必須啟用計費功能，且所有要求都必須包含有效的 API 金鑰。如要修正這個問題，請按照下列步驟操作：
404 NOT_FOUND 這項服務必須使用 HTTPS。 請確認您傳送要求至 https://roads.googleapis.com/，而非 http://roads.googleapis.com/。
429 RESOURCE_EXHAUSTED 已達專案要求限制，因此要求遭到節流。 您已超出在 Google Cloud Platform 控制台中設定的要求限制。這項限制通常會設為每日要求數、每 100 秒要求數，以及每位使用者每 100 秒的要求數。設定這項限制時，請確保單一或少數使用者不會耗盡每日配額，同時所有使用者仍可合理存取。如要設定這些限制，請參閱「限制 API 用量」一文。

指數輪詢

要求失敗時，請務必以指數輪詢方式重試要求。舉例來說，如果要求失敗一次，請在一秒後重試；如果再次失敗，請在兩秒後重試，然後是四秒，依此類推。這樣可確保大量用戶端嘗試快速重試要求時，不會因要求中斷或大規模失敗而導致 Google 伺服器超載。

疑難排解常見問題

導入問題

我應該以多高的頻率取樣車輛位置？
建議每 1 到 10 秒回報一次位置，以獲得高品質的道路對齊結果。
每次查詢可傳送的點數是否設有限制？
可以，查詢最多可有 100 個點。
我應該使用哪種精確程度來儲存擷取的緯度/經度配對？
為確保路徑在所有縮放等級 (包括最大縮放等級) 都能貼齊道路，您應以小數點後 7 位的精確度儲存貼齊的緯度/經度配對。
我可以使用編碼折線顯示路徑嗎？
編碼折線只會指定到小數點後 5 位，因此會產生約 2 公尺的誤差。因此，如果您希望路徑在縮放比例較高時，仍能貼近道路，就不適合使用編碼折線。

常見問題

部分點未對齊，或對齊路徑有間隙。如何修正這個問題？
  • 如果您是以固定時間間隔取樣點，請確保點的取樣間隔較短 (每 1 到 10 秒)。如果使用較長的時間間隔 (例如 60 秒)，路徑對應演算法可能無法充分準確地判斷行駛的道路。
  • 如果是在地圖上手動點按建立點，很容易會建立點數較少或稀疏的路徑，而對齊演算法無法妥善處理這類路徑。貼齊演算法最適合用於距離較近的點。請試用道路對齊試用版，或使用道路檢查器測試路徑。
為什麼我放大地圖時，路徑會出現鋸齒狀或與道路稍微錯開？
  • 您是否會在顯示經緯度配對前，先截斷其精確度？如果儲存的經緯度配對精確度低於 7 個小數點，在地圖上顯示路徑時就會發生精確度錯誤。
  • 您是否使用編碼折線？編碼折線會將經緯度配對截斷至小數點後 5 位，這會造成幾公尺的誤差，導致在高縮放等級下，線條呈現鋸齒狀或與道路略有偏差。

如果上述兩種情況都不適用，可能是地圖圖塊最近更新，導致與用於對齊的道路索引不同步。如果只有少數查詢受到影響，這很可能就是原因。由於 Google 地圖會定期更新，因此偶爾會發生這種情況。如果您經常查看地圖上的舊路徑 (例如幾週前拍攝的路徑)，這種情況可能會更常發生。為獲得最佳視覺化效果，您應在路徑顯示於地圖上之前重新對齊舊路徑，盡量減少地圖圖塊與用於對齊的路網索引之間的不一致。

道路 X 的速限顯示有誤，可能的原因為何？
速限資訊來自多個來源，準確度和涵蓋範圍不一。 如果發現某種模式，例如特定道路類型或特定區域的速限持續錯誤，請按照下列步驟告訴我們：
  1. 在桌上型電腦上開啟 Google 地圖，或是開啟 Android 版 Google 地圖應用程式。
  2. 開啟左側選單。
  3. 選取「提供意見」，注意：系統可能會提示你登入。
  4. 選取「編輯地圖」。
  5. 選取要編輯的路段。
  6. 選取「下一步」。
  7. 在「其他」欄位中，指出該道路的速限有誤。
  8. 選取「提交」。
你也可以在這裡回報其他問題 (例如道路名稱有誤、繪製錯誤、封閉或為私人道路)。
為什麼路徑會切入彎道，而不是沿著道路行駛？
如要修正這個問題，請檢查下列事項：
  • 確認 interpolate 參數設為 true。
  • 確認原始資料點的取樣間隔是否夠近 (每 1 到 10 秒)。
為什麼在沒有速限變更的路段，系統卻在路徑比對結果中傳回許多路段？
如果將 interpolate 參數設為 true，道路對齊查詢會傳回折線，沿著道路轉彎、彎道和圓環。如果道路彎曲，即使速限不變，系統也會傳回多個路段，以便建立緊貼道路幾何形狀的多邊形折線。