沿路線搜尋功能總覽

下列 Places (New) API 提供沿路線搜尋功能：

  • 僅限 Text Search (新版)：搜尋預先定義行程路線沿途的地點。
  • Text Search (新版) 和 Nearby Search (新版)：計算從指定路線起點位置到搜尋結果中各個地點的路線摘要。
  • 僅限文字搜尋 (新版)：計算預先定義行程路線上每個地點的路線摘要。

沿路線搜尋

您可以使用 Routes API 計算兩個地點之間的行程路線。Routes 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 點是搜尋回應中傳回的地點：

點 A、B 和 C 是搜尋回應傳回的地點。

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

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

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

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

組成路徑的元件。

路徑包含下列元件：

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

  • 路線：從起點路線控點出發，途經所有中途路線控點，最後抵達目的地路線控點的完整行程。路線由一或多個路段組成。

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

  • 路段：路線中從一個路線控點到下一個路線控點的路徑。每個路段都包含一或多個不連續的步驟。

    路線包含不同的路段，代表從每個路線控點到下一個路線控點的路徑。舉例來說，如果路線包含單一起點路線控點和單一目的地路線控點，則路線包含單一路段。

    在起點和目的地之間，您為路線新增的每個額外中途點 (稱為「中途」中途點)，API 都會新增一個獨立路段。

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

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

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

舉例來說，假設 Routes API 計算出從起點到目的地的路線如下。將這條路線和搜尋條件一併傳送至 Text Search (New) 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} $$