GTFS Schedule

GTFS Schedule contains the scheduled data, including the description of:

  • the public transit lines (called 'routes');

  • the stops along those lines;

  • the schedules of those lines at their stops.

The GTFS Schedule specification includes both the specification as officially adopted in the google/transit GitHub repository and its Best Practices developed by the experience of the GTFS Best Practices working group and the application-specific GTFS practice recommendations.

Term definitions

This section defines terms that are used throughout this document.

  • Dataset - A complete set of files defined by this specification reference. Altering the dataset creates a new version of the dataset. Datasets should be published at a public, permanent URL, including the zip file name. (e.g., https://www.agency.org/gtfs/gtfs.zip).

  • Record - A basic data structure comprised of a number of different field values describing a single entity (e.g. transit agency, stop, route, etc.). Represented, in a table, as a row.

  • Field - A property of an object or entity. Represented, in a table, as a column.

  • Field value - An individual entry in a field. Represented, in a table, as a single cell.

  • Required - The field must be included in the dataset, and a value must be provided in that field for each record. Some required fields permit an empty string as a value (denoted in this specification as empty). To enter an empty string, just omit any text between the commas for that field.

  • Optional - The field may be omitted from the dataset. If an optional column is included, some of the entries in that field may be empty strings. To enter an empty string, just omit any text between the commas for that field. Note that an omitted field is equivalent to a field that is entirely empty.

  • Conditionally required - The field or file is required under certain conditions, which are outlined in the field or file description. Outside of these conditions, this field or file is optional.

  • Service day - A service day is a time period used to indicate route scheduling. The exact definition of service day varies from agency to agency but service days often do not correspond with calendar days. A service day may exceed 24:00:00 if service begins on one day and ends on a following day. For example, service that runs from 08:00:00 on Friday to 02:00:00 on Saturday, could be denoted as running from 08:00:00 to 26:00:00 on a single service day.

  • Text-to-speech field - The field should contain the same information than its parent field (on which it falls back if it is empty). It is aimed to be read as text-to-speech, therefore, abbreviation should be either removed ("St" should be either read as "Street" or "Saint"; "Elizabeth I" should be "Elizabeth the first") or kept to be read as it ("JFK Airport" is said abbreviated).

Field types

  • Color - A color encoded as a six-digit hexadecimal number. Refer to https://htmlcolorcodes.com to generate a valid value (the leading "#" is not included).
    Example: FFFFFF for white, 000000 for black or 0039A6 for the A,C,E lines in NYMTA.

  • Currency Code - An ISO 4217 alphabetical currency code. For the list of current currency, refer to https://en.wikipedia.org/wiki/ISO_4217#Active_codes .
    Example: CAD for Canadian dollars, EUR for euros or JPY for Japanese yen.

  • Date - Service day in the YYYYMMDD format. Since time within a service day can be above 24:00:00, a service day often contains information for the subsequent day(s).
    Example: 20180913 for September 13th, 2018.

  • Email - An email address.
    Example: example@example.com

  • Enum - An option from a set of predefined constants defined in the "Description" column.
    Example: The route_type field contains a 0 for tram, a 1 for subway...

  • ID - An ID field value is an internal ID, not intended to be shown to riders, and is a sequence of any UTF-8 characters. Using only printable ASCII characters is recommended. IDs defined in one .txt file are often referenced in another .txt file.
    Example: The stop_id field in stops.txt is a ID. The stop_id field in stop_times.txt is an ID referencing stops.stop_id.

  • Language Code - An IETF BCP 47 language code. For an introduction to IETF BCP 47, refer to www.rfc-editor.org/rfc/bcp/bcp47.txt and www.w3.org/International/articles/language-tags/.
    Example: en for English, en-US for American English or de for German.

  • Latitude - WGS84 latitude in decimal degrees. The value must be greater than or equal to -90.0 and less than or equal to 90.0.
    Example: 41.890169 for the Colosseum in Rome.

  • Longitude - WGS84 longitude in decimal degrees. The value must be greater than or equal to -180.0 and less than or equal to 180.0.
    Example: 12.492269 for the Colosseum in Rome.

  • Non-negative Float - A floating point number greater than or equal to 0.

  • Non-negative Integer - A integer greater than or equal to 0.

  • Phone number - A phone number.

  • Time - Time in the HH:MM:SS format (H:MM:SS is also accepted). The time is measured from "noon minus 12h" of the service day (effectively midnight except for days on which daylight savings time changes occur). For times occurring after midnight, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins.
    Example: 14:30:00 for 2:30PM or 25:35:00 for 1:35AM on the next day.

  • Text - A string of UTF-8 characters, which is aimed to be displayed and which must therefore be human readable.

  • Timezone - TZ timezone from the www.iana.org/time-zones. Timezone names never contain the space character but may contain an underscore. Refer to en.wikipedia.org/wiki/List_of_tz_zones for a list of valid values.
    Example: Asia/Tokyo, America/Los_Angeles or Africa/Cairo.

  • URL - A fully qualified URL that includes http:// or https://, and any special characters in the URL must be correctly escaped. See the following www.w3.org/Addressing/URL/4_URI_Recommentations.html for a description of how to create fully qualified URL values.

Best practices (not part of the official specification)

  • 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).

Dataset files

File name

(Requirement) Defines

agency.txt

(Required) Transit agencies with service represented in this dataset.

stops.txt

(Required) Stops where vehicles pick up or drop off riders. Also defines stations and station entrances.

routes.txt

(Required) Transit routes. A route is a group of trips that are displayed to riders as a single service.

trips.txt

(Required) Trips for each route. A trip is a sequence of two or more stops that occur during a specific time period.

stop_times.txt

(Required) Times that a vehicle arrives at and departs from stops for each trip.

calendar.txt

(Conditionally Required) Service dates specified using a weekly schedule with start and end dates. This file is required unless all dates of service are defined in calendar_dates.txt.

calendar_dates.txt

(Conditionally Required) Exceptions for the services defined in the calendar.txt. If calendar.txt is omitted, then calendar_dates.txt is required and must contain all dates of service.

fare_attributes.txt

(Optional) Fare information for a transit agency's routes.

fare_rules.txt

(Optional) Rules to apply fares for itineraries.

shapes.txt

(Optional) Rules for mapping vehicle travel paths, sometimes referred to as route alignments.

frequencies.txt

(Optional) Headway (time between trips) for headway-based service or a compressed representation of fixed-schedule service.

transfers.txt

(Optional) Rules for making connections at transfer points between routes.

pathways.txt

(Optional) Pathways linking together locations within stations.

levels.txt

(Optional) Levels within stations.

translations.txt

(Optional) Translations of customer-facing dataset values.

feed_info.txt

(Optional) Dataset metadata, including publisher, version, and expiration information.

attributions.txt

(Optional) Dataset attributions.

Best practices for all files

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.

Examples:

Brighton Churchill Square

Villiers-sur-Marne

Market Street

Abbreviations

Avoid use of abbreviations throughout the dataset 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.

Field definitions

agency.txt

File: Required

Field name

(Type, Requirement) Description

agency_id

(ID, Conditionally Required) Identifies a transit brand which is often synonymous with a transit agency. Note that in some cases, such as when a single agency operates multiple separate services, agencies and brands are distinct. This document uses the term "agency" in place of "brand". A dataset may contain data from multiple agencies. This field is required when the dataset contains data for multiple transit agencies, otherwise it is optional.


Best practices

Should be included, even if there is only one agency in the feed. (See also recommendation to include agency_id in routes.txt and fare_attributes.txt)

agency_name

(text, Required) Full name of the transit agency.

agency_url

(URL, Required) URL of the transit agency.

agency_timezone

