실시간 도로 데이터는 선택한 경로의 도로 상황 및 이벤트에 대한 최신 업데이트를 제공하여 동적 모니터링과 신속한 대응을 지원합니다. 이 데이터는 BigQuery에서 사용할 수 있는 주기적으로 수집된 데이터와 다르며 시의적절한 정보가 필요한 시나리오에 적합합니다.
이 데이터는 지속적으로 스트리밍되며 경로의 이동 시간을 나타내는 이동 시간과 경로의 교통 밀도를 보여주는 속도 판독 간격이 포함됩니다.
실시간 도로 데이터에 액세스하려면 계약에 실시간 운영 패키지가 포함되어야 합니다.
이동 시간 및 속도 측정 간격 Pub/Sub 구독 만들기
전용 Google Cloud Pub/Sub 주제가 제공되며, 여기에서 생성된 모든 경로의 실시간 데이터를 구독할 수 있습니다.
다음 코드 샘플은 바이너리 인코딩을 사용하는 주제의 형식을 보여줍니다.
projects/maps-platform-roads-management/topics/rmi-roadsinformation-PROJECT_NUMBER
또한 JSON 인코딩을 사용하는 다른 주제도 제공합니다 (-json로 끝남). 실시간 데이터 메시지를 수신하려면 제공된 Pub/Sub 주제를 구독해야 합니다. Cloud Pub/Sub 주제에서 메시지를 구독하고 사용하는 방법에 대한 간략한 개요는 주제 구독을 참조하세요.
이동 시간 및 속도 판독 간격 스키마
각 실시간 데이터 메시지에는 다음과 같은 데이터가 포함됩니다.
duration_in_seconds,static_duration_in_seconds,speed_reading_offsets(오프셋 기반 속도 판독 간격),retrieval_timestamp,has_road_closure와 같은 도로 세부정보selected_route_id및display_name와 같은 경로 식별자
각 메시지는 다음 Protobuf 형식을 준수하여 게시됩니다.
syntax = "proto3"; // Contains the road information like travel duration and speed reading // intervals for a selected route. message RoadsInformation { // Legacy message. May stop being populated on or after November 9, 2026. // Use top-level duration_in_seconds and static_duration_in_seconds instead. message TravelDuration { // The duration of travel through the route based on current road // conditions. float duration_in_seconds = 1; // The duration of travel through the route without taking road // conditions into consideration. float static_duration_in_seconds = 2; } message Timestamp { // Represents seconds of UTC time since Unix epoch // 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to // 9999-12-31T23:59:59Z inclusive. int64 seconds = 1; // Non-negative fractions of a second at nanosecond resolution. Negative // second values with fractions must still have non-negative nanos values // that count forward in time. Must be from 0 to 999,999,999 // inclusive. int32 nanos = 2; } // Legacy message representing the latitude and longitude of a coordinate // within a coordinate-based speed reading interval. message LatLng { float latitude = 1; float longitude = 2; } // Legacy coordinate-based speed reading interval message. May stop being // populated on or after November 9, 2026. Use SpeedReadingOffset instead. message SpeedReadingInterval { // The coordinates on the polyline for the speed reading interval. repeated LatLng interval_coordinates = 1; // Describes the categorized current speed of road conditions. // Possible values are: // - "NORMAL": Road is flowing smoothly, no slowdown is detected. // - "SLOW": Slowdown detected, but no congestion formed. // - "TRAFFIC_JAM": Traffic jam detected. In this legacy field, heavy // traffic jams (dark red) are also reported as "TRAFFIC_JAM"; // "TRAFFIC_JAM_HEAVY" is never used. string speed = 2; } // Offset-based speed reading interval along the route. message SpeedReadingOffset { // The distance offset from the start of the route in meters for the start // of the interval (inclusive). int32 start_offset = 1; // The distance offset from the start of the route in meters for the end of // the interval (exclusive; equals the start_offset of the subsequent // interval). int32 end_offset = 2; // Describes the categorized current speed of traffic, aligned with the // colors in the Google Maps traffic layer. Possible values are: // - "NORMAL" (green): Traffic is flowing smoothly, no slowdown is detected. // - "SLOW" (yellow): Slowdown detected, but no traffic jam formed. // - "TRAFFIC_JAM" (red): Traffic jam detected. // - "TRAFFIC_JAM_HEAVY" (dark red): Heavy traffic jam detected (available // as of October 8, 2026). string speed = 3; } // Id for selected_route. string selected_route_id = 1; // User provided name for the route. string display_name = 2; // Legacy coordinate-based speed reading intervals. May stop being populated // on or after November 9, 2026. Use speed_reading_offsets instead. repeated SpeedReadingInterval speed_reading_intervals = 3; // Legacy travel time information. May stop being populated on or after // November 9, 2026. Use duration_in_seconds and static_duration_in_seconds // instead. TravelDuration travel_duration = 4; // Legacy timestamp when the road data was collected. May stop being populated // on or after November 9, 2026. Use retrieval_timestamp instead. Timestamp retrieval_time = 5; // Contains a geojson polyline representing the optimal route determined // based on user's input waypoints. string route_geometry = 6; // Road segment place IDs along the route. They follow topological order // and are always connected. repeated string road_segment_ids = 7; // Offset-based speed reading intervals representing traffic density across // the route; each interval is demarcated by the distance offset from the // start of the route. Omitted when has_road_closure is true. repeated SpeedReadingOffset speed_reading_offsets = 8; // The duration of travel through the route based on current traffic // conditions. Omitted when has_road_closure is true. float duration_in_seconds = 9; // The duration of travel through the route without taking traffic // conditions into consideration. float static_duration_in_seconds = 10; // The time the traffic data was collected, as an RFC 3339 UTC timestamp // string (for example, "2026-10-08T15:04:05+00:00"). string retrieval_timestamp = 11; // Whether there is a full road closure on the route. When true, // duration_in_seconds and speed_reading_offsets are omitted because the // route is impassable. Omitted when road closure information is undetermined. bool has_road_closure = 12; }
오프셋 기반 속도 판독 간격 및 필드 이전
2026년 10월 8일부터 속도 판독 구간은 오프셋 기반 speed_reading_offsets 필드에 제공됩니다. 여기서 각 구간은 경로 시작 지점으로부터의 start_offset (포함) 및 end_offset (제외)로 구분되며 네 번째 속도 카테고리 TRAFFIC_JAM_HEAVY를 포함합니다. 속도 카테고리 및 간격 형식에 대한 자세한 내용은 속도 읽기 간격을 참조하세요.
다음 표는 각 기존 Pub/Sub 필드 (2026년 11월 9일 이후에 채워지지 않을 수 있음)를 대체 필드에 매핑합니다.
| 기존 필드 | 대체 필드 | 참고 |
|---|---|---|
speed_reading_intervals |
speed_reading_offsets |
다중선 좌표 대신 미터 오프셋 (start_offset, end_offset)을 사용하고 TRAFFIC_JAM_HEAVY 속도 카테고리를 추가합니다. |
travel_duration.duration_in_seconds |
duration_in_seconds |
최상위 float 필드로 평면화되었습니다. |
travel_duration.static_duration_in_seconds |
static_duration_in_seconds |
최상위 float 필드로 평면화되었습니다. |
retrieval_time |
retrieval_timestamp |
RFC 3339 문자열로 형식이 지정되며, BigQuery 구독은 이를 TIMESTAMP로 자동 변환합니다. |
Pub/Sub를 사용하여 BigQuery로 경로 데이터 스트리밍
도로 데이터를 BigQuery 테이블로 직접 스트리밍하도록 Pub/Sub 구독을 구성할 수 있습니다. 이를 통해 강력한 데이터 스토리지를 제공하고 제공된 경로 정보에 대한 강력한 분석을 지원합니다. 이 유형의 구독을 설정하기 전에 데이터를 쓸 BigQuery 프로젝트에 적합한 데이터 세트와 테이블을 만들어야 합니다.
BigQuery에 쓰는 Pub/Sub 구독을 만드는 방법에 대한 자세한 안내는 BigQuery로 데이터 스트리밍을 참조하세요.
JSON으로 인코딩된 주제에 BigQuery 구독을 만듭니다. 구독을 구성할 때 테이블 스키마 사용을 선택하고 알 수 없는 필드 삭제를 사용 설정하여 새 필드가 추가될 때 수집 파이프라인이 원활하게 계속 실행되도록 합니다. speed_reading_offsets와 같은 새 필드를 저장하려면 테이블에 해당 열을 추가합니다.
BigQuery 테이블 스키마
Pub/Sub 주제에 게시된 메시지(BigQuery 테이블에 기록될 수도 있음)는 다음 스키마를 따릅니다. 호환성을 보장하려면 대상 BigQuery 테이블을 만들 때 이 스키마를 사용해야 합니다.
[ { "mode": "NULLABLE", "name": "selected_route_id", "type": "STRING", "description": "Id for selected_route." }, { "mode": "NULLABLE", "name": "display_name", "type": "STRING", "description": "User provided name for the route." }, { "fields": [ { "mode": "NULLABLE", "name": "speed", "type": "STRING", "description": "Describes the categorized current speed of traffic. Possible values are: \"NORMAL\": Traffic is flowing smoothly, no slowdown is detected. \"SLOW\": Slowdown detected, but no traffic jam formed. \"TRAFFIC_JAM\": Traffic jam detected (groups red and dark red segments; does not include \"TRAFFIC_JAM_HEAVY\")." }, { "fields": [ { "mode": "NULLABLE", "name": "latitude", "type": "NUMERIC" }, { "mode": "NULLABLE", "name": "longitude", "type": "NUMERIC" } ], "mode": "REPEATED", "name": "interval_coordinates", "type": "RECORD", "description": "The geometry for this interval" } ], "mode": "REPEATED", "name": "speed_reading_intervals", "type": "RECORD", "description": "Legacy coordinate-based speed reading intervals. May stop being populated on or after November 9, 2026. Use speed_reading_offsets instead." }, { "fields": [ { "mode": "NULLABLE", "name": "duration_in_seconds", "type": "FLOAT", "description": "The duration of travel through the route based on\ncurrent traffic conditions." }, { "mode": "NULLABLE", "name": "static_duration_in_seconds", "type": "FLOAT", "description": "The duration of travel through the route without\ntaking traffic conditions into consideration." } ], "mode": "NULLABLE", "name": "travel_duration", "type": "RECORD", "description": "Legacy travel time information. May stop being populated on or after November 9, 2026. Use top-level duration_in_seconds and static_duration_in_seconds instead." }, { "fields": [ { "mode": "NULLABLE", "name": "seconds", "type": "INTEGER", "description": "Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive." }, { "mode": "NULLABLE", "name": "nanos", "type": "INTEGER", "description": "Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive." } ], "mode": "NULLABLE", "name": "retrieval_time", "type": "RECORD", "description": "Legacy timestamp when the traffic data was collected. May stop being populated on or after November 9, 2026. Use retrieval_timestamp instead." }, { "mode": "NULLABLE", "name": "route_geometry", "type": "STRING", "description": "Contains a geojson polyline representing the optimal route determined based on user's input waypoints" }, { "mode": "REPEATED", "name": "road_segment_ids", "type": "STRING", "description": "Road segment place IDs along the route. They follow topological order and are always connected" }, { "fields": [ { "mode": "NULLABLE", "name": "start_offset", "type": "INTEGER", "description": "The distance offset from the start of the route in meters for the start of the interval (inclusive)." }, { "mode": "NULLABLE", "name": "end_offset", "type": "INTEGER", "description": "The distance offset from the start of the route in meters for the end of the interval (exclusive; equals the start_offset of the subsequent interval)." }, { "mode": "NULLABLE", "name": "speed", "type": "STRING", "description": "Describes the categorized current speed of traffic, aligned with the colors in the Google Maps traffic layer. Possible values are: \"NORMAL\" (green): Traffic is flowing smoothly, no slowdown is detected. \"SLOW\" (yellow): Slowdown detected, but no traffic jam formed. \"TRAFFIC_JAM\" (red): Traffic jam detected. \"TRAFFIC_JAM_HEAVY\" (dark red): Heavy traffic jam detected (available as of October 8, 2026)." } ], "mode": "REPEATED", "name": "speed_reading_offsets", "type": "RECORD", "description": "Offset-based speed reading intervals representing traffic density across the route; each interval is demarcated by the distance offset from the start of the route. Omitted when has_road_closure is true." }, { "mode": "NULLABLE", "name": "duration_in_seconds", "type": "FLOAT", "description": "The duration of travel through the route based on current traffic conditions. Omitted when has_road_closure is true." }, { "mode": "NULLABLE", "name": "static_duration_in_seconds", "type": "FLOAT", "description": "The duration of travel through the route without taking traffic conditions into consideration." }, { "mode": "NULLABLE", "name": "retrieval_timestamp", "type": "TIMESTAMP", "description": "The time the traffic data was collected." }, { "mode": "NULLABLE", "name": "has_road_closure", "type": "BOOLEAN", "description": "Whether there is a full road closure on the route. When true, duration_in_seconds and speed_reading_offsets are omitted because the route is impassable. A NULL value indicates that road closure information is undetermined." } ]