累積道路資料會以時間序列資料的形式提供,包括:
- 行程期間
- 車速讀取間隔 (SRI)
- 路線幾何圖形
設定 BigQuery
您必須先設定 Google Cloud 雲端專案並訂閱資料交換庫,才能在 BigQuery 中存取道路資料。
必要條件
確認 Google Cloud 雲端專案和帳戶具有下列設定:
- 啟用 BigQuery API。如需操作說明,請參閱「使用 Google Cloud 控制台查詢公開資料集」。
- 啟用 Analytics Hub API。請參閱「Analytics Hub API」。
- 授予必要的 IAM 角色。請確認您的帳戶具備下列角色,可執行訂閱者工作及建立資料集:
- Analytics Hub 訂閱者
(
roles/analyticshub.subscriber)- BigQuery 使用者 (
roles/bigquery.user)
- BigQuery 使用者 (
訂閱資料交換
道路資料會透過 BigQuery (Analytics Hub) 的私人資料交換與您共用。您會收到 Google 合作夥伴提供的特定訂閱連結,用於存取資料。這個資料集遵循下列命名慣例:
historical_roads_data_PROJECT_NUMBER.
如要訂閱資料,請按照下列步驟操作:
- 按一下 Google 合作夥伴提供的訂閱連結。點選這個連結,即可直接前往 Google Cloud 控制台中的資料交換。
- 在 Google Cloud 控制台中,查看資料交換詳細資料。
- 按一下對話方塊中的「訂閱」按鈕。
- 訂閱完成後,連結的資料集會顯示在 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 | 舊版座標式速度讀取間隔。2027 年 1 月 13 日當天或之後,可能就不會再填入資料。請改用 speed_reading_offsets。請參閱「速度讀取間隔」。 |
| speed_reading_intervals.interval_coordinates | REPEATED | 地理位置 | 舊版。2027 年 1 月 13 日當天或之後,可能停止填入資料。請改用 speed_reading_offsets。這個間隔的幾何圖形 |
| speed_reading_intervals.speed | 可以為空值 | STRING | 舊版。2027 年 1 月 13 日當天或之後,可能停止填入資料。請改用 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欄。較早的資料列含有空白陣列。 - 2027 年 1 月 13 日當天或之後,舊版
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則不會更新。