GTFS modeling: Use static feeds with realtime feeds

To ensure continued service and accurate data is served to Google Transit users, General Transit Feed Specification (GTFS) modeling is required. GTFS modeling refers to designing static and realtime (RT) feeds to work together to convey the reality on the ground.

GTFS modeling basics

• GTFS Static Feeds: GTFS Static is for premeditated schedule and transit design. You should provide your static feed to Google a minimum of 2 days in advance. However, a week ahead is ideal in case Google detects conflicts or suspicious issues with your feed that require human review.
• GTFS Realtime Feeds: Updates provided to Google are reflected immediately.
  GTFS Realtime is designed to provide realtime status over static data. It communicates delays through vehicle positions and trip updates for trips or stops predefined in static. It also provides service alerts (delays, service interruptions) to users. 
• In your static feed, you can use feed_info.txt to pre-determine (2–7+ days in advance) when static changes should go live, making sure to be consistent with your realtime feeds. Use the feed_start_date and feed_end_date fields to specify the dates that your static feed should be active. If the feed_start_date starts in the future (based on when we process it), we’ll still process that feed, but will keep both the current and “future” version. 
• Static feeds contain core data on routes, stops, and trip scheduling, but as noted above, any changes to static feeds require anywhere from 2–7 days. The following are best practices for how to make scheduling changes.

Best practices to update your static & realtime feeds

Various transit changes occur within ground transportation services, including different durations, levels of urgency, and type of entity. Generally speaking, any changes to core data, including additions, modifications, or deletions of stops, routes, or trips should be performed in the static feed. However, for some changes, particularly temporary changes that need to be made reactively and quickly, there are some methods to achieve this in the realtime feed. Check the following tables for best practices to update the data in your feed.

Overall: 

	Static	Realtime
Add data to the feed	Most changes are possible and straightforward.	In general, this isn't possible unless adding to an existing frequency with schedule_relationship.
Delete data from the feed	Significant deletions get flagged as suspicious, and may undergo longer review.	The realtime feed isn't suited for static deletions. However, alerts are encouraged for temporary deletions.
Modify data in the feed	Most changes are possible and straightforward.	Not supported or encouraged.

Shapes

	Static	Realtime
Add	Add shape_id to existing trip from trips.txt as desired	Not possible. The shape_id must exist
Delete	Remove shape_id from existing trips from trips.txt as desired. There may be unused shapes	N/A
Modify	Modify shape as desired. Changes go live in 2 days	N/A

Stops

	Static	Realtime
Add	Yes. Appropriate stop_times and trip changes might be required Tip: New stop names take some time (2+ days) to resolve on Google Maps, subject to review	N/A
Delete	Possible. Ensure no stop_times continue to refer to undefined stops	NO_SERVICE effect on service alert: Stop will be skipped on every trip it's a part of. Alternatively, the schedule_relationship of a StopTimeUpdate could be SKIPPED
Modify	Stop revisions may take more than 2 days to resolve due to the intensive review process	No, only deletion is possible

Stop times

	Static	Realtime
Add	Adding a stop_time is equivalent to inserting an existing stop along with a defined trip. Allow 2 days for changes to go live.	Not possible.
Delete	Remove desired stop_times from desired trips (to remove respective stops from trips). Allow 2 days for changes to go live.	The schedule_relationship of a StopTimeUpdate could be SKIPPED.
Modify	Modify stop_times file as desired. Changes go live in 2 days.	Fundamentally, vehicle position (VP) and trip update (TU) are modified stop times in realtime. Service alerts with effect SIGNIFICANT_DELAY and  MODIFIED_SERVICE can indicate this too.

Trips

	Static	Realtime
Add	To explicitly activate or disable service by date, use calendar_dates.txt. Use calendar_dates.txt together with calendar.txt to define exceptions to the default service patterns defined in calendar.txt. If service is generally regular, with a few changes on explicit dates (for instance, to accommodate special event services, or a school schedule), this is a good approach. It takes 2 days to go live, but GTFS need not be dramatically modified. A single line edit is required if service already exists in trips. Service and trip at the lowest granularity can be made to have 1:1 mapping.	Use schedule_relationship values to indicate realtime for unplanned trips. The shape and stop_time have to be predefined  against an existing trip. “ADDED” copies planned trips with new start_time so long as the parent trip does not have block transfers. Consistent start_time is crucial to distinguish between trips. ADDITIONAL_SERVICE in service alerts is used to describe additional buses deployed on existing service lines.
Delete	Remove the trip and ensure that all references are removed (frequencies, stop_times, trips). Goes live in 2 days. Another way to accomplish this is to remove corresponding entries from calendar.txt or add exceptions to calendar_dates.txt.	A trip update with schedule relationship SKIPPED achieves this. Alert with effect NO_SERVICE or REDUCED_SERVICE also indicates this to the user. Use descriptive text.
Modify	You can modify trips as needed. Another way to accomplish this is to have corresponding entries in calendar.txt or add exceptions to calendar_dates.txt.	Modification of trip stops isn't permitted. However, delays and early arrivals are indicated through TU or VP. Stops and parts of trips can be blocked in realtime (mentioned above) through service alerts.

