累積的道路資料

累積道路資料是指您在選定路線上，可隨時間累積的資料。使用 Roads Selection API 建立路線後，就會開始收到資料。這項資料可用於深入分析、策略規劃，以及瞭解路徑的長期行為。

累積道路資料會以時間序列資料的形式提供，包括：

設定 BigQuery

您必須先設定 Google Cloud 雲端專案並訂閱資料交換，才能在 BigQuery 中存取道路資料。

必要條件

確認 Google Cloud 雲端專案和帳戶的設定如下：

  1. 啟用 BigQuery API。如需操作說明，請參閱「使用 Google Cloud 控制台查詢公開資料集」。
  2. 啟用 Analytics Hub API。請參閱「Analytics Hub API」。
  3. 授予必要的 IAM 角色。請確認您的帳戶具備下列角色，可執行訂閱者工作及建立資料集：
  4. Analytics Hub 訂閱者 (roles/analyticshub.subscriber)

訂閱資料交換

道路資料會透過 BigQuery (Analytics Hub) 的私人資料交換與您共用。您會收到 Google 合作夥伴提供的特定訂閱連結，用於存取資料。這個資料集遵循下列命名慣例：

historical_roads_data_PROJECT_NUMBER.

如要訂閱資料，請按照下列步驟操作：

  1. 按一下 Google 合作夥伴提供的訂閱連結。點選這個連結，即可直接前往 Google Cloud 控制台中的資料交換。
  2. 在 Google Cloud 控制台中，查看資料交換詳細資料。
  3. 按一下對話方塊中的「訂閱」按鈕。
  4. 訂閱完成後，連結的資料集會顯示在 Google Cloud 控制台的 BigQuery「Explorer」面板中。現在，您可以使用 Explorer 面板中顯示的資料表名稱，在 SQL 查詢中存取資料。

BigQuery 資料表

所選路線的累積道路資料，會託管在 Google 擁有的雲端專案中，並存放在獨立的 BigQuery 資料集。這項資料是透過 BigQuery sharing (Analytics Hub) 中專為您建立的私人資料交換服務與您共用。如要存取資料，您必須訂閱資料交換，並在 Google Cloud 專案下建立連結資料集。

共用的 BigQuery 資料集包含一些由 Google 定義及建立的 BigQuery 資料表。以下是各資料表的詳細資料。

historical_travel_time 個資料表

以下是 BigQuery 資料表 historical_travel_time 的結構定義：

名稱 模式 類型 說明
selected_route_id 可以為空值 STRING 路線的 selected_route_id
display_name 可以為空值 STRING 路徑的顯示名稱
record_time 可以為空值 時間戳記 計算路線資料的時間戳記
duration_in_seconds 可以為空值 FLOAT 考量路況後的路線所需時間。當 has_road_closure 為 true 時，系統會省略 (NULL)。
static_duration_in_seconds 可以為空值 FLOAT 路線所需時間 (不考量路況)
route_geometry 可以為空值 地理位置 路線的車流量監測折線幾何圖形
road_segment_ids REPEATED STRING 路線沿途的路段，以地點 ID 表示
has_road_closure 可以為空值 BOOLEAN 路線是否完全封閉。當 true 時，系統會省略 duration_in_seconds (NULL)，因為路線無法通行。NULL 值表示道路封閉資訊不確定。

表格行為和事實

  • 資料表按天分區，每個分區的到期時間設為 10 年。
  • 資料表每小時會更新一次，並以批次方式寫入最新流量資料。
  • 在 Roads Selection API 中建立新路線後，最多可能需要等待 1 小時，才能在這個資料表中看到可用資料。
  • 從 Roads Selection API 刪除路徑後，系統就不會再將該路徑的新資料寫入這個資料表。不過，歷來資料會保留到到期為止。
  • 路線上的路段會按照拓撲順序排列，且一律會相連。
  • has_road_closure 旗標與 Google 地圖上的道路封閉狀態一致。

recent_roads_data 個資料表

注意：只有在合約包含即時道路資料時，才能使用這個資料表。

與 historical_travel_time 不同，這個資料表也包含以偏移量為基礎的速限讀取間隔 (speed_reading_offsets)，以及舊版以座標為基礎的速限讀取間隔 (speed_reading_intervals)。以下是 BigQuery 中的結構定義：