(Timezone, Required) Timezone where the transit agency is located. If multiple agencies are specified in the dataset, each must have the same agency_timezone.

agency_lang

(Language Code, Optional) Primary language used by this transit agency. This field helps GTFS consumers choose capitalization rules and other language-specific settings for the dataset.

Best practices

Should be included.

agency_phone

(Phone number, Optional) A voice telephone number for the specified agency. This field is a string value that presents the telephone number as typical for the agency's service area. It can and should contain punctuation marks to group the digits of the number. Dialable text (for example, TriMet's "503-238-RIDE") is permitted, but the field must not contain any other descriptive text.

Best practices

Should be included unless no such customer service phone exists.

agency_fare_url

(URL, Optional) URL of a web page that allows a rider to purchase tickets or other fare instruments for that agency online.

Best practices

Should be included unless the agency is fully fare-free.

agency_email

(Email, Optional) Email address actively monitored by the agency’s customer service department. This email address should be a direct contact point where transit riders can reach a customer service representative at the agency.

Best practices

Should be included unless no such customer service email exists.

General best practices for agency.txt

  • Bus services are run by several small bus agencies. But there is one big agency that is responsible for scheduling and ticketing and from a user’s perspective responsible for the bus services.The one big agency should be defined as agency within the dataset. Even if the data is split internally by different small bus operators there should only be one agency defined in the feed.

  • The dataset provider runs the ticketing portal, but there are different agencies that actually operate the services and are known by users to be responsible. The agencies actually operating the services should be defined as agencies within the dataset.

stops.txt

File: Required

Field name

(Type, Requirement) Description

stop_id

(ID, Required) Identifies a stop, station, or station entrance.

The term "station entrance" refers to both station entrances and station exits. Stops, stations or station entrances are collectively referred to as locations. Multiple routes may use the same stop.

Best practices (not part of the official specification)

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 stop_id.

stop_id is an internal ID, not intended to be shown to passengers.

Maintain consistent stop_id for the same stops across data iterations (see Dataset Publishing & General Practices).

stop_code

(Text, Optional)

Short text or a number that identifies the location for riders. These codes are often used in phone-based transit information systems or printed on signage to make it easier for riders to get information for a particular location. The stop_code can be the same as stop_id if it is public facing. This field should be left empty for locations without a code presented to riders.

Best practices

stop_code should be included in GTFS if there are passenger-facing stop numbers or short identifiers.

stop_name

(Text, Conditionally Required) Name of the location. Use a name that people will understand in the local and tourist vernacular.

When the location is a boarding area (location_type=4), the stop_name should contains the name of the boarding area as displayed by the agency. It could be just one letter (like on some European intercity railway stations), or text like “Wheelchair boarding area” (NYC’s Subway) or “Head of short trains” (Paris’ RER).

Conditionally Required:

Required for locations which are stops (location_type=0), stations (location_type=1) or entrances/exits (location_type=2).

Optional for locations which are generic nodes (location_type=3) or boarding areas (location_type=4).

Best practices

The stop_name should match the agency's public name for the stop, station, or boarding facility, e.g. what is printed on a timetable, published online, and/or presented at the location. 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 the best practices for Abbreviations under All Files. Provide stop names in mixed case, following local conventions, as per recommendation for all customer-facing text fields. By default, stop_name should not contain generic or redundant words like “Station” or “Stop”, but some edge cases are allowed:

  • When it is actually part of the name (Union Station, Central Station)

  • When the stop_name is too generic (such as if it is the name of the city). “Station”, “Terminal”, or other words make the meaning clear.

tts_stop_name

(Text, Optional) Readable version of the stop_name. See "Text-to-speech field" in the Term Definitions for more.

stop_desc

(Text, Optional)

Description of the location that provides useful, quality information. Do not simply duplicate the name of the location.

stop_lat

(Latitude, Conditionally Required)

Latitude of the location.

For stops/platforms (location_type=0) and boarding area (location_type=4), the coordinates must be the ones of the bus pole — if exists — and otherwise of where the travellers are boarding the vehicle (on the sidewalk or the platform, and not on the roadway or the track where the vehicle stops).

Conditionally Required:

  • Required for locations which are stops (location_type=0), stations (location_type=1) or entrances/exits (location_type=2).

  • Optional for locations which are generic nodes (location_type=3) or boarding areas (location_type=4).

Best practices

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 datasets from different providers (i.e. two agencies use exactly the same stop / boarding facility), indicate the stop is shared by using the exact same stop_lat and stop_lon for both stops.

stop_lon

(Longitude, Conditionally Required)

Longitude of the location.

For stops/platforms (location_type=0) and boarding area (location_type=4), the coordinates must be the ones of the bus pole — if exists — and otherwise of where the travellers are boarding the vehicle (on the sidewalk or the platform, and not on the roadway or the track where the vehicle stops).

Conditionally Required:

  • Required for locations which are stops (location_type=0), stations (location_type=1) or entrances/exits (location_type=2).

  • Optional for locations which are generic nodes (location_type=3) or boarding areas (location_type=4).

Best practices

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 datasets from different providers (i.e. two agencies use exactly the same stop / boarding facility), indicate the stop is shared by using the exact same stop_lat and stop_lon for both stops.

zone_id

(ID, Conditionally Required)

Identifies the fare zone for a stop. This field is required if providing fare information using fare_rules.txt, otherwise it is optional. If this record represents a station or station entrance, the zone_id is ignored.

stop_url

(URL, Optional)

URL of a web page about the location. This should be different from the agency.agency_url and the routes.route_url field values.

location_type

(Enum, Optional)

Type of the location:

0 (or blank): Stop (or Platform). A location where passengers board or disembark from a transit vehicle. Is called a platform when defined within a parent_station.

1: Station. A physical structure or area that contains one or more platform.

2: Entrance/Exit. A location where passengers can enter or exit a station from the street. If an entrance/exit belongs to multiple stations, it can be linked by pathways to both, but the data provider must pick one of them as parent.

3: Generic Node. A location within a station, not matching any other location_type, which can be used to link together pathways defined in pathways.txt.

4: Boarding Area. A specific location on a platform, where passengers can board and/or alight vehicles.


Best practices

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.

  • The station or terminal should be defined as a record in stops.txt with location_type = 1.

  • Each boarding facility should be defined as a stop with location_type = 0. The parent_station field should reference the stop_id of the station the boarding facility is in.

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.)

Parent station name Child stop name

Chicago Union Station Chicago Union Station Platform 19

San Francisco Ferry Building Terminal San Francisco Ferry Building Terminal Gate E

Downtown Transit Center Downtown Transit Center Bay B

parent_station

(ID referencing stops.stop_id, Conditionally Required)

Defines hierarchy between the different locations defined in stops.txt. It contains the ID of the parent location, as followed:

  • Stop/platform (location_type=0): the parent_station field contains the ID of a station.

  • Station (location_type=1): this field must be empty.

  • Entrance/exit (location_type=2) or generic node (location_type=3): the parent_station field contains the ID of a station (location_type=1)

  • Boarding area (location_type=4): the parent_station field contains ID of a platform.

Conditionally Required:

  • Required for locations which are entrances (location_type=2), generic nodes (location_type=3) or boarding areas (location_type=4).

  • Optional for stops/platforms (location_type=0).

  • Forbidden for stations (location_type=1).


Best practices

Please refer to the Best Practices of the field stops.location_type.

stop_timezone

(Timezone, Optional) Timezone of the location. If the location has a parent station, it inherits the parent station’s timezone instead of applying its own. Stations and parentless stops with empty stop_timezone inherit the timezone specified by agency.agency_timezone. If stop_timezone values are provided, the times in stop_times.txt should be entered as the time since midnight in the timezone specified by agency.agency_timezone. This ensures that the time values in a trip always increase over the course of a trip, regardless of which timezones the trip crosses.

