Trip Updates
Trip updates communicate arguably the most important detail to riders: when their vehicle will serve their stop. The GTFS real time format includes a standardized format for trip updates. Using this format allows trip planners, including Transit, to get riders timely information on the status of their trip.
Required Fields
Cancellations
Non-Standard APIs
Prediction Engine
Troubleshooting
Required fields
A trip updates feed includes trip update entities, each with one trip descriptor and at least one stop time update.
Transit uses the trip Descriptor to determine exactly what trip the update refers to. To this end, please include a trip ID that corresponds with a valid trip in the static GTFS data.
At the moment, we are unable to associate real time data to routes with headways defined in frequencies.txt, since there are no trips defined in stop_times.txt.
Trips that weren’t scheduled in the static data may be included in a trip updates field. To do this, include ADDED as the schedule relationship. It should have the same stops, in the same sequence, as a recently active or soon-to-be active trip.
Stop time updates refer to each stop and they must include an arrival and/or departure Stop time event as well as a stop sequence or stop ID. They may additionally include a schedule relationship (see cancellations for skipped stops). Stop time events may include either a delay (compared to schedule), or a time, and an uncertainty value. Stop time events with high uncertainty value will not be represented as real-time data in the app.
Best Practices
- Always include a trip ID that corresponds with an active trip in the static GTFS data.
- Stop sequences and stop IDs must match with the static GTFS data.
- Added or duplicated trips must have the same service pattern as a trip in the static data occurring within 90 minutes before or after the added or duplicated trip.
- Transit will display predictions for up to 90 minutes in the future, which can be seen by tapping on a route from the app’s home screen. Predictions up to 4 ½ hours in the future can be seen in the “More Departures” list. Predictions occurring more than 4 ½ hours in the future are considered low-confidence and thus are not displayed in the app.
Cancellations
Cancelled departures can be a nasty surprise for transit agencies and riders alike. Many moving parts, from driver reassignments to personnel shortages and service changes, can make it difficult to keep trip information up to date.
To make things simpler for everyone, Transit automatically crosses out cancelled departures with an unambiguous strike-through in the list of a line’s upcoming departures shown on the app’s main screen and in the route details. This way, users can know that a vehicle will not be appearing at their stop at the stated time. 
How to display cancellations
Select a trip in your GTFS-rt with the TripDescriptor. After the trip is selected, it can be cancelled with a TripUpdates message or scheduleRelationship enum.
Cancel an entire trip
Provide a trip_update with TripDescriptor that matches the affected trip, and enter the schedule_relationship as CANCELED.
Example code
trip_update {
trip {
trip_id: "trip100"
start_time: 12:34:56
schedule_relationship: CANCELED
}
}
Cancel some stops on a trip
In the case of a detour or a vehicle that does not stop at all stops: specify SKIPPED with stopTime.scheduleRelationship.
Implicit cancellations
For non-standard APIs, note that the app will automatically cancel a departure if a trip is missing real-time information and the agency has provided real-time information for later trips.
For example: there are three departures scheduled in 5, 10, and 18 minutes. The agency has provided real-time information for the trips in 10 and 18 minutes, but not for the trip in 5 minutes. The app will consider the scheduled trip in 5 minutes to be cancelled, and display the strikethrough.
If your agency prefers to display these trips as scheduled and not cancelled, please contact us data@transitapp.com, and we can disable this functionality.
Non-standard APIs
Not all agencies are able to produce GTFS RT feeds for third parties. We do our best to work with feeds in other formats.
At a high level, we need to be able to match two to three identifiers from your real time API with the static data: the stop, and either the trip ID, or the route and headsign.
In either case, we need to know what stop to display the predictions on, so please include either the stop_id or the stop_code from the static data.
- Matching with Trip IDs: The best way to associate real time data with a scheduled item is by using the trip ID.
- Matching with routes and headsigns: If it’s impossible to include a trip ID in your API, we can also use fields to match the route and headsign. The route ID or short name can work, as long as they use the same identifiers as the static GTFS. Similarly, the headsign should also directly match the static data.
We can work with APIs that return this information per stop, route/stop combination, or global requests that provide the complete state of the network.
Best practices
- Always use the same identifiers in the real time feed as the static GTFS feed.
- When possible, use trip IDs instead of headsigns and routes.
- If your endpoint has rate limits, please make sure it allows many requests per second. Alternatively, reach out, and we can provide an IP to be allow-listed.
Prediction Engine
What can you do if your agency doesn’t have a trip updates endpoint, or if your trip updates are otherwise unreliable? Transit has developed a prediction engine that uses machine learning to generate accurate arrival times. Our predictions can be up to 80% more accurate than agency data.
To enable the prediction engine, we need accurate, frequently updated vehicle locations, and two weeks to train a machine learning model for your city. Note that our prediction engine has been extensively tested on bus networks but may not perform as well for other modes.
In some cases, we may need to “switch on” trip updates without a two-week lead time. In these cases, we can enable a less sophisticated prediction engine, which uses vehicle locations to propagate delays down the route.
Troubleshooting
It happens to the best of us: something went wrong, and real time isn’t displaying in the app.
- One of the most common issues that causes downtime is when IDs in the static and real-time data don’t match. This might occur in the period after you publish a schedule update but before it is reflected in your real time data pipeline (Guidelines for Producing GTFS Static Data for Transit). Please ensure to upload new static GTFS a week before any changes are active.
- Another common issue is missing trips. Again, the culprit is often mismatched IDs, possibly from headway adjustments. We recommend designating added trips, but if that’s not possible, consider increasing how frequently you publish static data updates.
- Finally, check the timestamps of your updates. We don’t display real-time updates that are “stale”, or more than a few minutes old.