名稱 模式 類型 說明
selected_route_id 可以為空值 STRING 路線的 selected_route_id
display_name 可以為空值 STRING 路徑的顯示名稱
record_time 可以為空值 時間戳記 計算路線資料的時間戳記
duration_in_seconds 可以為空值 FLOAT 考量路況後的路線所需時間。當 has_road_closure 為 true 時，系統會省略 (NULL)。
static_duration_in_seconds 可以為空值 FLOAT 路線所需時間 (不考量路況)
route_geometry 可以為空值 地理位置 路線的車流量監測折線幾何圖形
speed_reading_intervals REPEATED RECORD 舊版座標式速度讀取間隔。2026 年 11 月 9 日起，可能不會再填入資料。請改用 speed_reading_offsets。請參閱「速度讀取間隔」。
speed_reading_intervals.interval_coordinates REPEATED 地理位置 舊版。2026 年 11 月 9 日起可能停止填入資料。請改用 speed_reading_offsets。這個間隔的幾何圖形
speed_reading_intervals.speed 可以為空值 STRING 舊版。2026 年 11 月 9 日起，可能不再填入資料。請改用 speed_reading_offsets。這個間隔的速度分類。可能的值：NORMAL、SLOW、TRAFFIC_JAM。在這個舊版欄位中，嚴重塞車 (深紅色) 也會回報為 TRAFFIC_JAM，不會使用 TRAFFIC_JAM_HEAVY。
road_segment_ids REPEATED STRING 路線沿途的路段，以地點 ID 表示
speed_reading_offsets REPEATED RECORD 以偏移量為基礎的速度讀取間隔，代表整條路線的車流密度；每個間隔都以路線起點的距離偏移量為界。如果 has_road_closure 為 true，則會省略。請參閱「速度讀取間隔」。
speed_reading_offsets.start_offset 可以為空值 INTEGER 間隔起點與路線起點的距離偏移量 (以公尺為單位，含)
speed_reading_offsets.end_offset 可以為空值 INTEGER 間隔結束時與路線起點的距離偏移量 (以公尺為單位，不含；等於後續間隔的 start_offset)
speed_reading_offsets.speed 可以為空值 STRING 這個區間的速度分類，與 Google 地圖路況圖層中的顏色一致。可能的值：NORMAL (綠色)、SLOW (黃色)、TRAFFIC_JAM (紅色)、TRAFFIC_JAM_HEAVY (深紅色，2026 年 10 月 8 日起提供)
has_road_closure 可以為空值 BOOLEAN 路線是否完全封閉。true、duration_in_seconds 和 speed_reading_offsets 則因路線無法通行而省略。NULL 值表示道路封閉資訊不確定。

表格行為和事實

  • 資料表按天分區，每個分區的到期時間設為 60 天。
  • 資料表每小時會更新一次，並以批次方式寫入最新流量資料。
  • 在 Roads Selection API 中建立新路線後，最多可能需要等待 1 小時，才能在這個資料表中看到可用資料。
  • 從 Roads Selection API 刪除路線後，系統就不會再將該路線的新資料寫入這個資料表。不過，歷來資料會保留到到期為止。
  • 路線上的路段會按照拓撲順序排列，且一律會相連。
  • 2026 年 10 月 8 日當天或之後記錄的資料列，會填入 speed_reading_offsets 欄。較早的資料列含有空白陣列。
  • 2026 年 11 月 9 日當天或之後，系統可能會停止填入舊版 speed_reading_intervals 欄。改用 speed_reading_offsets。
  • has_road_closure 旗標與 Google 地圖上的道路封閉狀態一致。

routes_status 個資料表

表格中包含所選路徑的中繼資料和狀態資訊。這個頁面旨在提供更簡單的方式，讓您查看所有路徑和狀態。這份資料表可與另外兩份資料表彙整，用於篩選資料。以下是 BigQuery 中的結構定義：

名稱 模式 類型 說明
selected_route_id 可以為空值 STRING 路線的 selected_route_id
display_name 可以為空值 STRING 路徑的顯示名稱
status* 可以為空值 STRING 路徑狀態
validation_error 可以為空值 STRING 路徑驗證錯誤
low_road_usage_start_time 可以為空值 時間戳記 重新驗證期間，首次觀察到路線道路使用率偏低的時間。與 VALIDATION_ERROR_LOW_ROAD_USAGE 相關聯。
route_attributes 可以為空值 STRING 所選路徑的自訂屬性
dynamic_routing 可以為空值 BOOLEAN 指出路徑是動態 (true) 還是固定 (false)。請參閱 dynamicRouting。
origin 可以為空值 地理位置 路線的起點路線控點
目的地 可以為空值 地理位置 路線的目的地路線控點
中間體 REPEATED 地理位置 路線的中繼路線控點
static_route_geometry 可以為空值 地理位置 計算靜態路線的折線幾何圖形，不含路線控點的即時路況
road_segment_ids REPEATED STRING 沿著靜態路線 (不考量即時路況) 計算出的路段，以地點 ID 表示

表格行為和事實

  • 這個表格只會列出狀態為 STATUS_RUNNING 或 STATUS_INVALID 的路徑。
  • 路徑中繼資料和狀態每小時更新一次，不間斷。
  • 在 Roads Selection API 中建立新路線後，最多可能需要等待 1 小時，該路線才會顯示在這個表格中。
  • 從 Roads Selection API 刪除路線後，最多可能需要等待 1 小時，所選路線才會從這個表格中移除。
  • 如果是固定路線 (dynamic_routing: false)，road_segment_ids 中的地點 ID 會自動更新，反映 Google 道路網路的變化，但仍代表同一條路線。如果是動態路徑 (dynamic_routing: true)，road_segment_ids 則不會更新。