GTFS Schedule Best Practices
These are recommended practices for describing public transportation services in the General Transit Feed Specification (GTFS). These practices have been synthesized from the experience of the GTFS Best Practices working group members and application-specific GTFS practice recommendations. For further background, see the Frequently Asked Questions.
Practices are organized into four primary sections:
Dataset Publishing & General Practices: These practices relate to the overall structure of the GTFS dataset and to the manner in which GTFS datasets are published.
Practice Recommendations Organized by File: Recommendations are organized by file and field in the GTFS to facilitate mapping practices back to the official GTFS reference.
Practice Recommendations Organized by Case: With particular cases, such as loop routes, practices may need to be applied across several files and fields. Such recommendations are consolidated in this section.
Frequently Asked Questions (FAQ) Why are these GTFS Best Practices important?
The objectives of GTFS Best Practices are:
To improve end-user customer experience in public transportation apps
Support broad data interoperability to make it easier for software developers to deploy and scale applications, products, and services
Facilitate the use of GTFS in various application categories (beyond its original focus on trip planning)
Without coordinated GTFS Best Practices, various GTFS-consuming applications may establish requirements and expectations in an uncoordinated way, which leads to diverging requirements and application-specific datasets and less interoperability. Prior to the release of the Best Practices, there was greater ambiguity and disagreement in what constitutes correctly-formed GTFS data.
How were they developed? Who developed them?
These Best Practices were developed by a working group of 17 organizations involved in GTFS, including app providers & data consumers, transit providers, and consultants with extensive involvement in GTFS. The working group was convened and facilitated by Rocky Mountain Institute.
Working Group members voted on each Best Practice. Most Best Practices were approved by a unanimous vote. In a minority of cases, Best Practices were approved a large majority of organizations.
Why not just change the GTFS reference?
Good question! The process of examining the Specification, data usage and needs did indeed trigger some changes to the Specification (see closed pull requests in GitHub). Specification reference amendments are subject to a higher bar of scrutiny and comment than the Best Practices. However, there was still need to agree on a clear set of Best Practice recommendations.
The working group anticipates that some GTFS Best Practices will eventually become part of the core GTFS reference.
Do GTFS validator tools check for conformance with these Best Practices?
No validator tool currently checks for conformance with all Best Practices. Various validator tools check for conformance with some of these best practices. For a list of GTFS validator tools, see Testing Feeds. If you write a GTFS validator tool that references these Best Practices, please email firstname.lastname@example.org.
I represent a transit agency. What steps can I take so that our software service providers and vendors follow these Best Practices?
Refer your vendor or software service provider to these Best Practices. We recommend referencing the GTFS Best Practices URL, as well as core Spec Reference in procurement for GTFS-producing software.
What should I do if I notice a GTFS data feed does not conform to these Best Practices?
Identify the contact for the feed, using the proposed feed_contact_email or feed_contact_url fields in feed_info.txt if they exist, or looking up contact information on the transit agency or feed producer website. When communicating the issue to the feed producer, link to the specific GTFS Best Practice under discussion. (See "Linking to this Document").
I would like to propose a modification/addition to the Best Practices. How do I do this?
Email email@example.com or open an issue or pull request in the GitHub GTFS Best Practices repo.
Dataset Publishing & General Practices
Datasets should be published at a public, permanent URL, including the zip file name. (e.g., www.agency.org/gtfs/gtfs.zip). Ideally, the URL should be directly downloadable without requiring login to access the file, to facilitate download by consuming software applications. While it is recommended (and the most common practice) to make a GTFS dataset openly downloadable, if a data provider does need to control access to GTFS for licensing or other reasons, it is recommended to control access to the GTFS dataset using API keys, which will facilitate automatic downloads.
GTFS data is published in iterations so that a single file at a stable location always contains the latest official description of service for a transit agency (or agencies).
Maintain persistent identifiers (id fields) for stop_id, route_id, and agency_id across data iterations whenever possible.
One GTFS dataset should contain current and upcoming service (sometimes called a “merged” dataset). Google transitfeed tool's merge function can be used to create a merged dataset from two different GTFS feeds.
At any time, the published GTFS dataset should be valid for at least the next 7 days, and ideally for as long as the operator is confident that the schedule will continue to be operated.
If possible, the GTFS dataset should cover at least the next 30 days of service.
Remove old services (expired calendars) from the feed.
If a service modification will go into effect in 7 days or fewer, express this service change through a GTFS-realtime feed (service advisories or trip updates) rather than static GTFS dataset.
The web-server hosting GTFS data should be configured to correctly report the file modification date (see HTTP/1.1 - Request for Comments 2616, under Section 14.29).