A GTFS Realtime feed lets transit agencies provide consumers with realtime information about disruptions to their service (stations closed, lines not operating, important delays, etc.) location of their vehicles, and expected arrival times.
Version 2.0 of the feed specification is discussed and documented on this site.
In GTFS-realtime v2.0 and higher, the Required column describes what fields must be provided by a producer in order for the transit data to be valid and make sense to a consuming application.
The following values are used in the Required field:
- Required: This field must be provided by a GTFS-realtime feed producer.
- Conditionally required: This field is required under certain conditions, which are outlined in the field Description. Outside of these conditions, the field is optional.
- Optional: This field is optional and is not required to be implemented by producers. However, if the data is available in the underlying automatic vehicle location systems (e.g., VehiclePosition
timestamp) it is recommended that producers provide these optional fields when possible.
Note that semantic requirements were not defined in GTFS-realtime version 1.0, and therefore feeds with
1 may not meet these requirements (see the proposal for semantic requirements for details).
Cardinality represents the number of elements that may be provided for a particular field, with the following values:
- One - A single one element may be provided for this field. This maps to the Protocol Buffer required and optional cardinalities.
- Many - Many elements (0, 1, or more) may be provided for this field. This maps to the Protocol Buffer repeated cardinality.
Always reference the Required and Description fields to see when a field is required, conditionally required, or optional. Please reference
gtfs-realtime.proto for Protocol Buffer cardinality.
Protocol Buffer data types
The following protocol buffer data types are used to describe feed elements:
- message: Complex type
- enum: List of fixed values
Fields labeled as experimental are subject to change and not yet formally adopted into the specification. An experimental field may be formally adopted in the future.
The contents of a feed message. Each message in the stream is obtained as a response to an appropriate HTTP GET request. A realtime feed is always defined with relation to an existing GTFS feed. All the entity ids are resolved with respect to the GTFS feed.
|header||FeedHeader||Required||One||Metadata about this feed and feed message.|
|entity||FeedEntity||Conditionally required||Many||Contents of the feed. If there is real-time information available for the transit system, this field must be provided. If this field is empty, consumers should assume there is no real-time information available for the system.|
Metadata about a feed, included in feed messages.
|gtfs_realtime_version||string||Required||One||Version of the feed specification. The current version is 2.0.|
|timestamp||uint64||Required||One||This timestamp identifies the moment when the content of this feed has been created (in server time). In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). To avoid time skew between systems producing and consuming realtime information it is strongly advised to derive timestamp from a time server. It is completely acceptable to use Stratum 3 or even lower strata servers since time differences up to a couple of seconds are tolerable.|
Determines whether the current fetch is incremental.
- FULL_DATASET: this feed update will overwrite all preceding realtime information for the feed. Thus this update is expected to provide a full snapshot of all known realtime information.
- DIFFERENTIAL: currently, this mode is unsupported and behavior is unspecified for feeds that use this mode. There are discussions on the GTFS Realtime mailing list around fully specifying the behavior of DIFFERENTIAL mode and the documentation will be updated when those discussions are finalized.
A definition (or update) of an entity in the transit feed. If the entity is not being deleted, exactly one of 'trip_update', 'vehicle' and 'alert' fields should be populated.
|id||string||Required||One||Feed-unique identifier for this entity. The ids are used only to provide incrementality support. The actual entities referenced by the feed must be specified by explicit selectors (see EntitySelector below for more info).|
|is_deleted||bool||Optional||One||Whether this entity is to be deleted. Should be provided only for feeds with Incrementality of DIFFERENTIAL - this field should NOT be provided for feeds with Incrementality of FULL_DATASET.|
|trip_update||TripUpdate||Conditionally required||One||Data about the realtime departure delays of a trip. At least one of the fields trip_update, vehicle, or alert must be provided - all these fields cannot be empty.|
|vehicle||VehiclePosition||Conditionally required||One||Data about the realtime position of a vehicle. At least one of the fields trip_update, vehicle, or alert must be provided - all these fields cannot be empty.|
|alert||Alert||Conditionally required||One||Data about the realtime alert. At least one of the fields trip_update, vehicle, or alert must be provided - all these fields cannot be empty.|
Realtime update on the progress of a vehicle along a trip. Please also refer to the general discussion of the trip updates entities.
Depending on the value of ScheduleRelationship, a TripUpdate can specify:
- A trip that proceeds along the schedule.
- A trip that proceeds along a route but has no fixed schedule.
- A trip that has been added or removed with regard to schedule.
The updates can be for future, predicted arrival/departure events, or for past events that already occurred. In most cases information about past events is a measured value thus its uncertainty value is recommended to be 0. Although there could be cases when this does not hold so it is allowed to have uncertainty value different from 0 for past events. If an update's uncertainty is not 0, either the update is an approximate prediction for a trip that has not completed or the measurement is not precise or the update was a prediction for the past that has not been verified after the event occurred.
Note that the update can describe a trip that has already completed.To this end, it is enough to provide an update for the last stop of the trip. If the time of arrival at the last stop is in the past, the client will conclude that the whole trip is in the past (it is possible, although inconsequential, to also provide updates for preceding stops). This option is most relevant for a trip that has completed ahead of schedule, but according to the schedule, the trip is still proceeding at the current time. Removing the updates for this trip could make the client assume that the trip is still proceeding. Note that the feed provider is allowed, but not required, to purge past updates - this is one case where this would be practically useful.
|trip||TripDescriptor||Required||One||The Trip that this message applies to. There can be at most one TripUpdate entity for each actual trip instance. If there is none, that means there is no prediction information available. It does not mean that the trip is progressing according to schedule.|
|vehicle||VehicleDescriptor||Optional||One||Additional information on the vehicle that is serving this trip.|
|stop_time_update||StopTimeUpdate||Conditionally required||Many||Updates to StopTimes for the trip (both future, i.e., predictions, and in some cases, past ones, i.e., those that already happened). The updates must be sorted by stop_sequence, and apply for all the following stops of the trip up to the next specified stop_time_update. At least one stop_time_update must be provided for the trip unless the trip.schedule_relationship is CANCELED - if the trip is canceled, no stop_time_updates need to be provided.|
|timestamp||uint64||Optional||One||Moment at which the vehicle's real-time progress was measured. In POSIX time (i.e., the number of seconds since January 1st 1970 00:00:00 UTC).|
|delay||int32||Optional||One||The current schedule deviation for the trip. Delay should only be specified when the prediction is given relative to some existing schedule in GTFS.
Delay (in seconds) can be positive (meaning that the vehicle is late) or negative (meaning that the vehicle is ahead of schedule). Delay of 0 means that the vehicle is exactly on time.
Delay information in StopTimeUpdates take precedent of trip-level delay information, such that trip-level delay is only propagated until the next stop along the trip with a StopTimeUpdate delay value specified.
Feed providers are strongly encouraged to provide a TripUpdate.timestamp value indicating when the delay value was last updated, in order to evaluate the freshness of the data.
Caution: this field is still experimental, and subject to change. It may be formally adopted in the future.
Timing information for a single predicted event (either arrival or departure). Timing consists of delay and/or estimated time, and uncertainty.
- delay should be used when the prediction is given relative to some existing schedule in GTFS.
- time should be given whether there is a predicted schedule or not. If both time and delay are specified, time will take precedence (although normally, time, if given for a scheduled trip, should be equal to scheduled time in GTFS + delay).
Uncertainty applies equally to both time and delay. The uncertainty roughly specifies the expected error in true delay (but note, we don't yet define its precise statistical meaning). It's possible for the uncertainty to be 0, for example for trains that are driven under computer timing control.
|delay||int32||Conditionally required||One||Delay (in seconds) can be positive (meaning that the vehicle is late) or negative (meaning that the vehicle is ahead of schedule). Delay of 0 means that the vehicle is exactly on time. Either delay or time must be provided within a StopTimeEvent - both fields cannot be empty.|
|time||int64||Conditionally required||One||Event as absolute time. In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). Either delay or time must be provided within a StopTimeEvent - both fields cannot be empty.|
|uncertainty||int32||Optional||One||If uncertainty is omitted, it is interpreted as unknown. To specify a completely certain prediction, set its uncertainty to 0.|
Realtime update for arrival and/or departure events for a given stop on a trip. Please also refer to the general discussion of stop time updates in the TripDescriptor and trip updates entities documentation.
Updates can be supplied for both past and future events. The producer is allowed, although not required, to drop past events. The update is linked to a specific stop either through stop_sequence or stop_id, so one of these fields must necessarily be set. If the same stop_id is visited more than once in a trip, then stop_sequence should be provided in all StopTimeUpdates for that stop_id on that trip.
|stop_sequence||uint32||Conditionally required||One||Must be the same as in stop_times.txt in the corresponding GTFS feed. Either stop_sequence or stop_id must be provided within a StopTimeUpdate - both fields cannot be empty. stop_sequence is required for trips that visit the same stop_id more than once (e.g., a loop) to disambiguate which stop the prediction is for.|
|stop_id||string||Conditionally required||One||Must be the same as in stops.txt in the corresponding GTFS feed. Either stop_sequence or stop_id must be provided within a StopTimeUpdate - both fields cannot be empty.|
|arrival||StopTimeEvent||Conditionally required||One||If schedule_relationship is empty or SCHEDULED, either arrival or departure must be provided within a StopTimeUpdate - both fields cannot be empty. arrival and departure may both be empty when schedule_relationship is SKIPPED. If schedule_relationship is NO_DATA, arrival and departure must be empty.|
|departure||StopTimeEvent||Conditionally required||One||If schedule_relationship is empty or SCHEDULED, either arrival or departure must be provided within a StopTimeUpdate - both fields cannot be empty. arrival and departure may both be empty when schedule_relationship is SKIPPED. If schedule_relationship is NO_DATA, arrival and departure must be empty.|
|schedule_relationship||ScheduleRelationship||Optional||One||The default relationship is SCHEDULED.|
The relation between this StopTime and the static schedule.
|SCHEDULED||The vehicle is proceeding in accordance with its static schedule of stops, although not necessarily according to the times of the schedule. This is the default behavior. At least one of arrival and departure must be provided.|
|SKIPPED||The stop is skipped, i.e., the vehicle will not stop at this stop. Arrival and departure are optional.|
|NO_DATA||No data is given for this stop. It indicates that there is no realtime information available. When set NO_DATA is propagated through subsequent stops so this is the recommended way of specifying from which stop you do not have realtime information. When NO_DATA is set neither arrival nor departure should be supplied.|
Realtime positioning information for a given vehicle.
|trip||TripDescriptor||Optional||One||The Trip that this vehicle is serving. Can be empty or partial if the vehicle can not be identified with a given trip instance.|
|vehicle||VehicleDescriptor||Optional||One||Additional information on the vehicle that is serving this trip. Each entry should have a unique vehicle id.|
|position||Position||Optional||One||Current position of this vehicle.|
|current_stop_sequence||uint32||Optional||One||The stop sequence index of the current stop. The meaning of current_stop_sequence (i.e., the stop that it refers to) is determined by current_status. If current_status is missing IN_TRANSIT_TO is assumed.|
|stop_id||string||Optional||One||Identifies the current stop. The value must be the same as in stops.txt in the corresponding GTFS feed.|
|current_status||VehicleStopStatus||Optional||One||The exact status of the vehicle with respect to the current stop. Ignored if current_stop_sequence is missing.|
|timestamp||uint64||Optional||One||Moment at which the vehicle's position was measured. In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC).|
|_occupancy_status_||OccupancyStatus||Optional||One||The degree of passenger occupancy of the vehicle.
Caution: this field is still experimental, and subject to change. It may be formally adopted in the future.
|INCOMING_AT||The vehicle is just about to arrive at the stop (on a stop display, the vehicle symbol typically flashes).|
|STOPPED_AT||The vehicle is standing at the stop.|
|IN_TRANSIT_TO||The vehicle has departed the previous stop and is in transit.|
Congestion level that is affecting this vehicle.
The degree of passenger occupancy for the vehicle.
Caution: this field is still experimental, and subject to change. It may be formally adopted in the future.
|EMPTY||The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.|
|_MANY_SEATS_AVAILABLE_||The vehicle has a large percentage of seats available. What percentage of free seats out of the total seats available is to be considered large enough to fall into this category is determined at the discretion of the producer.|
|_FEW_SEATS_AVAILABLE_||The vehicle has a small percentage of seats available. What percentage of free seats out of the total seats available is to be considered small enough to fall into this category is determined at the discretion of the producer.|
|_STANDING_ROOM_ONLY_||The vehicle can currently accommodate only standing passengers.|
|_CRUSHED_STANDING_ROOM_ONLY_||The vehicle can currently accommodate only standing passengers and has limited space for them.|
|FULL||The vehicle is considered full by most measures, but may still be allowing passengers to board.|
|_NOT_ACCEPTING_PASSENGERS_||The vehicle can not accept passengers.|
An alert, indicating some sort of incident in the public transit network.
|active_period||TimeRange||Optional||Many||Time when the alert should be shown to the user. If missing, the alert will be shown as long as it appears in the feed. If multiple ranges are given, the alert will be shown during all of them.|
|informed_entity||EntitySelector||Required||Many||Entities whose users we should notify of this alert. At least one informed_entity must be provided.|
|url||TranslatedString||Optional||One||The URL which provides additional information about the alert.|
|header_text||TranslatedString||Required||One||Header for the alert. This plain-text string will be highlighted, for example in boldface.|
|description_text||TranslatedString||Required||One||Description for the alert. This plain-text string will be formatted as the body of the alert (or shown on an explicit "expand" request by the user). The information in the description should add to the information of the header.|
Cause of this alert.
The effect of this problem on the affected entity.
A time interval. The interval is considered active at time
t is greater than or equal to the start time and less than the end time.
|start||uint64||Conditionally required||One||Start time, in POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). If missing, the interval starts at minus infinity. If a TimeRange is provided, either start or end must be provided - both fields cannot be empty.|
|end||uint64||Conditionally required||One||End time, in POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). If missing, the interval ends at plus infinity. If a TimeRange is provided, either start or end must be provided - both fields cannot be empty.|
A geographic position of a vehicle.
|latitude||float||Required||One||Degrees North, in the WGS-84 coordinate system.|
|longitude||float||Required||One||Degrees East, in the WGS-84 coordinate system.|
|bearing||float||Optional||One||Bearing, in degrees, clockwise from True North, i.e., 0 is North and 90 is East. This can be the compass bearing, or the direction towards the next stop or intermediate location. This should not be deduced from the sequence of previous positions, which clients can compute from previous data.|
|odometer||double||Optional||One||Odometer value, in meters.|
|speed||float||Optional||One||Momentary speed measured by the vehicle, in meters per second.|
A descriptor that identifies a single instance of a GTFS trip.
To specify a single trip instance, a trip_id by itself works fine in many cases. However, the following cases require additional information to resolve to a single trip instance:
- If the trip is defined in frequencies.txt, start_date and start_time are required in addition to trip_id.
- If the trip lasts more than 24 hours, or is delayed such that it would collide with a scheduled trip on the following day, then supply both start_date and trip_id.
- If the trip_id field can't be provided, then you must provide the fields route_id, direction_id, start_date, and start_time.
In all cases, if both route_id and trip_id are provided, then the route_id must match the route_id field assigned to the given trip in the GTFS trips.txt file.
The trip_id field can't, by itself or in combination with other TripDescriptor fields, be used to identify multiple trip instances. If the TripDescriptor resolves to zero or multiple trip instances, rather than a single one, it's considered an error. The entity that contains the erroneous TripDescriptor might be discarded by consumers.
For example, when a trip is defined in GTFS frequencies.txt with exact_times=0, a TripDescriptor must never specify trip_id by itself. That's because when you resolve a single trip instance that starts at a specific time of the day, you must also provide start_time.
Note that if the trip_id isn't known, the station sequence IDs in TripUpdate aren't sufficient, and stop_id fields must be provided as well. In addition, absolute arrival and departure times must be provided.
|trip_id||string||Conditionally required||One||The trip_id from the GTFS feed that this selector refers to. Whether trip_id is required depends on the type of trip:
• Non-frequency-based trips: The trip_id field alone is enough to uniquely identify these trips. Note that non-frequency-based trips aren't defined in GTFS frequencies.txt.
• Frequency-based trips: The trip_id, start_time, and start_date fields are all required. Frequency-based trips are defined in GTFS frequencies.txt.
• Schedule-based trips: The trip_id field can be omitted only if the trip can be uniquely identified by a combination of the provided route_id, direction_id, start_time, and start_date fields. Note that scheduled-based trips aren't defined in GTFS frequencies.txt.
|route_id||string||Conditionally required||One||The route_id from the GTFS feed that this selector refers to. If trip_id is omitted, then route_id, direction_id, start_time, and schedule_relationship=SCHEDULED must all be set to identify a trip instance.|
|direction_id||uint32||Conditionally required||One||The direction_id from the GTFS feed trips.txt file, which indicates the direction of travel. If trip_id is omitted, direction_id must be provided.
Caution: This field is still experimental and subject to change. It might be formally adopted in the future.
|start_time||string||Conditionally required||One||The initially scheduled start time of this trip instance. The field type Time defines the format of this field, for example 11:15:35 or 25:15:35. Whether the start_time field is required depends on the type of trip:
• The trip_id corresponds to a non-frequency-based trip: The start_time field needs to either be omitted or be equal to the value of departure_time in the GTFS feed's stop_times.txt file.
• The trip_id corresponds to a frequency-based trip: start_time is always required and must be specified for trip updates and vehicle positions. Frequency-based trips are defined in GTFS frequencies.txt.
◦ If the frequency-based trip corresponds to an exact_times=1 GTFS record: The start_time field must be some multiple, including zero, of headway_secs later than the frequencies.txt start_time for the corresponding time period.
◦ If the frequency-based trip corresponds to an exact_times=0 GTFS record: The start_time can be arbitrary, and it's initially expected to be the first departure of the trip. After it's established, the start_time of this frequency-based exact_times=0 trip is considered immutable, even if the first departure time changes. Any subsequent time changes can instead be reflected in a StopTimeUpdate message.
• The trip_id is omitted: start_time must be provided.
|start_date||string||Conditionally required||One||The start date of this trip instance in YYYYMMDD format. Whether start_date is required depends on the type of trip:
• Scheduled trips: start_date must be provided. This is to disambiguate trips that are so late that they collide with a scheduled trip on the next day. For example, suppose a train departs at 8:00 and 20:00 every day. If the train is 12 hours late, then there would be two distinct trips scheduled for the same time.
Note: This field is optional for scheduled trips in which such collisions are impossible. For example, this could happen if a service runs on an hourly schedule, and a vehicle that's one hour late isn't considered related to the schedule anymore.
• Frequency-based trips: start_date must be provided. Note that frequency-based trips are defined in the GTFS frequencies.txt file, while scheduled trips aren't.
• trip_id is omitted: start_date must be provided.
|schedule_relationship||ScheduleRelationship||Optional||One||The relation between this trip and the static schedule. If TripDescriptor is provided in an Alert EntitySelector, the schedule_relationship field is ignored by consumers when they identify the matching trip instance.|
The relation between this trip and the static schedule. If a trip is done in accordance with temporary schedule, not reflected in GTFS, then it shouldn't be marked as SCHEDULED, but marked as ADDED.
|SCHEDULED||Trip that is running in accordance with its GTFS schedule, or is close enough to the scheduled trip to be associated with it.|
|ADDED||An extra trip that was added in addition to a running schedule, for example, to replace a broken vehicle or to respond to sudden passenger load.|
|UNSCHEDULED||A trip that is running with no schedule associated to it - this value is used to identify trips defined in GTFS frequencies.txt with exact_times = 0. It should not be used to describe trips not defined in GTFS frequencies.txt, or trips in GTFS frequencies.txt with exact_times = 1.|
|CANCELED||A trip that existed in the schedule but was removed.|
Identification information for the vehicle performing the trip.
|id||string||Optional||One||Internal system identification of the vehicle. Should be unique per vehicle, and is used for tracking the vehicle as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the label field|
|label||string||Optional||One||User visible label, i.e., something that must be shown to the passenger to help identify the correct vehicle.|
|license_plate||string||Optional||One||The license plate of the vehicle.|
A selector for an entity in a GTFS feed. The values of the fields should correspond to the appropriate fields in the GTFS feed. At least one specifier must be given. If several are given, then the matching has to apply to all the given specifiers.
|agency_id||string||Conditionally required||One||At least one specifier must be given - all fields in an EntitySelector cannot be empty.|
|route_id||string||Conditionally required||One||At least one specifier must be given - all fields in an EntitySelector cannot be empty.|
|route_type||int32||Conditionally required||One||At least one specifier must be given - all fields in an EntitySelector cannot be empty.|
|trip||TripDescriptor||Conditionally required||One||At least one specifier must be given - all fields in an EntitySelector cannot be empty.|
|stop_id||string||Conditionally required||One||At least one specifier must be given - all fields in an EntitySelector cannot be empty.|
An internationalized message containing per-language versions of a snippet of text or a URL. One of the strings from a message will be picked up. The resolution proceeds as follows: If the UI language matches the language code of a translation, the first matching translation is picked. If a default UI language (e.g., English) matches the language code of a translation, the first matching translation is picked. If some translation has an unspecified language code, that translation is picked.
|translation||Translation||Required||Many||At least one translation must be provided.|
A localized string mapped to a language.
|text||string||Required||One||A UTF-8 string containing the message.|
|language||string||Conditionally required||One||BCP-47 language code. Can be omitted if the language is unknown or if no internationalization is done at all for the feed. At most one translation is allowed to have an unspecified language tag - if there is more than one translation, the language must be provided.|