wheelchair_boarding

(Enum, Optional) Indicates whether wheelchair boardings are possible from the location. Valid options are:

For parentless stops:

0 or empty - No accessibility information for the stop.

1 - Some vehicles at this stop can be boarded by a rider in a wheelchair.

2 - Wheelchair boarding is not possible at this stop.

For child stops:

0 or empty - Stop will inherit its wheelchair_boarding behavior from the parent station, if specified in the parent.

1 - There exists some accessible path from outside the station to the specific stop/platform.2 - There exists no accessible path from outside the station to the specific stop/platform.

For station entrances/exits:

0 or empty - Station entrance will inherit its wheelchair_boarding behavior from the parent station, if specified for the parent.

1 - Station entrance is wheelchair accessible.

2 - No accessible path from station entrance to stops/platforms.

level_id

(ID referencing levels.level_id, Optional) Level of the location. The same level can be used by multiple unlinked stations.

platform_code

(Text, Optional) Platform identifier for a platform stop (a stop belonging to a station). This should be just the platform identifier (eg. "G" or "3"). Words like “platform” or "track" (or the feed’s language-specific equivalent) should not be included. This allows feed consumers to more easily internationalize and localize the platform identifier into other languages.

routes.txt

File: Required

Field name

(Type, Requirement) Description

route_id

(ID, Required) Identifies a route

Best practices

All trips on a given named route should reference the same route_id.

Different directions of a route should not be separated into different route_id values.

Different spans of operation of a route should not be separated into different route_id values, i.e. do not create different records in routes.txt for “Downtown AM” and “Downtown PM” services).

If a route group includes distinctly named branches (e.g. 1A and 1B), follow recommendations in the route branches case to determine route_short_name and route_long_name.

agency_id

(ID referencing agency.agency_id, Conditionally Required) Agency for the specified route. This field is required when the dataset provides data for routes from more than one agency in agency.txt, otherwise it is optional.

Best practices

Must be included if it is defined in agency.txt.

route_short_name

(Text, Conditionally Required) Short name of a route. This will often be a short, abstract identifier like "32", "100X", or "Green" that riders use to identify a route, but which doesn't give any indication of what places the route serves.

Either route_short_name or route_long_name must be specified, or potentially both if appropriate.

Best practices

Include route_short_name if there is a brief service designation. This should be the commonly-known passenger name of the service, no longer than 12 characters.

route_long_name

(Text, Conditionally Required) Full name of a route. This name is generally more descriptive than the route_short_name and often includes the route's destination or stop.

Either route_short_name or route_long_name must be specified, or potentially both if appropriate.

Best practices

The definition from Specification reference: This name is generally more descriptive than the route_short_name and will often include the route's destination or stop. At least one of route_short_name or route_long_name must be specified, or potentially both if appropriate. If the route does not have a long name, please specify a route_short_name and use an empty string as the value for this field.

Examples of types of long names are below:

Primary travel path or corridor

Route name: “N”/“Judah; Form: route_short_name/ route_long_name; Agency: Muni, in San Francisco.

Route name: “6“/“ML King Jr Blvd; Form: route_short_name/ route_long_name; Agency: TriMet, in Portland, OR.

Route name: “6”/“Nation - Étoile”; Form: route_short_name/ route_long_name; Agency: RATP, in Paris, France.

Route name: “U2”-“Pankow – Ruhleben”; Form: route_short_name/ route_long_name; Agency: BVG, in Berlin, Germany.


Description of the service “Hartwell Area Shuttle“

route_long_name should not contain the route_short_name.

Include the full designation including a service identity when populating route_long_name. Examples:

Service identity "MAX Light Rail" TriMet, in Portland, Oregon; Recommendation: The route_long_name should include the brand (MAX) and the specific route designation; Examples "MAX Red Line" "MAX Blue Line".

Service identity "Rapid Ride" ABQ Ride, in Albuquerque, New Mexico; Recommendation: The route_long_name should include the brand (Rapid Ride) and the specific route designation; Examples "Rapid Ride Red Line" "Rapid Ride Blue Line."

route_desc

(Text, Optional) Description of a route that provides useful, quality information. Do not simply duplicate the name of the route.


Example: "A" trains operate between Inwood-207 St, Manhattan and Far Rockaway-Mott Avenue, Queens at all times. Also from about 6AM until about midnight, additional "A" trains operate between Inwood-207 St and Lefferts Boulevard (trains typically alternate between Lefferts Blvd and Far Rockaway).

route_type

(Enum, Required) Indicates the type of transportation used on a route. Valid options are:

0 - Tram, Streetcar, Light rail. Any light rail or street level system within a metropolitan area.

1 - Subway, Metro. Any underground rail system within a metropolitan area.

2 - Rail. Used for intercity or long-distance travel.

3 - Bus. Used for short- and long-distance bus routes.

4 - Ferry. Used for short- and long-distance boat service.

5 - Cable tram. Used for street-level rail cars where the cable runs beneath the vehicle, e.g., cable car in San Francisco.

6 - Aerial lift, suspended cable car (e.g., gondola lift, aerial tramway). Cable transport where cabins, cars, gondolas or open chairs are suspended by means of one or more cables.

7 - Funicular. Any rail system designed for steep inclines.

11 - Trolleybus. Electric buses that draw power from overhead wires using poles.

12 - Monorail. Railway in which the track consists of a single rail or a beam.

route_url

(URL, Optional) URL of a web page about the particular route. Should be different from the agency.agency_url value.

route_color

(Color, Optional) Route color designation that matches public facing material. Defaults to white (FFFFFF) when omitted or left empty. The color difference between route_color and route_text_color should provide sufficient contrast when viewed on a black and white screen.

Best practices

Should be consistent with signage and printed and online customer information (and thus not included if they do not exist in other places).

route_text_color

(Color, Optional) Legible color to use for text drawn against a background of route_color. Defaults to black (000000) when omitted or left empty. The color difference between route_color and route_text_color should provide sufficient contrast when viewed on a black and white screen.

Best practices

Should be consistent with signage and printed and online customer information (and thus not included if they do not exist in other places).

route_sort_order

(Non-negative integer, Optional) Orders the routes in a way which is ideal for presentation to customers. Routes with smaller route_sort_order values should be displayed first.

continuous_pickup

(Enum, Optional) Indicates that the rider can board the transit vehicle at any point along the vehicle’s travel path as described by shapes.txt, on every trip of the route. Valid options are:

0 - Continuous stopping pickup.

1 or empty - No continuous stopping pickup.

2 - Must phone agency to arrange continuous stopping pickup.

3 - Must coordinate with driver to arrange continuous stopping pickup.

The continuous pickup behavior defined in routes.txt can be overridden in stop_times.txt.

continuous_drop_off

(Enum, Optional) Indicates that the rider can alight from the transit vehicle at any point along the vehicle’s travel path as described by shapes.txt, on every trip of the route. Valid options are:

0 - Continuous stopping drop off.

1 or empty - No continuous stopping drop off.

2 - Must phone agency to arrange continuous stopping drop off.

3 - Must coordinate with driver to arrange continuous stopping drop off.

The continuous drop-off behavior defined in routes.txt can be overridden in stop_times.txt.

trips.txt

File: Required

Best practices

  • See special case for loop routes in the Best Practices: Loop routes are cases where trips start and end at the same stop, as opposed to linear routes, which have two distinct termini. Loop routes must be described following specific practices. See Loop route case.

  • See special case for lasso routes in the Best Practices page: Lasso routes are a hybrid of linear and loop geometries, in which vehicles travel on a loop for only a portion of the route. Lasso routes must be described following specific practices. See Lasso route case.

