基本概念

如要生成等時線，請向 API 提供起點、交通方式 (例如開車、騎機車、騎自行車或步行) 和時間限制。您也可以調整路線偏好設定和多邊形的外觀。

交通方式

使用必要的 travelMode (travel_mode) 參數指定交通方式：

• DRIVE：使用速限、道路階層、轉彎懲罰和即時路況 (選用)，計算客車在可駕駛道路上的可達性。
• TWO_WHEELER：計算兩輪機動車輛 (例如摩托車或速克達) 的可達性，使用特定模式的道路通行規則，以及比 DRIVE 在高速道路上更低的模型速度。因此，TWO_WHEELER 等時線涵蓋的區域通常大於 BICYCLE，但小於沿著高速公路的 DRIVE。
• BICYCLE：計算單車騎士沿著單車可通行的街道、單車道和共用路徑的可達性，並根據道路類型和坡度調整速度，不包括高速公路和管制通行的高速公路。
• WALK：計算行人在人行道、步道、小徑和行人可通行的街道上的可達性，並根據坡度調整步行速度。步行路線會忽略單向車輛限制。

時間範圍

您提供給服務的主要限制是 travelDuration (travel_duration)，這會定義計算的時間範圍。

• 時間長度下限和上限：時間長度必須至少為 "1s" (1 秒)。零 ("0s")、負值和未滿 1 秒的持續時間 (例如 "0.5s") 會傳回 400 INVALID_ARGUMENT 錯誤。API 支援 DRIVE 和 TWO_WHEELER 模式的最長行程時間為 3,600 秒 (1 小時)，WALK 和 BICYCLE 模式則為 7,200 秒 (2 小時)。
• 多邊形底限：由於 API 會將可到達的路段轉換為空間網格儲存格，因此如果時間很短，系統會傳回一個小型多邊形，涵蓋貼齊起點周圍的網格儲存格。
• 效能：計算時間會隨著要求的時間長度和所選的交通工具而調整。一小時開車等時線涵蓋的地理區域和路網，明顯大於一小時步行等時線，因此開車要求的延遲時間會較長。
• 格式：由於 API 使用 google.protobuf.Duration，因此時間長度必須格式化為以 "s" 結尾的字串 (例如 "3600s")，而非整數。

原始點和道路貼齊

您可以透過下列兩種方式指定等時線的起點：

• 座標 (location)：一組經緯度。請同時提供 latitude (以[-90, 90]表示) 和 longitude (以[-180, 180]表示)。如果省略其中一個，API 會將其視為 0.0，並將該點置於赤道或本初子午線上。如果兩者都省略 ({}) 或傳送 (0, 0)，API 會傳回 400 INVALID_ARGUMENT 錯誤。
• 地點 ID (place)：Google 地圖上特定地點的專屬 ID。提供地點 ID 後，服務會將地點解析為其群集中心座標，並將該點貼齊至最近的道路。請使用開頭為 places/ 的資源名稱格式 (例如 places/ChIJIQBpAG2ahYAR_6128GcTUEo)；不含 places/ 前置字元的純地點 ID 也可接受。如要進一步瞭解地點 ID，請參閱「地點 ID」。

無論採用哪種輸入方式，如果實際地點不在道路上 (例如在公園或建築物內)，API 就不會從該地點計算行程時間。為處理這種情況，服務會使用道路貼齊功能。道路貼齊功能具有下列特性：

• 智慧貼齊：服務會嘗試將起點貼齊至最近的可行駛路段。
• 模式感知：貼齊邏輯會考量 travel_mode。如果您要求 DRIVE 或 TWO_WHEELER，API 會忽略行人專用道，並尋找最近的可行駛街道。如果要求 WALK，API 會優先選擇可步行的路徑和人行道。
• 失敗案例：如果 API 無法在起點的最大貼齊距離內 (約 200 公尺，WALK 和 BICYCLE 則更短) 找到合適的路段，API 會傳回 404 NOT_FOUND 錯誤。大型地貌 (例如公園、校園或觀景點) 的地點 ID 群集中心，可能與旅行模式可用的最近道路相距甚遠，超過貼齊距離。在這種情況下，請改為傳遞道路入口的明確 location 座標。

通行方向 (進城與出城)

您可以使用 travelDirection (travel_direction) 參數，計算傳入和傳出可連性：

• FROM (去程)：計算在指定時間限制內，從起點可到達的區域。這項功能適用於商家派送區域或服務範圍等用途。
• TO (入境)：計算在指定時間限制內，可從哪些區域前往起點。這項功能適合用來判斷涵蓋範圍，例如員工可從哪些地方通勤到中央辦公室。

流量感知

使用 routingPreference (routing_preference) 參數，控制車流量資料對生成多邊形的影響：

• TRAFFIC_UNAWARE (預設)：使用自由流速限制和道路階層，生成等時線多邊形。這會產生確定性形狀，不會因一天中的時間而波動。這個參數適合用於一般分析或基準情境規劃。
• TRAFFIC_AWARE：使用處理要求時的即時路況計算等時線 (第 1 版無法自訂未來或過去的出發/抵達時間戳記)。這會導致可達區域在交通壅塞時縮小，在離峰時段擴大；在交通順暢或離峰時段，TRAFFIC_AWARE 和 TRAFFIC_UNAWARE 可能會傳回幾乎相同的多邊形。注意：只有在 travelMode 設為 DRIVE 或 TWO_WHEELER 時，才支援車流量監測路線。

平滑度和擬真度

您可以使用 polygonFidelity (polygon_fidelity) 和 enableSmoothing (enable_smoothing) 參數，自訂輸出多邊形的外觀和精確度。雖然這些選項各自獨立，但會共同決定最終形狀。

• polygonFidelity：控制用於估算可達邊界的空間格線儲存格解析度：

  • LOW：使用最大的格線單元 (寬度達數百公尺)。最適合用於涵蓋大範圍區域，頂點較少且沒有內部間隙，因此會產生一般形狀，可能會高估沿著狹窄道路走廊的可到達區域。
  • MEDIUM：在精確度和頂點數量之間取得平衡。
  • HIGH：使用最小的格線儲存格 (寬度約 100 至 150 公尺)。結果會更貼近可到達的道路網路，但在道路網路稀疏的地方可能會產生內部空洞。
  • POLYGON_FIDELITY_UNSPECIFIED：如未指定，服務會根據交通工具和時間長度自動選取解析度，短時間和 WALK 使用較精細的儲存格，長時間則使用較粗略的儲存格。如要比較不同時間長度或交通方式的等時線，請明確設定 polygonFidelity。

    

• enableSmoothing：控制是否要將精確度定義的格線儲存格階梯狀邊緣圓滑化。

  • false (原始)：預設值。傳回與格線對齊的邊界。邊緣會沿著網格儲存格呈現階梯狀。最適合用於分析準確度，例如嚴格的多邊形內點測試。
  • true (平滑)：將尖角修圓，以便在地圖上顯示，同時大致保留每個環的面積。邊界不再遵循網格儲存格。