Routes

	Static	Realtime
Add	To add a route, add a single line to routes.txt. However, this doesn’t have visibility until trips are created and assigned to the said route, under trips.txt.	Not possible or encouraged.
Delete	Remove the route and ensure that referencing trips are either removed or assigned to another route. Goes live in 2 days.	NO_SERVICE would stop all trips associated with this route. Stops on this route would remain unaffected when they're shared with other routes or trips. Tip: Actual route deletion is still a static concept.
Modify	You can modify trips as needed.  Tip: Users identify routes with color or names. Frequent change is discouraged.	Not possible or encouraged.

More about realtime feeds

Important: Realtime modification of shapes or paths and core elements of static feeds aren't currently supported or encouraged.

Realtime addition and deletion is possible: To allow this, a sketch of the path, stop_sequence, and stop_time (a trip to model after) must exist in the static feed.

Creative use of calendar.txt and calendar_dates.txt is encouraged. For example, to capture snow days, specify trips that may not be “in service” but may be taken in the future in case of contingencies. In other words, define the trips beforehand. This enables a quick “RT-based disabling/enabling (default)” when the moment arrives.

Frequently asked questions

What are the key features of Google Transit?

Google Transit helps transit agencies reach more passengers globally through Google Maps, which supports multiple languages. Public transportation agencies with fixed schedules and routes can partner for free by providing their data. 

How to ensure that my data will be published on Google Maps?

To publish your data on Google Maps, you must:

• Have a fixed schedule
• Provide publicly accessible services
• Have no reservation policy

Where do I upload my data?

Every partner will have a dedicated Transit Partner Dashboard where they can upload their feed in universally-accepted GTFS (General Transit Feed Specification) format using fetch URL or push method.

What if I have to make changes to my data once it is published on Google Maps?

For substantial dataset updates, such as the incorporation of new routes or trips, please contact the Google team. They will produce a TEST FEED and conduct a quality assessment prior to the publication of the data on Google Maps. For regular incremental updates to your data, simply upload the new GTFS data and it will be processed.

Why did my feed show acquisition failed?

Check if your feed has validation errors. These are launch blocking issues that need urgent resolution. Once the validation errors are resolved, your feed will be successfully acquired by the system.

Do I have to resolve all validation warnings for my data to be published?

It is preferable to resolve all validation warnings for better end-user experience, but they are not launch-blocking. It is strongly recommended to resolve even non-blocking validation warnings, in order to provide end users with the best experience.

One user was recently added to the Transit Partner Dashboard account. Why can’t he see the old validation reports?

Old validation reports will not be visible to recently added users. They will have access to the future validation reports only.

Is my data visible to the public after preview creation?

The preview environment offers a confidential glimpse into how data will appear on Google Maps once live, but it is not publicly accessible.

My service has been disrupted on route X due to an accident. How do I relay this information on the feed?

This data can be entered on the Transit Partner Dashboard using Manual Alerts or updated via Realtime feeds, including Service Alerts.

Can I publish data for different agencies serving different routes at the same time?

Yes, you can publish data for multiple agencies with diverse routes in one feed.

I am not happy with how my data looks on Google Maps. Can I change the data?

Yes, you can upload a new feed if you are not satisfied with the preview. Please continue to update your feed whenever you make changes to your website to maintain quality.

Is a contract necessary to publish my data on Google Maps?

Yes, a contract is mandatory to proceed with the onboarding process.

I want to publish my data on Google Maps. However, the data is already available on Google Maps via a 3rd party. What shall I do?

Kindly submit the New Participation Request form to initiate the onboarding process. Upon successful onboarding of your data, Google Maps will feature your information, replacing any existing third-party data.

Can I provide all 3 types of realtime feed at the same time?

Yes, you can publish all the 3 types of realtime simultaneously feed using the same account.

Can I issue a press release to announce that my data is live on Google Maps?