block_id can be provided for frequency-based trips.

Field name

(Type, Requirement) Description

route_id

(ID referencing routes.route_id, Required) Identifies a route

service_id

(ID referencing calendar.service_id or calendar_dates.service_id, Required) Identifies a set of dates when service is available for one or more routes.

trip_id

(ID, Required) Identifies a trip.

trip_headsign

(Text, Optional) Text that appears on signage identifying the trip's destination to riders. Use this field to distinguish between different patterns of service on the same route. If the headsign changes during a trip, trip_headsign can be overridden by specifying values for the stop_times.stop_headsign.

Best practices

Do not provide route names (matching route_short_name and route_long_name) in the trip_headsign or stop_headsign fields.

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 trip_headsign with stop_times.stop_headsign. Below are recommendations for some possible cases:

2A.

Route Description: Destination-only

Recommendation: Provide the terminus destination. e.g. "Transit Center", “Portland City Center”, or “Jantzen Beach”>

2B.

Route Description: Destinations with waypoints

Recommendation: <destination> via <waypoint> “Highgate via Charing Cross”. If waypoint(s) are removed from the headsign show to passengers after the vehicle passes those waypoints, use stop_times.stop_headsign to set an updated headsign.>

2C.

Route Description: Regional placename with local stops

Recommendation: If there will be multiple stops inside the city or borough of destination, use stop_times.stop_headsign once reaching the destination city.>

2D.

Route Description: Direction-only

Recommendation: Indicate using terms such as “Northbound”, “Inbound”, “Clockwise,” or similar directions.>

2E.

Route Description: Direction with destination

Recommendation: <direction> to <terminus name> e.g. “Southbound to San Jose”>

2F.

Route Description: Direction with destination and waypoints

Recommendation: <direction> via <waypoint> to <destination> (“Northbound via Charing Cross to Highgate”).>

Note: Do not begin a headsign with the words “To” or “Towards”.

trip_short_name

(Text, Optional) Public facing text used to identify the trip to riders, for instance, to identify train numbers for commuter rail trips. If riders do not commonly rely on trip names, leave this field empty. A trip_short_name value, if provided, should uniquely identify a trip within a service day; it should not be used for destination names or limited/express designations.

direction_id

(Enum, Optional) Indicates the direction of travel for a trip. This field is not used in routing; it provides a way to separate trips by direction when publishing time tables. Valid options are:

0 - Travel in one direction (e.g. outbound travel).

1 - Travel in the opposite direction (e.g. inbound travel).

Example: The trip_headsign and direction_id fields could be used together to assign a name to travel in each direction for a set of trips. A trips.txt file could contain these records for use in time tables:

trip_id,...,trip_headsign,direction_id

1234,...,Airport,0

1505,...,Downtown,1

Best practices (not part of the official specification)

If trips on a route service opposite directions, distinguish these groups of trips with the direction_id field, using values 0 and 1.

Use values 0 and 1 consistently throughout the dataset. i.e.

  • If 1 = Outbound on the Red route, then 1 = Outbound on the Green route

  • If 1 = Northbound on Route X, then 1 = Northbound on Route Y

  • If 1 = clockwise on Route X then 1 = clockwise on Route Y

block_id

(ID, Optional) Identifies the block to which the trip belongs. A block consists of a single trip or many sequential trips made using the same vehicle, defined by shared service days and block_id. A block_id can have trips with different service days, making distinct blocks.

shape_id

(ID referencing shapes.shape_id, Conditionally Required) Identifies a geospatial shape describing the vehicle travel path for a trip.

Conditionally Required:

  • Required if the trip has a continuous pickup or drop-off behavior defined either in routes.txt or in stop_times.txt.

  • Optional otherwise.

wheelchair_accessible

(Enum, Optional) Indicates wheelchair accessibility. Valid options are:

0 or empty - No accessibility information for the trip.

1 - Vehicle being used on this particular trip can accommodate at least one rider in a wheelchair.

2 - No riders in wheelchairs can be accommodated on this trip.

bikes_allowed

(Enum, Optional) Indicates whether bikes are allowed. Valid options are:

0 or empty - No bike information for the trip.

1 - Vehicle being used on this particular trip can accommodate at least one bicycle.

2 - No bicycles are allowed on this trip.

stop_times.txt

File: Required

Best practices

  • Loop routes: Loop routes require special stop_times considerations. (See: Loop route case)

Field name

(Type, Requirement) Description

trip_id

(ID referencing trips.trip_id, Required) Identifies a trip

arrival_time

(Time, Conditionally Required) Arrival time at a specific stop for a specific trip on a route. If there are not separate times for arrival and departure at a stop, enter the same value for arrival_time and departure_time. For times occurring after midnight on the service day, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins.

Scheduled stops where the vehicle strictly adheres to the specified arrival and departure times are timepoints. If this stop is not a timepoint, it is recommended to provide an estimated or interpolated time. If this is not available, arrival_time can be left empty. Further, indicate that interpolated times are provided with timepoint=0. If interpolated times are indicated with timepoint=0, then time points must be indicated with timepoint=1. Provide arrival times for all stops that are time points. An arrival time must be specified for the first and the last stop in a trip.

Best practices

arrival_time and departure_time fields should specify time values whenever possible, including non-binding estimated or interpolated times between timepoints.

departure_time

(Time, Conditionally Required) Departure time from a specific stop for a specific trip on a route. For times occurring after midnight on the service day, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins. If there are not separate times for arrival and departure at a stop, enter the same value for arrival_time and departure_time. See the arrival_time description for more details about using timepoints correctly.

The departure_time field should specify time values whenever possible, including non-binding estimated or interpolated times between timepoints.

Best practices

arrival_time and departure_time fields should specify time values whenever possible, including non-binding estimated or interpolated times between timepoints.

stop_id

(ID referencing stops.stop_id, Required) Identifies the serviced stop. All stops serviced during a trip must have a record in stop_times.txt. Referenced locations must be stops, not stations or station entrances. A stop may be serviced multiple times in the same trip, and multiple trips and routes may service the same stop.

stop_sequence

(Non-negative integer, Required) Order of stops for a particular trip. The values must increase along the trip but do not need to be consecutive.

Example: The first location on the trip could have a stop_sequence=1, the second location on the trip could have a stop_sequence=23, the third location could have a stop_sequence=40, and so on.

stop_headsign

(Text, Optional) Text that appears on signage identifying the trip's destination to riders. This field overrides the default trips.trip_headsign when the headsign changes between stops. If the headsign is displayed for an entire trip, use trips.trip_headsign instead.

A stop_headsign value specified for one stop_time does not apply to subsequent stop_times in the same trip. If you want to override the trip_headsign for multiple stop_times in the same trip, the stop_headsign value must be repeated in each stop_time row.

Best practices

stop_headsign values override the trip_headsign (in trips.txt). stop_headsign values should be provided when the text displayed on the headsign changes during a trip. stop_headsign values do not “carry down” to subsequent stops, and therefore values must be repeated if the stop headsign remains the same. In general, headsign values should also correspond to signs in the stations.

In the cases below, “Southbound” would mislead customers because it is not used in the station signs.

In NYC, for the 2 going Southbound:

For stop_times.txt rows: Until Manhattan is Reached Use stop_headsign value: Manhattan & Brooklyn

For stop_times.txt rows: Until Downtown is Reached Use stop_headsign value: Downtown & Brooklyn

For stop_times.txt rows: Until Brooklyn is Reached Use stop_headsign value: Brooklyn

For stop_times.txt rows: Once Brooklyn is Reached Use stop_headsign value: Brooklyn (New Lots Av)


In Boston, for the Red Line going Southbound, for the Braintree branch:

