處理行程資料

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

讀取資料酬載

駕駛人開始導航時、沿途定期 (預設每 60 秒) 和抵達目的地時，Google 地圖或 Waze 會將行程資料酬載傳送至 Navigation Connect 伺服器。每個 JSON 訊息都包含相關行程資料，包括駕駛人的道路座標、行駛距離和預計到達時間 (ETA)。

下列程式碼範例顯示行程資料酬載，適用於駕駛人從 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
  }
}

監控行程的有效狀態

如要確認是否順利啟動及監控進度，請評估每個酬載中的狀態欄位。

狀態 說明
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 物件清單形式傳回路況。這些物件會使用下列值，將流量類別對應至折線索引：

  • startPolylinePointIndex：折線上的流量間隔起始索引。
  • endPolylinePointIndex：流量間隔的結束索引。
  • speed：這個區隔的流量類別：NORMAL、SLOW 或 TRAFFIC_JAM。

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 參數排除大型欄位。詳情請參閱「選用設定」。

處理行程結束狀態

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

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