處理行程資料

擷取行程資料時，後端會收到 JSON 酬載，詳細說明司機的行程進度。剖析這些酬載，即可監控行程、更新調度系統，以及解讀目前的行程狀態，以便在行程進行中或結束時，判斷駕駛人接下來的步驟。

讀取資料酬載

駕駛人開始導航時、沿途定期 (預設每 60 秒) 和抵達目的地時，Google 地圖或 Waze 會將行程資料酬載傳送至 Navigation Connect 伺服器。每個 JSON 訊息都包含相關行程資料，包括駕駛人的道路對應座標、行駛距離和預計到達時間。由於這些更新反映的是駕駛人當下的即時路線，因此可能與後端預先計算的路線不同 (請參閱常見問題)。

以下程式碼範例顯示行程資料酬載，適用於司機從 King's Cross 導航至 Central St. Giles 的行程。

{
  "name": "projects/123456/trips/221B9CD6-4146-4CBF-9556-853817654938",
  "state": "ENROUTE",
  "execution": {
    "origin": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      }
    },
    "destination": {
      "point": {
        "latitude": 51.515598,
        "longitude": -0.1277623
      }
    },
    "location": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      },
      "sourceTime": "2025-05-30T12:37:26Z",
      "serverTime": "2025-05-30T12:37:26.221069Z"
    },
    "traveledDuration": "0s",
    "remainingDuration": "990s",
    "traveledDistanceMeters": 0,
    "remainingDistanceMeters": 2879,
    "stopAddedInRoute": false
  }
}

監控行程的即時狀態

如要確認是否成功啟動，並監控進度，請評估每個酬載中的 state 欄位。

狀態 說明
NEW 行程已建立，但司機尚未開始導航。
ENROUTE 司機正在導航前往目的地。使用這個狀態確認行程已通過驗證並順利啟動。

處理新增的停靠點

駕駛人可以在導航期間新增停靠點。如果有的話，Navigation Connect 會在 JSON 資料酬載中，將 execution.stopAddedInRoute 欄位設為 true。Navigation Connect API 會繼續追蹤駕駛人前往原始目的地的路徑。預計到達時間 (ETA)、距離和時間等指標會增加，以納入新增的停靠點。

新增停靠點的行為取決於導航應用程式，並符合其標準功能：

  • Google 地圖：駕駛人可以在路線中新增多個停靠點。
  • Waze：駕駛人只能新增一個停靠點。如果駕駛人嘗試新增其他停靠點，Waze 會提示他們開始新的導航工作階段，而不是將停靠點新增至目前路線。

您不需要調整後端輸入內容，即可支援這項功能。

排解驗證和啟動問題

如果沒有收到 ENROUTE 狀態，可能發生驗證錯誤。常見原因包括 API 參數拼字錯誤或行程權杖過期。在初始 CreateTrip 回應中查看權杖到期時間。

如果狀態未從 NEW 變更為 ENROUTE，可能是司機的裝置阻礙了驗證程序。在這些情況下，Navigation Connect 不會傳送錯誤訊息。請確認下列事項：

  • 司機安裝的 Waze 版本為 5.15.5 以上，或 Google 地圖版本為 26.14 以上。
  • 駕駛人未使用 Android Auto 或 Apple CarPlay。
  • 司機已連上網際網路。

處理剩餘路線資料 (僅限 Waze)

如果您在建立行程時啟用剩餘路線回報功能，後端就會收到從駕駛人目前位置到最終目的地的剩餘路線折線，以及即時路況資訊。

您可以擷取及處理這項資料，為應用程式中的多項功能提供支援，包括以下範例：

  • 提供即時追蹤地圖：在面向消費者的網頁或行動地圖上，繪製剩餘路線的折線，讓消費者掌握司機的行程。
  • 提高預計抵達時間的準確度：結合道路對應的折線和流量間隔速度，改善內部物流或預計送達時間預測。
  • 分析路線合規情形：比較剩餘路線幾何與預期派車路線，評估駕駛人是否遵守路線 (如要瞭解即時路線和預先計算路線可能不同的原因，請參閱常見問題)。

無論您是傳送 GetTrip 要求，還是使用 Google Cloud Pub/Sub 接收事件驅動的更新，Navigation Connect 都會在 execution.remainingRoute 欄位中傳回其餘路線詳細資料。不過，酬載格式和結構化資料的方式，取決於您使用的擷取方法。

GetTrip 方法