For stop_times.txt rows: Until Downtown is Reached Use stop_headsign value: Inbound to Braintree

For stop_times.txt rows: Once Downtown is Reached Use stop_headsign value: Braintree

For stop_times.txt rows: After Downtown Use stop_headsign value: Outbound to Braintree

pickup_type

(Enum, Optional) Indicates pickup method. Valid options are:

0 or empty - Regularly scheduled pickup.

1 - No pickup available.

2 - Must phone agency to arrange pickup.

3 - Must coordinate with driver to arrange pickup.

Best practices

Non-revenue (deadhead) trips that do not provide passenger service should be marked with pickup_type and drop_off_type value of 1 for all stop_times rows. 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 pickup_type = 1 (no pickup available) and drop_off_type = 1 (no drop off available).

drop_off_type

(Enum, Optional) Indicates drop off method. Valid options are:

0 or empty - Regularly scheduled drop off.

1 - No drop off available.

2 - Must phone agency to arrange drop off.

3 - Must coordinate with driver to arrange drop off.

Best practices

Non-revenue (deadhead) trips that do not provide passenger service should be marked with pickup_type and drop_off_type value of 1 for all stop_times rows. 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 pickup_type = 1 (no pickup available) and drop_off_type = 1 (no drop off available).

continuous_pickup

(Enum, Optional) Indicates that the rider can board the transit vehicle at any point along the vehicle’s travel path as described by shapes.txt, from this stop_time to the next stop_time in the trip’s stop_sequence. Valid options are:

0 - Continuous stopping pickup.

1 or empty - No continuous stopping pickup.

2 - Must phone agency to arrange continuous stopping pickup.

3 - Must coordinate with driver to arrange continuous stopping pickup.

If this field is populated, it overrides any continuous pickup behavior defined in routes.txt. If this field is empty, the stop_time inherits any continuous pickup behavior defined in routes.txt.

continuous_drop_off

(Enum, Optional) Indicates that the rider can alight the transit vehicle at any point along the vehicle’s travel path as described by shapes.txt, from this stop_time to the next stop_time in the trip’s stop_sequence. Valid options are:

0 - Continuous stopping drop off.

1 or empty - No continuous stopping drop off.

2 - Must phone agency to arrange continuous stopping drop off.

3 - Must coordinate with driver to arrange continuous stopping drop off.

If this field is populated, it overrides any continuous drop off behavior defined in routes.txt. If this field is empty, the stop_time inherits any continuous drop off behavior defined in routes.txt.

shape_dist_travelled

(Non-negative float, Optional) Actual distance traveled along the associated shape, from the first stop to the stop specified in this record. This field specifies how much of the shape to draw between any two stops during a trip. Must be in the same units used in shapes.txt. Values used for shape_dist_traveled must increase along with stop_sequence; they cannot be used to show reverse travel along a route.

Example: If a bus travels a distance of 5.25 kilometers from the start of the shape to the stop, shape_dist_traveled=5.25.

Best practices

shape_dist_traveled must be provided for routes that have looping or inlining (the vehicle crosses or travels over the same portion of alignment in one trip). See the shapes.shape_dist_traveled recommendation.

timepoint

(Enum, Optional) Indicates if arrival and departure times for a stop are strictly adhered to by the vehicle or if they are instead approximate and/or interpolated times. This field allows a GTFS producer to provide interpolated stop-times, while indicating that the times are approximate. Valid options are:

0 - Times are considered approximate.

1 or empty - Times are considered exact.

Best practices

The timepoint field should be provided. It specifies which stop_times the operator will attempt to strictly adhere to (timepoint=1), and that other stop times are estimates (timepoint=0).

calendar.txt

File: Conditionally Required

Best Practices

calendar_dates.txt should only contain a limited number of exceptions to the schedule. Regularly-scheduled service should be configured using calendar.txt.

Including a calendar.service_name field can also increase the human readability of GTFS, although this is not adopted in the spec.

Field name

(Type, Requirement) Description

service_id

(ID, Required) Uniquely identifies a set of dates when service is available for one or more routes. Each service_id value can appear at most once in a calendar.txt file.

monday

(Enum, Required) Indicates whether the service operates on all Mondays in the date range specified by the start_date and end_date fields. Note that exceptions for particular dates may be listed in calendar_dates.txt. Valid options are:

1 - Service is available for all Mondays in the date range.

0 - Service is not available for Mondays in the date range.

tuesday

(Enum, Required) Functions in the same way as monday except applies to Tuesday.

wednesday

(Enum, Required) Functions in the same way as monday except applies to Wednesday.

thursday

(Enum, Required) Functions in the same way as monday except applies to Thursday.

friday

(Enum, Required) Functions in the same way as monday except applies to Friday.

saturday

(Enum, Required) Functions in the same way as monday except applies to Saturday.

sunday

(Enum, Required) Functions in the same way as monday except applies to Sunday.

start_date

(Date, Required) Start service day for the service interval.

end_date

(Date, Required) End service day for the service interval. This service day is included in the interval.

calendar_dates.txt

File: Conditionally Required

Best practices

calendar_dates.txt should only contain a limited number of exceptions to the schedule. Regularly-scheduled service should be configured using calendar.txt.

Including a calendar.service_name field can also increase the human readability of GTFS, although this is not adopted in the spec.

Field name

(Type, Requirement) Description

service_id

(ID referencing calendar.service_id, Required) Identifies a set of dates when a service exception occurs for one or more routes. Each (service_id, date) pair can only appear once in calendar_dates.txt if using calendar.txt and calendar_dates.txt in conjunction. If a service_id value appears in both calendar.txt and calendar_dates.txt, the information in calendar_dates.txt modifies the service information specified in calendar.txt.

date

(Date, Required) Date when the service exception occurs

exception_type

(Enum, Required) Indicates whether service is available on the date specified in the date field. Valid options are:

1 - Service has been added for the specified date.

2 - Service has been removed for the specified date.

Example: Suppose a route has one set of trips available on holidays and another set of trips available on all other days. One service_id could correspond to the regular service schedule and another service_id could correspond to the holiday schedule. For a particular holiday, the calendar_dates.txt file could be used to add the holiday to the holiday service_id and to remove the holiday from the regular service_id schedule.

fare_attributes.txt

File: Optional

Best practices

agency_id should be included in fare_attributes.txt if it the field is included in agency.txt.

If a fare system cannot be accurately modeled, avoid further confusion and leave it blank.

Include fares (fare_attributes.txt and fare_rules.txt) and model them as accurately as possible. In edge cases where fares cannot be accurately modeled, the fare should be represented as more expensive rather than less expensive so customers will not attempt to board with insufficient fare. If the vast majority of fares cannot be modeled correctly, do not include fare information in the dataset.

Field name

(Type, Requirement) Description

fare_id

(ID, Required) Identifies a fare class

price

(Non-negative float, Required) Fare price, in the unit specified by currency_type.

currency_type

(Currency Code, Required) Currency used to pay the fare.

payment_method

(Enum, Required) Indicates when the fare must be paid. Valid options are:

0 - Fare is paid on board.

1 - Fare must be paid before boarding.

transfers

(Enum, Required) Indicates the number of transfers permitted on this fare. The fact that this field can be left empty is an exception to the requirement that a Required field must not be empty. Valid options are:

0 - No transfers permitted on this fare.

1 - Riders may transfer once.

2 - Riders may transfer twice.

empty - Unlimited transfers are permitted.

agency_id

(ID referencing agency.agency_id, Conditionally Required) Identifies the relevant agency for a fare. This field is required for datasets with multiple agencies defined in agency.txt, otherwise it is optional.

transfer_duration

