Skip to content

Add NewRoutes to GTFS-RT to support dynamic service (#606) #621

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cleveramarquet wants to merge 14 commits into
base: master
Choose a base branch
from
Open

Add NewRoutes to GTFS-RT to support dynamic service (#606) #621

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
a4aa723
Update gtfs-realtime.proto
cleveramarquet Apr 9, 2026
315d4bc
Update gtfs-realtime.proto
cleveramarquet Apr 9, 2026
6cf9c5b
add Route message and fields for sort order and dates
cleveramarquet Apr 10, 2026
f03724f
add route_sort_order and activation dates to Route message
cleveramarquet Apr 10, 2026
1d169ab
Marked agency and route names as Conditionally Required
cleveramarquet Apr 29, 2026
cf6e0a6
Merge branch 'master' into cleveramarquet-add-new-routes-proposal
cleveramarquet Oct 16, 2026
8f6d060
Add route_id to TripProperties
cleveramarquet Oct 23, 2026
907e9cf
Clarify static vs dynamic route_id in reference.md
cleveramarquet Oct 23, 2026
df7a18d
Add route_id description to TripProperties table
cleveramarquet Oct 28, 2026
321aca2
Update gtfs-realtime/spec/en/reference.md
cleveramarquet Nov 2, 2026
83e5b69
Update gtfs-realtime/spec/en/reference.md
cleveramarquet Nov 10, 2026
9b11f48
Update reference.md
cleveramarquet Nov 10, 2026
a7b870c
Update reference.md
cleveramarquet Nov 10, 2026
1adb147
Update reference.md
cleveramarquet Nov 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions gtfs-realtime/proto/gtfs-realtime.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,7 @@ message FeedEntity {
optional Shape shape = 6;
optional Stop stop = 7;
optional TripModifications trip_modifications = 8;
optional Route route = 9;

// The extensions namespace allows 3rd-party developers to extend the
// GTFS Realtime Specification in order to add and evaluate new features and
Expand Down Expand Up @@ -424,6 +425,10 @@ message TripUpdate {
// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
optional string trip_short_name = 6;

// Specify the route associated with the trip, if the route has been added dynamically. The associated `Route` message should be included in the same feed.
// Optional if schedule_relationship is NEW, forbidden otherwise.
optional string route_id = 7;

// The extensions namespace allows 3rd-party developers to extend the
// GTFS Realtime Specification in order to add and evaluate new features
// and modifications to the spec.
Expand Down Expand Up @@ -806,6 +811,8 @@ message TripDescriptor {
optional string trip_id = 1;

// The route_id from the GTFS that this selector refers to.
// This field is used to identify a trip inside an existing static GTFS, not to dynamically create or insert new routes
// To assign routes dynamically, use the `trip_properties.route_id` field.
Comment thread
cleveramarquet marked this conversation as resolved.
Resolved
optional string route_id = 5;

// The direction_id from the GTFS feed trips.txt file, indicating the
Expand Down Expand Up @@ -1231,6 +1238,60 @@ message TripModifications {
extensions 9000 to 9999;
}

// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
message Route {
// Identifier of the route. Must be different than any route_id defined in the (CSV) GTFS.
// Required
optional string route_id = 1;

// See definition of routes.agency_id in (CSV) GTFS.
// Conditionally Required, see reference
optional string agency_id = 2;

// See definition of routes.route_short_name in (CSV) GTFS.
// Conditionally Required, see reference
optional TranslatedString route_short_name = 3;

// See definition of routes.route_long_name in (CSV) GTFS.
// Conditionally Required, see reference
optional TranslatedString route_long_name = 4;

// See definition of routes.route_desc in (CSV) GTFS.
optional TranslatedString route_desc = 5;

// See definition of routes.route_type in (CSV) GTFS.
// Required
optional int32 route_type = 6;

// See definition of routes.route_url in (CSV) GTFS.
optional TranslatedString route_url = 7;

// See definition of routes.route_color in (CSV) GTFS.
optional string route_color = 8;

// See definition of routes.route_text_color in (CSV) GTFS.
optional string route_text_color = 9;

// See definition of routes.route_sort_order in (CSV) GTFS.
optional uint32 route_sort_order = 10;

// See definition of calendar.start_date in (CSV) GTFS.
// The first day that the new route is active, in YYYYMMDD format.
optional string start_date = 11;

// See definition of calendar.end_date in (CSV) GTFS.
// The last day that the new route is active, in YYYYMMDD format.
optional string end_date = 12;

// The extensions namespace allows 3rd-party developers to extend the
// GTFS Realtime Specification in order to add and evaluate new features and
// modifications to the spec.
extensions 1000 to 1999;

// The following extension IDs are reserved for private use by any organization.
extensions 9000 to 9999;
}

// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
// Select a stop by stop sequence or by stop_id. At least one of the two values must be provided.
message StopSelector {
Expand Down
23 changes: 21 additions & 2 deletions gtfs-realtime/spec/en/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,10 +132,10 @@ A definition (or update) of an entity in the transit feed. If the entity is not
| **trip_update** | [TripUpdate](#message-tripupdate) | Conditionally required | One | Data about the realtime departure delays of a trip. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty. |
| **vehicle** | [VehiclePosition](#message-vehicleposition) | Conditionally required | One | Data about the realtime position of a vehicle. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty. |
| **alert** | [Alert](#message-alert) | Conditionally required | One | Data about the realtime alert. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty. |
| **shape** | [Shape](#message-shape) | Conditionally required | One | Data about the realtime added shapes, such as for a detour. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty. <br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |
| **shape** | [Shape](#message-shape) | Conditionally required | One | Data about the realtime added shapes, such as for a detour. At least one of the fields trip_update, vehicle, alert, shape or route must be provided - all these fields cannot be empty. <br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |
| **stop** | [Stop](#message-stop) | Conditionally required | One | A new stop added to the feed dynamically. <br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |
| **trip_modifications** | [TripModifications](#message-tripmodifications) | Conditionally required | One | List of trips affected by a particular modifications, such as a detour. <br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |

| **route** | [Route](#message-route) | Conditionally required | One | Data about a new route added to the feed dynamically, such as a bus bridge. <br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |

@phil-swiftly phil-swiftly Nov 3, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In order to clarify the Conditionally required status of this FeedEntity, I think route needs to be added to the list in the FeedEntity description of which at least one entity type must be entered. Link here

@cleveramarquet cleveramarquet Nov 10, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@phil-swiftly, thank you for the thorough review! I've added route to the FeedEntity conditionally required entity types list in the latest commits to reference.md. Let me know if this can be resolved.


## _message_ TripUpdate

Expand Down Expand Up @@ -264,6 +264,7 @@ Defines updated properties of the trip.
| **shape_id** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Optional | One | Specifies the identifier of the shape of the vehicle travel path when the trip shape differs from the shape specified in (CSV) GTFS or to specify it in real-time when it's not provided by (CSV) GTFS, such as a vehicle that takes differing paths based on rider demand. See definition of `trips.shape_id` in (CSV) GTFS. <br>If a shape is neither defined in (CSV) GTFS nor in real-time, the shape is considered unknown. This field can refer to a shape defined in the (CSV) GTFS in shapes.txt or a `Shape` in the same (protobuf) real-time feed. The order of stops (stop sequences) for this trip must remain the same as (CSV) GTFS. If it refers to a `Shape` entity in the same real-time feed, the value of this field should be the one of the `shape_id` inside the entity, and _not_ the `id` of `FeedEntity`.<br>Stops that are a part of the original trip but will no longer be made, such as when a detour occurs, should be marked as schedule_relationship=SKIPPED or more details can be provided via a `TripModifications` message.<br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |
| **trip_headsign** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Optional | One | Specifies the headsign for this trip when it differs from the original. <br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |
| **trip_short_name** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Optional | One | Specifies the name for this trip when it differs from the original. <br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |
| **route_id** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Optional | One | Specifies the route associated with the trip, if the route has been added dynamically. The associated `Route` message should be included in the same feed. Optional if `schedule_relationship` is `NEW`, and forbidden otherwise. <br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.|

## _message_ VehiclePosition

Expand Down Expand Up @@ -734,3 +735,21 @@ _If a modification affects the first stop of the trip, that stop also serves as
|------------------|------------|----------------|-------------------|-------------------|
| **stop_id** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Required | One | The replacement stop ID which will now be visited by the trip. May refer to a new stop added using a GTFS-RT `Stop` message in the same GTFS-RT feed, or to an existing stop defined in the (CSV) GTFS feed’s `stops.txt`. If it refers to a `Shape` entity in the real-time feed, the value of this field should be the one of the `stop_id` inside the entity, and _not_ the `id` of `FeedEntity`. The stop MUST have `location_type=0` (routable stops). |
| **travel_time_to_stop** | [int32](https://protobuf.dev/programming-guides/proto2/#scalar) | Optional | One | The difference in seconds between the arrival time at this stop and the arrival time at the reference stop. The reference stop is the stop prior to `start_stop_selector`. If the modification begins at the first stop of the trip, then the first stop of the trip is the reference stop. <br/><br/>This value MUST be monotonically increasing and may only be a negative number if the first stop of the original trip is the reference stop. <br/><br/>If the value is not supplied, consumers MAY interpolate or infer the `travel_time_to_stop` based on other data. |

## _message_ Route
Real-time information about a transit route. This message is used to dynamically define a route that does not exist in the static GTFS.

| _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ |
| :--- | :--- | :--- | :--- | :--- |
| **route_id** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Required | One | Identifier of the route. Must be different than any route_id defined in the static GTFS. Note: route_id should not be reused for different disruptions or car pools on the same service day.|
| **agency_id** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Conditionally Required | One | Agency which operates the route. See [routes.agency_id](https://gtfs.org/schedule/reference/#routestxt). |
| **route_short_name** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Conditionally Required | One | Short name of the route. See [routes.route_short_name](https://gtfs.org/schedule/reference/#routestxt). |
| **route_long_name** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Conditionally Required | One | Long name of the route. See [routes.route_long_name](https://gtfs.org/schedule/reference/#routestxt). |
| **route_desc** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Optional | One | Description of the route. See [routes.route_desc](https://gtfs.org/schedule/reference/#routestxt). |
| **route_type** | [int32](https://protobuf.dev/programming-guides/proto2/#scalar) | Required | One | Describes the type of transportation used on a route. See [routes.route_type](https://gtfs.org/schedule/reference/#routestxt). |
| **route_url** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Optional | One | URL of a web page about the route. See [routes.route_url](https://gtfs.org/schedule/reference/#routestxt). |
| **route_color** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Optional | One | Route color in RGB hex format. See [routes.route_color](https://gtfs.org/schedule/reference/#routestxt). |
| **route_text_color** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Optional | One | Route text color in RGB hex format. See [routes.route_text_color](https://gtfs.org/schedule/reference/#routestxt). |
| **route_sort_order** | [uint32](https://protobuf.dev/programming-guides/proto2/#scalar) | Optional | One | A non-negative integer used to specify the order in which the routes should be displayed. |
| **start_date** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Optional | One | The first day that the new route is active, in YYYYMMDD format. |
| **end_date** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Optional | One | The last day that the new route is active, in YYYYMMDD format. |
Loading