處理行程資料

擷取行程資料時,後端會收到 JSON 酬載,詳細說明司機的行程進度。剖析這些酬載,即可監控行程、更新調度系統,以及解讀目前的行程狀態,以便在行程進行或結束時,決定司機的下一步。

讀取資料酬載

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

下列程式碼範例顯示行程資料酬載,適用於司機開始導航從國王十字車站到中央聖吉爾斯的行程。

{
  "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。
  • 司機已連上網際網路。

處理剩餘的路線資料

如果您在建立行程時啟用了剩餘路線回報功能,後端就會收到從司機目前位置到最終目的地的剩餘路線折線和即時路況。駕駛人必須使用 Android 版 Waze 5.20.0.2 以上版本、iOS 版 Waze 5.20.0.1 以上版本,或 Android 版 Google 地圖 26.27 以上版本。

您可以擷取及處理這類資料,為應用程式中的多項功能提供支援,包括:

  • 提供即時追蹤地圖:在客戶端網頁或行動地圖上,顯示剩餘路線折線,讓客戶掌握司機的行程。
  • 提高預計到達時間準確度:結合道路貼齊折線和車流區間速度,改善內部物流或送達時間預測。
  • 分析路線遵循情況:比較剩餘路線幾何圖形與預期派遣路線,評估司機是否遵循路線 (如要瞭解即時路線和預先計算路線可能不同的原因,請參閱常見問題)。

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

GetTrip 方法

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

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

Google Cloud Pub/Sub 更新

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

這種格式會直接結合折線幾何圖形和車流速度,因此不必手動對應索引。

查看 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)

駕駛必須使用 Waze 5.22 以上版本。

如果您在建立行程時啟用了路線偏離回報功能,當司機偏離路線時,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 會拒絕變更行程目的地或更新已完成行程的要求。
  • 司機在行程期間曾位於美國,但您在設定期間驗證應用程式時,並未啟用美國的資料共用功能。
在應用程式中改用手動狀態追蹤。