(Non-negative integer, Optional) Length of time in seconds before a transfer expires. When transfers=0 this field can be used to indicate how long a ticket is valid for or it can can be left empty.

fare_rules.txt

File: Optional

The fare_rules.txt table specifies how fares in fare_attributes.txt apply to an itinerary. Most fare structures use some combination of the following rules:

  • Fare depends on origin or destination stations.

  • Fare depends on which zones the itinerary passes through.

  • Fare depends on which route the itinerary uses.

Best practices

agency_id should be included in fare_attributes.txt if it the field is included in agency.txt.

If a fare system cannot be accurately modeled, avoid further confusion and leave it blank.

Include fares (fare_attributes.txt and fare_rules.txt) and model them as accurately as possible. In edge cases where fares cannot be accurately modeled, the fare should be represented as more expensive rather than less expensive so customers will not attempt to board with insufficient fare. If the vast majority of fares cannot be modeled correctly, do not include fare information in the feed.

Field name

(Type, Requirement) Description

fare_id

(ID referencing fare_attributes.fare_id, Required) Identifies a fare class

route_id

(ID referencing routes.route_id, Optional) Identifies a route associated with the fare class. If several routes with the same fare attributes exist, create a record in fare_rules.txt for each route.

Example: If fare class "b" is valid on route "TSW" and "TSE", the fare_rules.txt file would contain these records for the fare class:

fare_id,route_id

b,TSW

b,TSE

route_id

(ID referencing routes.route_id, Optional) Identifies a route associated with the fare class. If several routes with the same fare attributes exist, create a record in fare_rules.txt for each route.

Example: If fare class "b" is valid on route "TSW" and "TSE", the fare_rules.txt file would contain these records for the fare class:

fare_id,route_id

b,TSW

b,TSE

origin_id

(ID referencing stops.zone_id, Optional) Identifies an origin zone. If a fare class has multiple origin zones, create a record in fare_rules.txt for each origin_id.

Example: If fare class "b" is valid for all travel originating from either zone "2" or zone "8", the fare_rules.txt file would contain these records for the fare class:

fare_id,...,origin_id

b,...,2

b,...,8

destination_id

(ID referencing stops.zone_id, Optional) Identifies a destination zone. If a fare class has multiple destination zones, create a record in fare_rules.txt for each destination_id.

Example: The origin_id and destination_id fields could be used together to specify that fare class "b" is valid for travel between zones 3 and 4, and for travel between zones 3 and 5, the fare_rules.txt file would contain these records for the fare class:

fare_id,...,origin_id,destination_id

b,...,3,4

b,...,3,5

contains_id

(ID referencing stops.zone_id, Optional) Identifies the zones that a rider will enter while using a given fare class. Used in some systems to calculate correct fare class.

Example: If fare class "c" is associated with all travel on the GRT route that passes through zones 5, 6, and 7 the fare_rules.txt would contain these records:

fare_id,route_id,...,contains_id

c,GRT,...,5

c,GRT,...,6

c,GRT,...,7

Because all contains_id zones must be matched for the fare to apply, an itinerary that passes through zones 5 and 6 but not zone 7 would not have fare class "c". For more detail, see https://code.google.com/p/googletransitdatafeed/wiki/FareExamples in the GoogleTransitDataFeed project wiki.

shapes.txt

File: Optional

Shapes describe the path that a vehicle travels along a route alignment, and are defined in the file shapes.txt. Shapes are associated with Trips, and consist of a sequence of points through which the vehicle passes in order. Shapes do not need to intercept the location of Stops exactly, but all Stops on a trip should lie within a small distance of the shape for that trip, i.e. close to straight line segments connecting the shape points.

Best practices

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.

Field name

(Type, Requirement) Description

shape_id

(ID, Required) Identifies a shape

shape_pt_lat

(Latitude, Required) Latitude of a shape point. Each record in shapes.txt represents a shape point used to define the shape.

shape_pt_lon

(Longitude, Required) Longitude of a shape point.

shape_pt_sequence

(Non-negative integer, Required) Sequence in which the shape points connect to form the shape. Values must increase along the trip but do not need to be consecutive.

Example: If the shape "A_shp" has three points in its definition, the shapes.txt file might contain these records to define the shape:

shape_id,shape_pt_lat,shape_pt_lon,shape_pt_sequence

A_shp,37.61956,-122.48161,0

A_shp,37.64430,-122.41070,6

A_shp,37.65863,-122.30839,11

shape_dist_travelled

(Non-negative float, Optional) Actual distance traveled along the shape from the first shape point to the point specified in this record. Used by trip planners to show the correct portion of the shape on a map. Values must increase along with shape_pt_sequence; they cannot be used to show reverse travel along a route. Distance units must be consistent with those used in stop_times.txt.

Example: If a bus travels along the three points defined above for A_shp, the additional shape_dist_traveled values (shown here in kilometers) would look like this:

shape_id,shape_pt_lat,shape_pt_lon,shape_pt_sequence,shape_dist_traveled

A_shp,37.61956,-122.48161,0,0

A_shp,37.64430,-122.41070,6,6.8310

A_shp,37.65863,-122.30839,11,15.8765

Best practices

Must be provided in both shapes.txt and stop_times.txt if an alignment includes looping or inlining (the vehicle crosses or travels over the same portion of alignment in one trip).

If a vehicle retraces or crosses the route alignment at points in the course of a trip, shape_dist_traveled is important to clarify how portions of the points in shapes.txt line up correspond with records in stop_times.txt.

The shape_dist_traveled field allows the agency to specify exactly how the stops in the stop_times.txt file fit into their respective shape. A common value to use for the shape_dist_traveled field is the distance from the beginning of the shape as traveled by the vehicle (think something like an odometer reading).

Route alignments (in shapes.txt) should be within 100 meters of stop locations which a trip serves.

Simplify alignments so that shapes.txt does not contain extraneous points (i.e. remove extra points on straight-line segments; see discussion of line simplification problem).

frequencies.txt

File: Optional

frequencies.txt represents trips that operate on regular headways (time between trips). This file can be used to represent two different types of service.

  • Frequency-based service (exact_times=0) in which service does not follow a fixed schedule throughout the day. Instead, operators attempt to strictly maintain predetermined headways for trips.

  • A compressed representation of schedule-based service (exact_times=1) that has the exact same headway for trips over specified time period(s). In schedule-based service operators try to strictly adhere to a schedule.

Best practices

Actual stop times are ignored for trips referenced by frequencies.txt; only travel time intervals between stops are significant for frequency-based trips. For clarity/human readability, it is recommended that the first stop time of a trip referenced in frequencies.txt should begin at 00:00:00 (first arrival_time value of 00:00:00).

block_id Can be provided for frequency-based trips.

Field name

(Type, Requirement) Description

trip_id

(ID referencing trips.trip_id, Required) Identifies a trip to which the specified headway of service applies.

start_time

(Time, Required) Time at which the first vehicle departs from the first stop of the trip with the specified headway.

end_time

(Time, Required) Time at which service changes to a different headway (or ceases) at the first stop in the trip.

headway_seconds

(Non-negative integer, Required) Time, in seconds, between departures from the same stop (headway) for the trip, during the time interval specified by start_time and end_time. Multiple headways for the same trip are allowed, but may not overlap. New headways may start at the exact time the previous headway ends.

exact_times

(Enum, Required) Indicates the type of service for a trip. See the file description for more information. Valid options are:

0 or empty - Frequency-based trips.

1 - Schedule-based trips with the exact same headway throughout the day. In this case the end_time value must be greater than the last desired trip start_time but less than the last desired trip start_time + headway_secs.

transfers.txt

File: Optional

When calculating an itinerary, GTFS-consuming applications interpolate transfers based on allowable time and stop proximity. transfers.txt specifies additional rules and overrides for selected transfers.

