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:
The System Tags menu includes four different tags, each corresponding to a description below. Selecting one of these tags will highlight all applicable recommendations.
These practices improve customer experience in applications like Google Maps that are used for trip planning.
These practices help maintain the ability for a human reader to unzip and examine GTFS files.
These practices support the creation of HTML timetables based on GTFS, such as with the GTFS-to-HTML software.
The objectives of GTFS Best Practices are:
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.
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.
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.
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 [email protected].
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.
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").
Email [email protected].
|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 |
|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. |
|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).|
This section shows practices organized by file and field, aligning with the GTFS reference.
|Mixed Case||All customer-facing text strings (including stop names, route names, and headsigns) should use Mixed Case (not ALL CAPS), following local conventions for capitalization of place names on displays capable of displaying lower case characters.|
|Brighton Churchill Square|
|Abbreviations||Avoid use of abbreviations throughout the feed for names and other text (e.g. St. for Street) unless a location is called by its abbreviated name (e.g. “JFK Airport”). Abbreviations may be problematic for accessibility by screen reader software and voice user interfaces. Consuming software can be engineered to reliably convert full words to abbreviations for display, but converting from abbreviations to full words is prone to more risk of error.|
|agency_id||Should be included, even if there is only one agency in the feed. (See also recommendation to include |
|agency_lang||Should be included.|
|agency_phone||Should be included unless no such customer service phone exists.|
|agency_email||Should be included unless no such customer service email exists.|
|agency_fare_url||Should be included unless the agency is fully fare-free.|
|stop_id||Stops that are in different physical locations (i.e., different designated precise locations for vehicles on designated routes to stop, potentially distinguished by signs, shelters, or other such public information, located on different street corners or representing different boarding facility such as a platform or bus bay, even if nearby each other) should have different |
|Maintain consistent |
|When there is not a published stop name, follow consistent stop naming conventions throughout the feed.|
|Avoid use of abbreviations other than for places that are most commonly called by an abbreviated name. See Abbreviations (#2) under All Files.|
|Provide stop names in mixed case, following local conventions, as per recommendation for all customer-facing text fields.|
|By default, |
|stop_lat & stop_lon||Stop locations should be as accurate possible. Stop locations should have an error of no more than four meters when compared to the actual stop position.|
|Stop locations should be placed very near to the pedestrian right of way where a passenger will board (i.e. correct side of the street).|
|If a stop location is shared across separate data feeds (i.e. two agencies use exactly the same stop / boarding facility), indicate the stop is shared by using the exact same |
|parent_station & location_type||Many stations or terminals have multiple boarding facilities (depending on mode, they might be called a bus bay, platform, wharf, gate, or another term). In such cases, feed producers should describe stations, boarding facilities (also called child stops), and their relation. |
|When naming the station and child stops, set names that are well-recognized by riders, and can help riders to identify the station and boarding facility (bus bay, platform, wharf, gate, etc.).|
|agency_id||Must be included if it is defined in |
|route_long_name||The definition from Specification reference: |
This name is generally more descriptive than the
Examples of types of long names are below:
|Include the full designation including a service identity when populating |
|route_id||All trips on a given named route should reference the same |
|If a route group includes distinctly named branches (e.g. 1A and 1B), follow recommendations in the route branches case to determine |
|route_color & route_text_color||Should be consistent with signage and printed and online customer information (and thus not included if they do not exist in other places).|
|trip_headsign||Do not provide route names (matching |
|Should contain destination, direction, and/or other trip designation text shown on the headsign of the vehicle which may be used to distinguish amongst trips in a route. Consistency with direction information shown on the vehicle is the primary and overriding goal for determining headsigns supplied in GTFS datasets. Other information should be included only if it does not compromise this primary goal. If headsigns change during a trip, override |
|Do not begin a headsign with the words “To” or “Towards”.|
|direction_id||If trips on a route service opposite directions, distinguish these groups of trips with the |
|Use values 0 and 1 consistently throughout the dataset. i.e.|
Loop routes: Loop routes require special
stop_times considerations. (See: Loop route case)
|pickup_type & drop_off_type||Non-revenue (deadhead) trips that do not provide passenger service should be marked with |
|On revenue trips, internal “timing points” for monitoring operational performance and other places such as garages that a passenger cannot board should be marked with |
|arrival_time & departure_time|
In the cases below, “Southbound” would mislead customers because it is not used in the station signs.
|Including a |
|Including a |
|If a fare system cannot be accurately modeled, avoid further confusion and leave it blank.|
|Include fares (|
|If a fare system cannot be accurately modeled, avoid further confusion and leave it blank.|
|Include fares (|
|All Fields||Ideally, for alignments that are shared (i.e. in a case where Routes 1 and 2 operate on the same segment of roadway or track) then the shared portion of alignment should match exactly. This helps to facilitate high-quality transit cartography.|
|Alignments should follow the centerline of the right of way on which the vehicle travels. This could be either the centerline of the street if there are no designated lanes, or the centerline of the side of the roadway that travels in the direction the vehicle moves. |
Alignments should not “jag” to a curb stop, platform, or boarding location.
|shape_dist_traveled||Must be provided in both |
If a vehicle retraces or crosses the route alignment at points in the course of a trip,
feed_info.txt should be included, with all fields below.
|feed_start_date & feed_end_date||Should be included|
|feed_version||Should be included|
|feed_contact_email & feed_contact_url||Provide at least one|
|All Fields||Actual stop times are ignored for trips referenced by |
|block_id||Can be provided for frequency-based trips.|
transfers.transfer_type can be one of four values defined in the GTFS. These
transfer_type definitions are quoted from the GTFS Specification below, in italics, with additional practice recommendations.
0 or (empty): This is a recommended transfer point between routes.
If there are multiple transfer opportunities that include a superior option (i.e. a transit center with additional amenities or a station with adjacent or connected boarding facilities/platforms), specify a recommended transfer point.
1: This is a timed transfer point between two routes. The departing vehicle is expected to wait for the arriving one, with sufficient time for a passenger to transfer between routes.
This transfer type overrides a required interval to reliably make transfers. As an example, Google Maps assumes that passengers need 3 minutes to safely make a transfer. Other applications may assume other defaults.
2: This transfer requires a minimum amount of time between arrival and departure to ensure a connection. The time required to transfer is specified by
Specify minimum transfer time if there are obstructions or other factors which increase the time to travel between stops.
3: Transfers are not possible between routes at this location.
Specify this value if transfers are not possible because of physical barriers, or if they are made unsafe or complicated by difficult road crossings or gaps in the pedestrian network.
|If in-seat (block) transfers are allowed between trips, then the last stop of the arriving trip must be the same as the first stop of the departing trip.|
This section covers particular cases with implications across files and fields.
On loop routes, vehicles’ trips begin and end at the same location (sometimes a transit or transfer center). Vehicles usually operate continuously and allow passengers to stay onboard as the vehicle continues its loop.
Headsigns recommendations should therefore be applied in order to show riders the direction in which the vehicle is going.
To indicate the changing direction of travel, provide
stop_headsigns in the
stop_times.txt file. The
stop_headsign describes the direction for trips departing from the stop for which it's defined. Adding
stop_headsigns to each stop of a trip allows you to change the headsign information along a trip.
Don’t define one single circular trip in the stop_times.txt file for a route that operates between two endpoints (such as when the same bus goes back and forth). Instead, split the trip into two separate trip directions.
Examples of circular trip modeling:
|trips.trip_id||Model the complete round-trip for the loop with a single trip.|
|stop_times.stop_id||Include the first/last stop twice in |
|trips.direction_id||If loop operates in opposite directions (i.e. clockwise and counterclockwise), then designate |
|trips.block_id||Indicate continuous loop trips with the same |
Lasso routes combine aspects of a loop route and directional route.
|Subway Routes (Chicago)|
|Bus Suburb to Downtown Routes (St. Albert or Edmonton)|
|CTA Brown Line (CTA Website and TransitFeeds)|
|trips.trip_id||The full extent of a “vehicle round-trip” (see illustration above) consists of travel from A to B to B and back to A. An entire vehicle round-trip may be expressed by: |
|stop_times.stop_headsign||The stops along the A-B section will be passed through in both directions. |
|trip.trip_headsign||The trip headsign should be a global description of the trip, like displayed in the schedules. Could be “Linden to Linden via Loop” (Chicago example), or “A to A via B” (generic example).|
Some routes may include branches. Alignment and stops are shared amongst these branches, but each also serves distinct stops and alignment sections. The relationship among branches may be indicated by route name(s), headsigns, and trip short name using the further guidelines below.
|All Fields||In naming branch routes, it is recommended to follow other passenger information materials. Below are descriptions and examples of two cases:|
|If timetables and on-street signage represent two distinctly named routes (e.g. 1A and 1B), then present this as such in the GTFS, using the |
|If agency-provided information describes branches as the same named route, then utilize the |
The objectives of maintaining GTFS Best Practices is to:
GTFS applications and practice evolve, and so this document may need to be amended from time to time. To propose an amendment to this document, open a pull request in the GTFS Best Practices GitHub repository and advocate for the change. You can slo email any comments to [email protected].
Please link here in order to provide feed producers with guidance for correct formation of GTFS data. Each individual recommendation has an anchor link. Click the recommendation to get the URL for the in-page anchor link.
If a GTFS-consuming application makes requirements or recommendations for GTFS data practices that are not described here, it is recommended to publish a document with those requirements or recommendations to supplement these common best practices.
The GTFS Best Practices Working Group was convened by Rocky Mountain Institute in 2016-17, consisting of public transportation providers, developers of GTFS-consuming applications, consultants, and academic organizations to define common practices and expectations for GTFS data. Members of this working group included:
Today, this document is maintained by MobilityData International Organization