Extensions¶
Additional files and fields can be extended onto GTFS Schedule datasets to accommodate a variety of application-specific needs communicated between transit agencies and software vendors, even if these fields are not in the official specification.
Below is a list of GTFS Schedule extensions that may be implemented. ➕
Making an extension official in the specification
Extensions may become active proposals and subsequently merged into the official specification via the Specification Amendment Process.
Contributing to this list
Have an extension you want to share with the GTFS community? Request to add an extension to GTFS.org here.
GTFS-Pathways
Maintained by MobilityData
- Accessibility-focused for pathways linking together locations within transit stations for route planning and wayfinding.
- While the core specification of GTFS-Pathways has been completely integrated into GTFS, additional information such as text-to-speech instructions, wheelchair assistance information, equipment-failure reporting, planned or scheduled entrance or exit closures, and elevator and escalator outages need to be added.
GTFS-Fares v2
Maintained by MobilityData
- Enables trip planning apps to display pricing information to riders.
- While the base implementation of GTFS-Fares v2 has recently been voted to pass into GTFS, some features and functionalities of this extension that are still remaining include zonal/distance-based fares, rider categories, fare capping and ranges, fare bundles passes and containers, rush hour/holiday pricing, transfer sequences, and one route behaviour.
GTFS-Flex
Maintained by MobilityData
- Extends GTFS by including deviated fixed routes and on-demand transportation service features in its data modeling that do not always follow the same for fixed stops.
- The proposal is composed of 2 extensions: GTFS-FlexibleTrips, which describes the service itself and GTFS-BookingRules, which provides the booking information of GTFS-FlexibleTrips.
GTFS-Occupancies
Maintained by MobilityData
- Describes a vehicle’s passenger crowdedness on a usual or projected basis.
- Supplements the availability of crowdedness information described in GTFS Realtime by offering static predictions for future trips based on previous trends, which can assist riders plan trips based on their crowdedness preferences and comfortability.
Google Transit Extensions to GTFS
Maintained by Google
- Provides translation support, extends route types, allows for more detailed transfer rules and adds a number of other functions.
- Created by the San Francisco Bay Area Metropolitan Transportation Commission. Adds additional real time information, directions, rider categories and more.
- Adds on-time performance tracking checkpoints, station and facility information and more.
GTFS-Eligibilities
Maintained by the Oregon Department of Transportation
GTFS-eligibilities is formed around the concept that it should provide a manner for systems operating based on user accounts to understand whether a trip is eligible based on user account information. This means the fields proposed provide:
- Common attributes associated with user accounts such as age, gender, company affiliation, trip purposes, and assistance levels provided.
- Customizable authentications of locally-defined attributes and statuses. Custom eligibilities are provided, as well as a way to understand how the custom eligibility can be authenticated.
GTFS-Capabilities
Maintained by the Oregon Department of Transportation
Describes the additional capabilities that a service may be able to provide to serve people with disabilities and those who have mobility devices.
- Information about services available to a rider from a person, such as a driver or other agency-provided human resource.
- Vehicle information, described by the (further extended) GTFS-VehicleCategories specification. See also the GTFS-seats draft extension.
- A focus on describing vehicle amenities related to mobility devices, and how boarding with those devices affects capacity for other riders and devices.
Additional files and fields can be extended onto GTFS Realtime feeds to accommodate a variety of application-specific needs communicated between transit agencies and software vendors, even if these fields are not in the official specification.
Below is a list of GTFS Realtime extensions that may be implemented. ➕
Making an extension official in the specification
Extensions may become active proposals and subsequently merged into the official specification via the Specification Amendment Process.
Contributing to this list
Have an extension you want to share with the GTFS community? Request to add an extension to GTFS.org here.
GTFS-PathwayUpdates
Maintained by MobilityData
- Describe changes to station pathways in real time such as elevator downtime or closed pathways.
GTFS-OccupancyStatus
Maintained by MobilityData
- Provide information in real time on the crowding of transit vehicles.
Protobuf Extensions¶
To allow producers to add custom information to a GTFS Realtime feed, we will take advantage of the Extensions feature of Protocol Buffers. Extensions allow us to define a namespace in a Protocol Buffer message where third-party developers can define additional fields without the need to modify the original proto definition.
When possible we should avoid extensions and add fields useful to many agencies to the main specification to avoid fragmentation and extra work for consumers to support various extensions to the spec. Before requesting an extension id, producers should propose adding the field to the specification (see Adding new fields to GTFS Realtime).
The extension IDs within the range 9000-9999 are reserved for private use by GTFS-rt producers. These IDs should only be used to convey information internally to your organization. Extensions in this range must not be used in public feeds.
To create a new extension, we will assign a producer the next available extension id, picked incrementally from a list of numbers starting at 1000 and going up and documented in the Extension Registry section found below.
These assigned extension ids corresponds to the tag ids available in the "extension" namespace for each GTFS Realtime message definition. Now that the developer has an assigned extension id, they will use that id when extending any and all GTFS Realtime messages. Even if the developer only plans to extend a single message, the assigned extension id will be reserved for ALL messages.
For a developer extending the spec, instead of adding a single field like a "string" or "int32" with their extension id, the preferred model is to define a new message like "MyTripDescriptorExtension", extend the underlying GTFS Realtime message with your new message, and then put all your new fields in there. This has the nice property that you can manage fields within your extension message however you want, without needing to reserve a new extension id from the master list.
message MyTripDescriptorExtension {
optional string some_string = 1;
optional bool some_bool = 2;
...
}
extend transit_realtime.TripDescriptor {
optional MyTripDescriptorExtension my_trip_descriptor = YOUR_EXTENSION_ID;
}
When creating extensions, developers should follow the Protocol Buffers Language Guide. A common mistake is re-using an extension field number. In the Assigning Field Numbers section, the Language Guide says:
Each field in the message definition has a unique number. These numbers are used to identify your fields in the message binary format, and should not be changed once your message type is in use.
For example, in the first example some_string
was assigned field number 1
. When the developer no longer wishes to use some_string
, or when some_string
has been adopted in the official GTFS Realtime spec and there is no need for the extension, the developer cannot re-use field number 1
for a new field. Instead, the developer should deprecate the field and use a new number for the new field:
message MyTripDescriptorExtension {
optional string some_string = 1 [deprecated=true];
optional bool some_bool = 2;
optional string some_new_string = 3;
...
}
Extension Registry¶
Extension ID | Developer | Contact | Details |
---|---|---|---|
1000 | OneBusAway | onebusaway-developers | https://github.com/OneBusAway/onebusaway/wiki/GTFS-Realtime-Resources |
1001 | New York City MTA | mtadeveloperresources | https://mta.info/developers/ |
1002 | transit-realtime-partner-support@google.com | Google Maps Live Transit Updates | |
1003 | OVapi | gtfs-rt at ovapi.nl | https://gtfs.ovapi.nl |
1004 | Metra | William Ashbaugh w.l.ashbaugh@gmail.com | |
1005 | Metro-North Railroad | John Larsen | |
1006 | realCity | David Varga | https://realcity.io |
1007 | Transport for NSW | timetable@transport.nsw.gov.au | Group discussion |
1008 | SEPTA - Southeastern Pennsylvania Transportation Authority | Gregory Apessos | https://github.com/septadev |
1009 | Swiftly | mike@goswift.ly | Group Discussion |
1010 | IBI Group | Ritesh Warade | GitHub proposal for new timestamps in Service Alerts |
1013 | MITFAHR|DE|ZENTRALE (MFDZ) | Holger Bruch | Group discussion |
9000-9999 | RESERVED - INTERNAL USE ONLY | GTFS Community | Group discussion |
For more information, contact specifications@mobilitydata.org