Best practices

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.

Field name

(Type, Requirement) Description

from_stop_id

(ID referencing stops.stop_id, Required) Identifies a stop or station where a connection between routes begins. If this field refers to a station, the transfer rule applies to all its child stops.

to_stop_id

(ID referencing stops.stop_id, Required) Identifies a stop or station where a connection between routes ends. If this field refers to a station, the transfer rule applies to all child stops.

transfer_type

(Enum, Required) Indicates the type of connection for the specified (from_stop_id, to_stop_id) pair. Valid options are:

0 or empty - Recommended transfer point between routes.

1 - Timed transfer point between two routes. The departing vehicle is expected to wait for the arriving one and leave sufficient time for a rider to transfer between routes.

2 - Transfer requires a minimum amount of time between arrival and departure to ensure a connection. The time required to transfer is specified by min_transfer_time.

3 - Transfers are not possible between routes at the location.

Best practices

"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 min_transfer_time. 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.

min_transfer_time

(Non-negative integer, Optional) Amount of time, in seconds, that must be available to permit a transfer between routes at the specified stops. The min_transfer_time should be sufficient to permit a typical rider to move between the two stops, including buffer time to allow for schedule variance on each route.

pathways.txt

File: Optional

The GTFS-Pathways extension uses a graph representation to describe subway or train, with nodes (the locations) and edges (the pathways).

To go from the entrance (which is a node represented as a location with location_type=2) to a platform (which is a node represented as a location with location_type=0), the rider will go through walkway, fare gates, stairs, etc (which are edges represented as pathways). The proposal also adds another type of location, a generic one called "generic node", to represent for example a walkway crossing from which different walkways can be taken.

Warning: Pathways must be exhaustive in a station.

As consequence, as soon as one platform (as stop), entrance or node belonging to a station has a pathway linked to it, the station is assumed to have exhaustive description of its pathways. Therefore, the following common sense rules apply:

  • No dangling location: If any location within a station has a pathway, then all locations should have pathways (except for those platforms that have boarding areas).

  • No locked platforms: Each platform must be connected to at least one entrance via some chain of pathways. There are very rare stations in the real life where you cannot go outside.

  • No pathways for a platform with boarding areas: A platform that has boarding areas is treated as a parent object, not a point. It may not have pathways assigned. All pathways should be for boarding areas.

Field name

(Type, Requirement) Description

pathway_id

(ID, Required) The pathway_id field contains an ID that uniquely identifies the pathway. The pathway_id is used by systems as an internal identifier of this record (e.g., primary key in database), and therefore the pathway_id must be dataset unique.

Different pathways can go from the same from_stop_id to the same to_stop_id. For example, this happens when two escalators are side by side in opposite direction, or when a stair is nearby and elevator and both go from the same place to the same place.

from_stop_id

(ID referencing stops.stop_id, Required) Location at which the pathway begins. It contains a stop_id that identifies a platform, entrance/exit, generic node or boarding area from the stops.txt file.

to_stop_id

(ID referencing stops.stop_id, Required) Location at which the pathway ends. It contains a stop_id that identifies a platform, entrance/exit, generic node or boarding area from the stops.txt file.

pathway_mode

(Enum, Required) Type of pathway between the specified (from_stop_id, to_stop_id) pair. Valid values for this field are:

1: walkway

2: stairs

3: moving sidewalk/travelator

4: escalator

5: elevator

6: fare gate (or payment gate): A pathway that crosses into an area of the station where a proof of payment is required (usually via a physical payment gate).

Fare gates may either separate paid areas of the station from unpaid ones, or separate different payment areas within the same station from each other. This information can be used to avoid routing passengers through stations using shortcuts that would require passengers to make unnecessary payments, like directing a passenger to walk through a subway platform to reach a busway.

7: exit gate: Indicates a pathway exiting an area where proof-of-payment is required into an area where proof-of-payment is no longer required.

is_bidirectional

(Enum, Required) Indicates in which direction the pathway can be used:

0: Unidirectional pathway, it can only be used from from_stop_id to to_stop_id.

1: Bidirectional pathway, it can be used in the two directions.

Fare gates (pathway_mode=6) and exit gates (pathway_mode=7) cannot be bidirectional.

length

(Non-negative float, Optional) Horizontal length in meters of the pathway from the origin location (defined in from_stop_id) to the destination location (defined in to_stop_id).

This field is recommended for walkways (pathway_mode=1), fare gates (pathway_mode=6) and exit gates (pathway_mode=7).

traversal_time

(Positive integer, Optional) Average time in seconds needed to walk through the pathway from the origin location (defined in from_stop_id) to the destination location (defined in to_stop_id).

This field is recommended for moving sidewalks (pathway_mode=3), escalators (pathway_mode=4) and elevator (pathway_mode=5).

stair_count

(Non-null integer, Optional) Number of stairs of the pathway.

Best Practices: one could use the approximation of 1 floor = 15 stairs to generate approximative values.

A positive stair_count implies that the rider walk up from from_stop_id to to_stop_id. And a negative stair_count implies that the rider walk down from from_stop_id to to_stop_id.


This field is recommended for stairs (pathway_mode=2).

max_slope

(Float, Optional) Maximum slope ratio of the pathway. Valid values for this field are:

0 or (empty): no slope.

• A float: slope ratio of the pathway, positive for upwards, negative for downwards.

This field should be used only with walkways (pathway_mode=1) and moving sidewalks (pathway_mode=3).

Example: In the US, 0.083 (also written 8.3%) is the maximum slope ratio for hand-propelled wheelchair, which mean an increase of 0.083m (so 8.3cm) for each 1m.

min_width

(Positive float, Optional) Minimum width of the pathway in meters.

This field is highly recommended if the minimum width is less than 1 meter.

signposted_as

(Text, Optional) String of text from physical signage visible to transit riders. The string can be used to provide text directions to users, such as 'follow signs to '. The language text should appear in this field exactly how it is printed on the signs.

When the physical signage is multilingual, this field may be populated and translated following the example of stops.stop_name in the field definition of feed_info.feed_lang.

reverse_signposted_as

(Text, Optional) Same than the signposted_as field, but when the pathways is used backward, i.e. from the to_stop_id to the from_stop_id.

levels.txt

File: Optional

Describe the different levels of a station. Is mostly useful when used in conjunction with pathways.txt, and is required for elevator (pathway_mode=5) to ask the user to take the elevator to the “Mezzanine” or the “Platform” level.

Field name

(Type, Requirement) Description

level_id

(ID, Required) Id of the level that can be referenced from stops.txt.

level_index

(Float, Required) Numeric index of the level that indicates relative position of this level in relation to other levels (levels with higher indices are assumed to be located above levels with lower indices).

Ground level should have index 0, with levels above ground indicated by positive indices and levels below ground by negative indices.

level_name

(Text, Optional) Optional name of the level (that matches level lettering/numbering used inside the building or the station). Is useful for elevator routing (e.g. “take the elevator to level “Mezzanine” or “Platforms” or “-1”).

translations.txt

File: Optional

In regions that have multiple official languages, transit agencies/operators typically have language-specific names and web pages. In order to best serve riders in those regions, it is useful for the dataset to include these language-dependent values.

Field name

(Type, Requirement) Description

table_name

(Enum, Required) Defines the table that contains the field to be translated. Allowed values are: agency, stops, routes, trips, stop_times, pathways, levels, feed_info and attributions (do not include the .txt file extension). If a table with a new file name is added by another proposal in the future, the table name is the name of the filename without the .txt file extension.

field_name

(Text, Required) Name of the field to be translated. Fields with type Text can be translated, fields with type URL, Email and Phone number can also be “translated” to provide resources in the correct language. Fields with other types should not be translated.