呼叫 GetTrip 方法時，折線的回覆格式取決於您在要求中指定的 routePolylineFormat 參數。詳情請參閱「自訂折線格式」。

對於所有折線格式，Navigation Connect 會在 execution.remainingRoute.trafficInformation 欄位中，以 SpeedReadingInterval 物件的獨立清單形式傳回流量。這些物件會使用下列值，將流量類別對應至折線索引：

Google Cloud Pub/Sub 更新

使用 Pub/Sub 擷取行程資料時，更新一律會以統一的 GeoJSON FeatureCollection 格式，在 execution.remainingRoute 欄位中傳回剩餘路線資料。

這個格式會直接結合折線幾何和車流速度，因此不需要手動對應索引。

查看 Pub/Sub 酬載範例

下列程式碼範例顯示 Pub/Sub 訊息 updatedTrip 物件的 execution.remainingRoute 欄位中傳回的 GeoJSON 結構：

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.3934, 37.7955],
          [-122.4010, 37.7980]
        ]
      },
      "properties": {
        "speed": "SLOW"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.4010, 37.7980],
          [-122.4058, 37.8025],
          [-122.4187, 37.8021]
        ]
      },
      "properties": {
        "speed": "NORMAL"
      }
    }
  ]
}

最佳化酬載大小

由於座標陣列很大，在 Pub/Sub 訊息中加入其餘路線資料可能會大幅增加酬載大小 (每則訊息最多 13 到 14 KB)。如果收到高頻率更新，這個量可能會增加後端處理負載和使用費用。

如要最佳化串流，請在行程建立期間，使用 TripConfig 物件中的 pubsubFieldMask 參數排除大型欄位。詳情請參閱「選用設定」。

處理路線偏離情形 (僅限 Waze)

如果建立行程時已啟用路線偏離回報功能，當司機偏離路線時，API 會傳回路線偏離中繼資料。您可以透過下列方式存取這項資料：

  • 隨選：呼叫 GetTrip 方法。伺服器會保留最後已知的偏差狀態。
  • 即時：訂閱 Google Cloud Pub/Sub。服務會在偵測到偏差後 5 秒內，使用現有的 updated_trip 事件發布偏差更新。

讀取偏差酬載

last_route_deviation 物件提供下列中繼資料，協助您分析事件。

欄位 類型 說明
location LatLng 用戶端裝置記錄偏差的經緯度座標。
source TriggerSource 偏差原因。您可以使用這項資訊，判斷駕駛人是否採取非預期行動或遵循系統指引：
  • DRIVER_INITIATED_REROUTE：駕駛人主動做出選擇 (例如轉錯彎或手動選取新路徑)。
  • SYSTEM_INITIATED_REROUTE：導航應用程式計算出新路線 (例如，因為路況改變或道路封閉)。
client_timestamp Timestamp 用戶端裝置偵測到偏差的時間。
server_timestamp Timestamp 伺服器處理偏差更新的時間。

處理行程結束狀態

當駕駛人抵達目的地或停止導航時，酬載會傳回下列其中一種結束狀態。您可以使用這些狀態，在應用程式中觸發適當的後續步驟。

狀態 說明 建議做法
ARRIVED 司機已抵達目的地。 檢查 remainingDistanceMeters。如果司機在附近停車，但不在確切座標位置，請考慮在應用程式中提供步行路線。
SUSPENDED 司機在抵達目的地前手動結束即時路況導航。
由於 Google 地圖或 Waze 不會在駕駛人提早結束工作階段時自動返回你的應用程式，因此駕駛人必須手動輕觸返回按鈕。 		為協助駕駛完成行程，請比較 execution.location 與目的地。如果距離仍未縮短，請提供按鈕或連結，讓使用者繼續行程或切換至步行模式。
FAILED 技術錯誤導致連線中斷。如果應用程式無法計算路線或顯示安全警告，就會發生這種情況。司機可能仍會繼續導航，但你不會收到更新。 在應用程式中改為手動狀態追蹤。
CLIENT_ERROR 顯示這個狀態的原因如下：
  • 司機撤銷同意聲明。
  • 駕駛人使用不支援的平台，例如 Android Auto 或 Apple CarPlay。
  • 應用程式在不同行程中重複使用行程權杖。舉例來說，Navigation Connect 會拒絕變更行程目的地或更新已完成行程的要求。
  • 行程期間，司機位於美國，但您在設定期間驗證應用程式時，未啟用美國的資料共用功能。
 在應用程式中改為手動狀態追蹤。