You are welcome to provide an estimated press release date for your feed's launch on Google Maps. Upon completion of the quality review and issue resolution for the feed, we will notify you. We will then request any press release data before the data is launched on Google Maps.

There's a small accident at stop X. I want to route around it through stop Y as soon as possible. Can I do this?

We can suppress stop X via service alerts. Trips will skip this stop. It isn’t possible to add stop Y to the schedule, but it’s possible to use the above alert to indicate that another intermediate stop may be taken. We can use service alerts to suppress stop X, causing trips to skip it. While we cannot add stop Y to the schedule, the same alert mechanism can be used to inform riders that an alternate intermediate stop may be used instead.

It's the Y festival here. We have X new lines running and some major modifications. Help!

What we can do depends on how soon the festival is.

If the festival is more than 2 days from now:

Use calendar_dates.txt to take all existing modified trips out of service for the duration of the festival. You can also add some new trips for this duration. It is difficult to add new stops, so we hope you planned for this (possible within one week+). You can use existing stops. To modify the stops, complete the following steps:

1. Create a new calendar and calendar_date entries (new service_id) for affected existing trips containing the regular calendar and the exclusion calendar_dates
2. Point affected trips to this new calendar (service_id)
3. Create calendar_dates entries with a new service_id for the event dates to be used with new special routes and altered versions of affected trips
4. Create trips (and shapes) for altered versions of affected trips. Also, create routes, trips, and shapes for special service lines. All of these should point to the service_id created in step 3
5. After the event, roll back to the previous feed format

 

If the festival is less than 2 days from now:

We can cancel existing trips, and MODIFIED_SERVICE effect is the right place to communicate this. There isn’t enough time to introduce new stops or stop_times to the routing schedules. However, we can “add vehicles” to existing lines (scheduled or frequency based) to cater to increased service.

The necessary actions depend on the proximity of the event, such as a festival.

 

If the event is more than two days away:

We can implement more comprehensive changes. Utilize calendar_dates.txt to temporarily suspend existing modified trips and introduce new ones for the event's duration. While adding new stops is challenging (ideally planned more than a week in advance), you can use existing stops.

 

To implement stop modifications for existing routes:

1. New Calendar Entries: Create a new service ID by establishing a new calendar and corresponding calendar_date entries for the affected existing trips. This new calendar should include the regular schedule and an exclusion list in calendar_dates for the days of the event
2. Assign New Service ID: Update the affected trips to use this new service ID
3. Event-Specific Service ID: Create calendar_dates entries with a separate, new service ID designated for the event dates. This ID will be used for new special routes and any altered versions of existing affected trips
4. Create Altered/New Trips: Develop the necessary trips (and their corresponding shapes) for both the altered versions of affected existing trips and for any entirely new special service lines. All of these must be linked to the service ID created in step 3
5. Reversion: After the event concludes, revert the feed to its pre-event format

 

If the event is less than two days away:

Due to the limited time, introducing new stops or stop times into the routing schedules is not feasible. However, we can cancel existing trips, which should be communicated using the MODIFIED_SERVICE effect. We can also address increased demand by "adding vehicles" to existing lines, whether they are scheduled or frequency-based.

I want to add a new route now!

We do not have this functionality at this moment.

I want to add a new trip now!

If there is no trip with the same stop_sequences as the new trip, it is not possible to build the new trip into the index in under 2 days.

However, a trip update (TU) or vehicle position (VP) may be set against a trip with different start times as an ADDED Schedule Relationship trip. This added schedule will use the stops of the trip_id provided but will initiate a trip on the new start_time given.

Important: The start_time, direction, start_date and trip_id must remain stable to maintain reference to the trip once added. This isn’t permitted in trips with block transfers. The TU and VP feed may resemble the following:

This isn’t a valid realtime code. It's just a guideline.  

# header information

header {

  # version of speed specification. Currently "2.0"

  gtfs_realtime_version: "2.0"

  # determines whether dataset is incremental or full

  incrementality: FULL_DATASET

  # the moment where this dataset was generated on server

  timestamp: 1284457468

}

# multiple entities can be included in the feed

entity {

  # unique identifier for the entity

  id: "add-a-trip"

  # "type" of the entity

  trip_update {

    trip {

      # selects which GTFS entity (trip) will be affected

      Schedule_relationship: ADDED

      trip_id: "tripid_of_trip_to_copy" #defined in Static

      route_id: “routeid_of_trip_to_copy” # defined in Static. 

                                          # Must NOT contain block transfers.

      start_time: “10:00:00” #the local time when this ad hoc trip starts

      start_date: “20180201” #the local date when this ad hoc trip starts

    }

    ...

  }

}