language

(Language Code, Required) Language of translation.

If the language is the same as in feed_info.feed_lang, the original value of the field will be assumed to be the default value to use in languages without specific translations (if default_lang doesn't specify otherwise).

Example: In Switzerland, a city in an officially bilingual canton is officially called “Biel/Bienne”, but would simply be called “Bienne” in French and “Biel” in German.

translation

(Text or URL or Email or Phone number, Required) Translated value.

record_id

(ID, Conditionally Required) Defines the record that corresponds to the field to be translated. The value in record_id should be a main ID of the table, as defined below:

  • agency_id for agency.txt;

  • stop_id for stops.txt;

  • route_id for routes.txt;

  • trip_id for trips.txt;

  • trip_id for stop_times.txt;

  • pathway_id for pathways.txt;

  • level_id for levels.txt;

  • attribution_id for attribution.txt.

No field should be translated in the other tables. However producers sometimes add extra fields that are outside the official specification and these unofficial fields may need to be translated. Below is the recommended way to use record_id for those tables:

service_id for calendar.txt;

service_id for calendar_dates.txt;

fare_id for fare_attributes.txt;

fare_id for fare_rules.txt;

shape_id for shapes.txt;

trip_id for frequencies.txt;

from_stop_id for transfers.txt.

Conditionally Required:

- forbidden if table_name is feed_info;

- forbidden if field_value is defined;

- required if field_value is empty.

record_sub_id

(ID, Conditionally Required) Helps the record that contains the field to be translated when the table doesn’t have a unique ID. Therefore, the value in record_sub_id is the secondary ID of the table, as defined by the table below:

• None for agency.txt;

• None for stops.txt;

• None for routes.txt;

• None for trips.txt;

stop_sequence for stop_times.txt;

• None for pathways.txt;

• None for levels.txt;

• None for attributions.txt.

No field should be translated in the other tables. However producers sometimes add extra fields that are outside the official specification and these unofficial fields may need to be translated. Below is the recommended way to use record_sub_id for those tables:

• None for calendar.txt;

date for calendar_dates.txt;

• None for fare_attributes.txt;

route_id for fare_rules.txt;

• None for shapes.txt;

start_time for frequencies.txt;

to_stop_id for transfers.txt.

Conditionally Required:

- forbidden if table_name is feed_info;

- forbidden if field_value is defined;

- required if table_name=stop_times and record_id is defined.

field_value

(Text or URL or Email or Phone number, Conditionally Required) Instead of defining which record should be translated by using record_id and record_sub_id, this field can be used to define the value which should be translated. When used, the translation will be applied when the fields identified by table_name and field_name contains the exact same value defined in field_value.

The field must have exactly the value defined in field_value. If only a subset of the value matches field_value, the translation won’t be applied.

If two translation rules match the same record (one with field_value, and the other one with record_id), then the rule with record_id is the one which should be used.

Conditionally Required:

- forbidden if table_name is feed_info;

- forbidden if record_id is defined;

- required if record_id is empty.

feed_info.txt

File: Conditionally Required

  • Required if translations.txt is provided

  • Optional otherwise.

The file contains information about the dataset itself, rather than the services that the dataset describes. Note that, in some cases, the publisher of the dataset is a different entity than any of the agencies.

Best practices

feed_info.txt should be included with all of the following fields: feed_start_date, feed_end_date & feed_version. Provide at least one of feed_contact_email & feed_contact_url.

Field name

(Type, Requirement) Description

feed_publisher_name

(Text, Required) Full name of the organization that publishes the dataset. This may be the same as one of the agency.agency_name values.

feed_publisher_url

(URL, Required) URL of the dataset publishing organization's website. This may be the same as one of the agency.agency_url values.

feed_lang

(Language Code, Required) Default language used for the text in this dataset. This setting helps GTFS consumers choose capitalization rules and other language-specific settings for the dataset. The file translations.txt can be used if the text needs to be translated into languages other than the default one.


The default language may be multilingual for datasets with the original text in multiple languages. In such cases, the feed_lang field should contain the language code mul defined by the norm ISO 639-2. The best practice here would be to provide, in translations.txt, a translation for each language used throughout the dataset. If all the original text in the dataset is in the same language, then mul should not be used.

Example: Consider a dataset from a multilingual country like Switzerland, with the original stops.stop_name field populated with stop names in different languages. Each stop name is written according to the dominant language in that stop’s geographic location, e.g. Genève for the French-speaking city of Geneva, Zürich for the German-speaking city of Zurich, and Biel/Bienne for the bilingual city of Biel/Bienne. The dataset feed_lang should be mul and translations would be provided in translations.txt, in German: Genf, Zürich and Biel; in French: Genève, Zurich and Bienne; in Italian: Ginevra, Zurigo and Bienna; and in English: Geneva, Zurich and Biel/Bienne.

default_lang

(Language Code, Optional) Defines the language that should be used when the data consumer doesn’t know the language of the rider. It will often be en (English).

feed_start_date

(Date, Optional) The dataset provides complete and reliable schedule information for service in the period from the beginning of the feed_start_date day to the end of the feed_end_date day. Both days can be left empty if unavailable. The feed_end_date date must not precede the feed_start_date date if both are given. Dataset providers are encouraged to give schedule data outside this period to advise of likely future service, but dataset consumers should treat it mindful of its non-authoritative status. If feed_start_date or feed_end_date extend beyond the active calendar dates defined in calendar.txt and calendar_dates.txt, the dataset is making an explicit assertion that there is no service for dates within the feed_start_date or feed_end_date range but not included in the active calendar dates.

feed_end_date

(Date, Optional) (See above)

feed_version

(Text, Optional) String that indicates the current version of their GTFS dataset. GTFS-consuming applications can display this value to help dataset publishers determine whether the latest dataset has been incorporated.

feed_contact_email

(Email, Optional) Email address for communication regarding the GTFS dataset and data publishing practices. feed_contact_email is a technical contact for GTFS-consuming applications. Provide customer service contact information through agency.txt.

feed_contact_url

(Email, Optional) URL for contact information, a web-form, support desk, or other tools for communication regarding the GTFS dataset and data publishing practices. feed_contact_url is a technical contact for GTFS-consuming applications. Provide customer service contact information through agency.txt.

attributions.txt

File: Optional

The file defines the attributions applied to the dataset.

Field name

(Type, Requirement) Description

attribution_id

(ID, Optional) Identifies an attribution for the dataset or a subset of it. This is mostly useful for translations.

agency_id

(ID referencing agency.agency_id, Optional) Agency to which the attribution applies.

If one agency_id, route_id, or trip_id attribution is defined, the other ones must be empty. If none of them is specified, the attribution will apply to the whole dataset.

route_id

(ID referencing routes.route_id, Optional) Functions in the same way as agency_id except the attribution applies to a route. Multiple attributions can apply to the same route.

trip_id

(ID referencing trips.trip_id, Optional) Functions in the same way as agency_id except the attribution applies to a trip. Multiple attributions can apply to the same trip.

organization_name

(Text, Required) Name of the organization that the dataset is attributed to.

is_producer

(Enum, Optional) The role of the organization is producer. Valid options are:

0 or empty - Organization doesn’t have this role.

1 - Organization does have this role.

At least one of the fields is_producer, is_operator, or is_authority should be set at 1.

is_operator

(Enum, Optional) Functions in the same way as is_producer except the role of the organization is operator.

is_authority

(Enum, Optional) Functions in the same way as is_producer except the role of the organization is authority.

attribution_url

(URL, Optional) URL of the organization.

attribution_email

(Email, Optional) Email of the organization.

attribution_phone

(Phone number, Optional) Phone number of the organization.