沿路線搜尋總覽

沿途搜尋功能可在下列 Places (新版) API 中使用：

• 僅限 Text Search (新版)：搜尋沿著預先定義的旅遊路線的地點。
• Text Search (新版) 和 Nearby Search (新版)：計算從指定路線起點到搜尋結果中每個地點的路線摘要。
• 僅限文字搜尋 (新)：計算沿著預先定義的旅遊路線，每個地點的路線摘要。

沿路線搜尋

您可以使用 Routes API 計算兩個地點之間的行程路線。Routes API 可計算汽車、自行車、雙輪車、大眾運輸系統或步行路線。

注意：Places API 不支援大眾運輸系統路線。

Text Search (新版) 可讓您使用這個計算路線，執行沿路搜尋。使用這個選項時，您可以將預先計算的路線從 Routes API 傳遞至 Text Search (新版) 要求。回應就會包含符合搜尋條件，且位於指定路線附近的地點。

沿著路線搜尋的功能類似於使用 locationRestriction 或 locationBias 要求選項，可偏向搜尋結果。locationRestriction 會傳回位於可視區域邊界內的搜尋結果，而 locationBias 則可能會傳回位於可視區域外的搜尋結果。不過，雖然 locationBias 和 locationRestriction 選項可讓您指定偏好區域，以便偏重搜尋結果，但 Text Search 的沿路搜尋功能也能讓您偏重搜尋結果，以便納入從路線起點到路線目的地的最短繞路時間。您可以使用 locationBias 或 locationRestriction 搭配多邊形，為搜尋結果偏好設定。

舉例來說，請考慮從起點 (在 Routes API 中稱為路線控點) 到 Routes API 計算的目的地之間的路線：

沿路搜尋時，搜尋結果會偏向沿路附近的地點，並盡量縮短從起點到目的地的繞路時間。在這個範例中，點 A、B 和 C 是搜尋結果傳回的地點。

計算路由摘要

Text Search (新版) 和 Nearby Search (新版) 可根據要求中指定的路徑起點位置，計算回應中每個地點的路線摘要 (即時間和距離)。指定路線起點後，回應中不僅會包含符合搜尋內容的地點清單，還會包含從路線起點到各個地點的時間和距離。

在下圖中，點 A、B 和 C 是搜尋回應中傳回的位置：

對於結果中的每個地點，回應會包含從路線起點到該地點的車程時間和距離 (如有)。

注意：這只是路由資訊的預估值。如要取得實際路線詳細資料 (包括逐步指示)，請使用路線 API。

根據預設，系統會使用 Routes API 中的 TRAFFIC_UNAWARE 選項計算行程時間和距離。您可以選擇設定路線偏好設定，在計算期間考量即時路況 TRAFFIC_AWARE_OPTIMAL 或延遲降低的即時路況 TRAFFIC_AWARE。

注意： TRAFFIC_AWARE 和 TRAFFIC_OPTIMAL 僅適用於 DRIVE 和 TWO_WHEELER 移動模式。如果指定的路線偏好設定使用不支援的交通模式，路線摘要計算作業預設會使用 TRAFFIC_UNAWARE 選項。如果在不支援的區域中指定 TWO_WHEELER，API 會傳回空白的路徑摘要。

設定 TRAFFIC_AWARE 路線偏好設定後，系統會根據交通狀況計算路線。因此，路線和路線詳細資料會更準確地反映實際情況。由於資料品質提升會導致回應延遲，因此我們會套用效能最佳化方式，大幅減少延遲時間。設定 TRAFFIC_AWARE_OPTIMAL 路徑偏好設定時，系統會根據交通狀況計算路線，但不會套用任何效能最佳化功能。在這個模式中，伺服器會針對道路網路執行更詳盡的搜尋，找出最佳路線。

關於路線、路段和路線控點

路線由多個元件組成，並由 Routes API 計算：

路線由下列元件組成：

• Waypoint：如要計算路線，您至少必須指定起點和目的地的位置。您可以將這些位置定義為路線上的路線點。中繼路線控點是指起點和目的地之間，您希望路線經過的位置。

• 路線：從起點路線控點開始，經過任何中繼路線控點，到達目的地路線控點的整個行程。路線包含一或多個路段。

  將路線傳送至 Text Search 時，您會傳遞 Routes API 傳回的路線編碼後的折線。經過編碼的折線是經緯度點的編碼清單，可讓您以字串表示路線的折線。

• 路段：從路線中某個路標到下一個路標的路徑。每個航段都包含一或多個獨立的步驟。

  路線包含從每個路線控點到下一個路線控點的路徑，每個路段都各自獨立。舉例來說，如果路線包含單一起點路標和單一目的地路標，則路線就包含單一航段。

  對於您在起點和目的地後新增至路線的每個額外路標 (稱為「中繼」路標)，API 都會新增個別路段。

如要進一步瞭解路徑和計算路徑，請參閱 Routes API。

使用沿路搜尋功能計算路線摘要

您可以結合路徑摘要計算結果，並沿路搜尋。在這種情況下，Text Search (新版) 會在回應中傳回前往每個地點的車程時間和距離，然後從每個地點傳回路線的最終目的地。您可以將這項計算視為提供的交通時間和距離，假設您從指定路線繞道前往搜尋結果中的地點，然後繼續前往最終目的地。

舉例來說，請考慮以下由 Routes API 計算的路線，從起點前往目的地。將此路徑與搜尋條件一併傳送至 Text Search (新版) API。

在本例中，位置 A 是 Text Search (新版) 搜尋結果中傳回的地點。對於回應中的每個地點，搜尋結果會包含前往該地點的兩段行程所需的時間和距離：

• 第一段包含路線起點到地點的旅程時間和距離。在本例中，從起點到地點 A。
• 第二段則包含從地點到路線目的地的旅遊時間和距離。在本例中，從 A 到目的地。

您可以根據回應中的資訊計算繞路時間和距離，其中：

• \(t_{OD}\) 是從出發地到目的地的行程時間， \(s_{OD}\) 是從出發地到目的地的行程距離
• \(t_{OA}\) 是從起點到 A 的行程時間； \(s_{OA}\) 是從起點到 A 的行程距離
• \(t_{AD}\) 是從 A 到目的地的行程時間； \(s_{AD}\) 是從 A 到目的地的行程距離

繞路時間是原始行程 (從起點到目的地) 和新行程 (從起點到目的地經過 A) 之間的時間差異：

$$ t_{detour} = t_{OA} + t_{AD} - t_{OD} $$

繞路距離是指原始行程 (從起點到目的地) 和新行程 (從起點到目的地經過 A) 之間的距離差異：

$$ s_{detour} = s_{OA} + s_{AD} - s_{OD} $$