When providing GTFS-Realtime data, gaps in successive feed updates can have undesirable effects on the end user when viewing affected results in Google Maps.
In general, be careful of the following when providing GTFS-Realtime data.
- Entities (Alert, Trip Update, Vehicle Position) should only be dropped from a GTFS-Realtime feed when they’re no longer relevant to users.
- Feed Timestamps should reflect the last time that the feed was updated.
- Entity timestamps (Trip Update & Vehicle Position) should reflect the last time the data for that entity was updated.
If your feed adheres to the above guidelines, the following shouldn't be a problem. However, be aware of the following behavior in the case that the above guidelines aren't adhered to.
Successive feed update drops message
In this situation, your current feed contains a message describing some alert, trip update, vehicle position for a trip, stop, or route but the next bundle drops that entity. For each of the feed types and situations, be aware of the following behaviors.
Important:
- Google considers each individual update to a GTFS-Realtime feed to be a complete snapshot of all relevant information. Subsequent updates to these feeds will completely overwrite all information from the previous feed. If a message present in a previous feed isn’t present in your latest feed update, then no realtime data is shown for that specific entity, unless that message is restored in a future feed update.
- This behavior is slightly different when using the manual alerts section of the Partner Dashboard, where each update is additive.
Alert
Informational Alert is dropped
Impact: High
An Alert entity being dropped between feed updates will result in the alert that was previously present to no longer appear to users on Google Maps.
Alert with effect value of NO_SERVICE is dropped
Impact: High
Alerts with a NO_SERVICE effect will cause the affected trip to become deprioritized under a separate “disrupted journeys” section to end users in Google Maps.
If such an alert message is dropped between feed updates, beyond the above described behavior, the previously deprioritized trip will appear as a regular result to users with no context of the previous cancellation alert present.
Trip Update
Trip Update with ScheduleRelationship value of CANCELLED is dropped
Impact: High
A cancelled trip is removed from the trip results in Google Maps. However, when a message with ScheduleRelationship of cancelled is dropped between feed updates, the previously cancelled trip will reappear to users without any realtime information as if it wasn't cancelled.
This may result in users waiting for a vehicle that won’t arrive.
Trip Update entity with ScheduleRelationship value of ADDED is dropped
Impact: High
A trip with an ADDED ScheduleRelationship results in an additional service being surfaced to users in trip results in addition to existing static data. If such a trip update is dropped, this trip won’t be surfaced to users.
This will result in users not being aware of this added service.
Trip Update entity with ScheduleRelationship value of SCHEDULED is dropped
Impact: Medium
During previous updates, this trip would use UI elements to indicate to the user that arrival and departure times are being updated in realtime. These UI elements will disappear in this case and the result will appear without any realtime information.
This may result in users arriving at the bus stop either too early or late to board the vehicle.
Trip Update entity with a StopTimeUpdate that skips a stop
Impact: High
If a StopTimeUpdate that previously indicated that a stop would be skipped is dropped, users in the vicinity of this stop may be directed to ride from this stop.
This may result in users waiting for a vehicle that won’t stop for them.
Vehicle Position
Vehicle Position SCHEDULED entity is dropped
Impact: High
During previous bundle updates, UI would reflect the physical position of a bus on the map. Arrival and departure predictions were also visible to the end user.
If a SCHEDULED vehicle position for a specific trip is dropped, both the position of the vehicle and any predictions for arrival or departure time will disappear from Google Maps.
As a result, only arrival times from static data will be shown, which may not reflect real-world conditions.
Vehicle Position ADDED entity is dropped
Impact: High
During previous bundle updates, a new trip would be reflected in trip results that wasn’t present in the base static GTFS feed, along with vehicle positions and predictions of arrival and departure times.
If an ADDED vehicle position for a specific trip is dropped, the trip that’s not present in static GTFS will also disappear from trip results.
This will result in users being unaware of the added services.
Successive bundles repeat stale data
Important:
- If an entire feed isn’t updated within 15 minutes of the present time, we’ll report a TIMESTAMP_PAST warning in the realtime Validation Report. However, we’ll continue to process the feed.
- As a feed continues to go stale, you may encounter some of the behavior listed in this section, depending on feed type.
Alert
The timestamp field in FeedHeader message is stale
Impact: Low
There’s no effect on stale Alert data. We’ll continue to process the stale alert unless we receive an update where it’s not present. Since alerts don’t require frequent updates like Trip Updates or Vehicle Positions, it’s acceptable for an Alerts feed not to be updated for up to a week. However, we recommend that you update an Alert feed at least every 10 minutes to ensure that Google Maps users get the latest alerts.
If an Alerts feed hasn’t been updated for more than a week, the Transit team may ask you to update your feed. If your feed isn’t updated after this, your Alert feed may be disabled.
Trip Update
Timestamp field in FeedHeader message is stale
Impact: High
A feed is considered stale after 1 hour without an updated feed timestamp. The entire feed will be discarded. No realtime data will be reflected to the end user. Learn more about Successive Bundle Drops Update: Trip Update.
Timestamp field for Trip Update is consistently much older than when the feed was acquired
Impact: High
Over multiple feed acquisitions, a specific Trip Update timestamp has a consistently large difference from the time of feed acquisition. This is the time Google retrieves your feed, not the feed timestamp. Trip Updates for this trip will be discarded unless the time difference is improved.
This resulting UI will be as if the trip update didn't exist in the feed at all. Learn more about Successive Bundle Drops Update: Trip Update.
Vehicle Positions
Timestamp field in FeedHeader message is stale
Impact: High
The feed will be discarded. Learn more about Successive Bundle Drops Update: Vehicle Position.
Timestamp field in an individual VehiclePosition message is stale
Impact: High
VehiclePosition messages are considered stale if 15 minutes have passed from the timestamp contained in the timestamp field. This will result in the VehiclePosition information being discarded. Learn more about Successive Bundle Drops Update: Vehicle Position.
If entities for this trip are restored later, positional data from previous entities will still be used for calculating arrival and departure times.
Successive bundles update the timestamp of stale data
In this scenario, a feed repeats stale information, but it updates the timestamp either for the feed itself or for the entities within the feed.
FeedHeader timestamp field is updated but feed contains stale data
Impact: Medium
There’s no immediate effect, if individual entity information hasn’t changed. The feed will be interpreted as usual. However, as time passes the chance of individual entities becoming discarded due to staleness will become greater.
VehiclePosition entity timestamp field is updated but positional data is stale
Impact: High
In this case, the timestamp field for a vehicle position has updated despite the entity containing stale data positional data. As the timestamp is updated, we’ll consider this to be a new update that at the given timestamp has indicated that the vehicle has not moved.
In most situations, this will have a negative effect on immediate arrival and departure predictions that are calculated based on vehicle position, as it appears the vehicle hasn’t moved and may be running late. This will also have a negative impact on future predictions for this trip and potentially future trips.
If the vehicle hasn’t actually moved, this is fine. if it has actually moved, the end user will see inaccurate data and the accuracy of arrival time predictions will be negatively impacted.
New bundle isn’t uploaded
Impact: Medium
In this situation, a bundle is uploaded (pushed as opposed to fetched) but another isn't uploaded for an extended period of time.
Depending on the feed, Google will continue to process the same last uploaded feed message until each relevant entity is considered stale.
- Alerts are never considered stale and will continue to be shown until a new feed without the relevant feed entity present is uploaded or the feed itself is disabled.
- Trip Updates are considered stale after 1 hour, and in that timeframe will likely result in stale information being displayed to users.
- Vehicle Positions are considered stale after 15 minutes.