Reference

This document explains the types of files within a General Transit Feed Specification (GTFS) transit feed, and it defines the fields used in all of those files.

The following topics are covered in this document:

  1. Term definitions
  2. Field types
  3. Dataset files
  4. File requirements
  5. Field definitions

Term definitions

The following terms are used throughout this document:

  • Dataset: A complete set of files defined by this specification reference. Any alteration to the dataset creates a new version of the dataset. Publish datasets at a public, permanent URL, which includes the zip file name. For example, https://www.agency.org/gtfs/gtfs.zip.

  • Record: A basic data structure comprised of a number of different field values that describe a single entity, such as a transit agency, stop, or route. Records are 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. To enter an empty string, just omit any text between the commas for that field. Note that 0 is interpreted as "a string of value 0," which is different from an empty string.
  • Optional: The field can be omitted from the dataset. If you choose to include an optional column, some of the entries in that field can be empty strings.

    • To enter an empty string, just omit any text between the commas for that field. Note that 0 is interpreted as "a string of value 0," which is different from an empty string. 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 time period used to indicate route scheduling. The exact definition of service day varies from agency to agency, but service days often don't correspond to 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.

Field types

The following types of fields are used throughout the General Transit Feed Specification (GTFS) transit feed:

  • Color: A color that's encoded as a six-digit hexadecimal number. Refer to HTML color codes to generate valid values. Note that the leading "#" is not included.

    • Example, FFFFFF for white, 000000 for black, or 0039A6 for the A,C,E lines of a service.
  • Currency code: An ISO 4217 alphabetical currency code. For the list of current currency, see Active codes.

    • Example, CAD for Canadian dollars, EUR for euros, or JPY for Japanese yen.
  • Date: A service day that's given in the YYYYMMDD format. Because the time within a service day can be above 24:00:00, a service day often contains information for the subsequent days.

    • Example, 20180913 for September 13th, 2018.
  • Email: An email address.

    • Example, ex@gmail.com.
  • Enum: An option that comes from a set of predefined constants defined in the "Description" column.

    • Example, The route_type field of routes.txt contains a 0 for trams or a 1 for subways.
  • ID: A sequence of any UTF-8 characters that uniquely identifies an entity but doesn't necessarily identify a specific record in a table. IDs defined in one TXT file are often referenced in another TXT file. An ID field value isn't meant to be displayed to the user. Any UTF-8 characters can be used, but we recommend the use of only printable ASCII characters.

    • Example: The stop_id field in stops.txt is an ID. The stop_id field in stop_times.txt is an ID that references stops.stop_id.
  • Language code: An IETF BCP 47 language code. For an introduction to IETF BCP 47, refer to Tags for identifying languages and Language tags in HTML and XML.

    • Example: en for English, en-US for American English, or de for German.
  • Latitude: A 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: A 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: An integer greater than or equal to 0.

  • Phone number: A phone number.

  • Time: A time given in the HH:MM:SS format. H:MM:SS is also accepted. The time is measured from "noon minus 12 hours" at the beginning of the service day. This is effectively midnight, except for days on which daylight savings time changes occur. For times 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:30 PM or 25:35:00 for 1:35 AM on the next day.
  • Text: A string of UTF-8 characters that is meant to be displayed, and so must be human readable.

  • Timezone: A timezone from the Time Zone Database. Timezone names never contain the space character but can contain an underscore. For a list of valid values, refer to List of tz database time zones.

    • 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. For a description of how to create fully qualified URL values, see W3C URI recommendations.

Dataset files

This specification defines the following files and their associated content:

Filename Required Definition
agency.txt Required Defines one or more transit agencies that have services represented in the dataset.
stops.txt Required Defines stops where vehicles pick up or drop off riders. Also defines stations and station entrances.
routes.txt Required Defines transit routes. A route is a group of trips that are displayed to riders as a single service.
trips.txt Required Defines 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 Provides the times when a vehicle arrives at and departs from individual stops for each trip.
calendar.txt Conditionally required Defines service dates when service is available for particular routes. Uses a weekly schedule. This file specifies start and end dates of service, as well as the days of the week when service is available. This file is required unless all of the dates of service are defined in calendar_dates.txt.
calendar_dates.txt Conditionally required Defines exceptions for the services defined in the calendar.txt file. If calendar.txt is omitted, then calendar_dates.txt is required and must contain all dates of service.
fare_attributes.txt Optional Defines fare information for a transit agency's routes.
fare_rules.txt Optional Defines rules to apply fare information for itineraries.
shapes.txt Optional Defines rules to map vehicle travel paths, sometimes referred to as route alignments.
frequencies.txt Optional Describes the headway, which is the time between trips, for routes that have a variable frequency of service. Can also provide a compressed representation of fixed-schedule services.
transfers.txt Optional Defines rules for how connections are made at transfer points between routes.
pathways.txt Optional Defines rules to describe the walking connections between two stops within a station, such as between an entrance and a platform. These pathways are represented as the edges of a walking graph.
levels.txt Optional Defines levels within stations.
feed_info.txt Optional Provides additional information about the feed itself, such as publisher, version, and expiration information.

File requirements

The following requirements apply to the format and contents of your files:

  • All files in a General Transit Feed Spec (GTFS) feed must be saved as comma-delimited text.

  • The first line of each file must contain field names. Each subsection of the Field definitions section corresponds to one of the files in a GTFS dataset. They list the field names you can use in that file.

  • All field names are case sensitive.

  • Field values can't contain tabs, carriage returns, or new lines.

  • Field values that contain quotation marks or commas must be enclosed within quotation marks. In addition, each quotation mark in the field value must be preceded with a quotation mark. This is consistent with how Microsoft Excel outputs comma-delimited (CSV) files. For more information on the CSV file format, see Common format and MIME type for comma-separated values (CSV) files. The following example demonstrates how field values appear in a comma-delimited file:

    • Original field value: Contains "quotes", commas, and text
    • Field value in CSV file: "Contains ""quotes"", commas, and text"
  • Field values must not contain HTML tags, comments, or escape sequences.

  • Remove any extra spaces between fields or field names. Many parsers consider the spaces to be part of the value, which may cause errors.

  • Each line must end with a CRLF or LF linebreak character.

  • Encode files in UTF-8 to support all Unicode characters. Files that include the Unicode byte-order mark (BOM) character are acceptable. For more information on the BOM character and UTF-8, see the Unicode FAQ.

  • All dataset files must be zipped together.

Field definitions

agency.txt

File: Required

Defines one or more transit agencies that have services represented in the dataset.

Field name Type Required Description
agency_id ID Conditionally required

Identifies a transit brand, which is often the same as 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 transit feed can represent data from more than one agency. This field is required for transit feeds that contain data for multiple agencies. Otherwise, it's optional.

agency_name Text Required Contains the full name of the transit agency.
agency_url URL Required Contains the URL of the transit agency.
agency_timezone Timezone Required Contains the timezone where the transit agency is located. If multiple agencies are specified in the feed, each must have the same agency_timezone.
agency_lang Language code Optional Specifies the primary language used by this transit agency. This setting helps GTFS consumers choose capitalization rules and other language-specific settings for the dataset.
agency_phone Phone number Optional Provides a voice telephone number for the specified agency. This field is a string value that presents the telephone number in a format typical for the agency's service area. It can and should contain punctuation marks to group the digits of the number. Dialable text, such as TriMet's 503-238-RIDE, is permitted, but the field must not contain any other descriptive text.
agency_fare_url URL Optional Specifies the URL of a web page where a rider can purchase tickets or other fare instruments for the agency online.
agency_email Email Optional Contains a valid email address that's actively monitored by the agency's customer service department. This email address needs to be a direct contact point where transit riders can reach a customer service representative at the agency.

stops.txt

File: Required

Defines stops where vehicles pick up or drop off riders. Also defines stations and station entrances.

Field name Type Required 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, and station entrances are collectively referred to as locations. Multiple routes can use the same stop.
stop_code Text Optional

Contains some short text or a number that uniquely identifies the stop for riders. Stop codes are often used in phone-based transit information systems or printed on stop signage to make it easier for riders to get information for a particular stop.

The stop_code can be the same as stop_id if the ID is public facing. Leave this field blank for stops without a code presented to riders.

stop_name Text Conditionally required

Contains the name of a location. Use a name that people understand in the local and tourist vernacular.

When the location is a boarding area, with location_type=4, include the name of the boarding area as displayed by the agency in the stop_name. It can be just one letter or text like "Wheelchair boarding area" or "Head of short trains."

This field is required for locations that are stops, stations, or entrances/exits, which have location_type fields of 0, 1, and 2 respectively.

This field is optional for locations that are generic nodes or boarding areas, which have location_type fields of 3 and 4 respectively.

stop_desc Text Optional Describes a location. Provide useful, quality information. Don't simply duplicate the name of the location.
stop_lat Latitude Conditionally required

Contains the latitude of a stop, station, or station entrance.

This field is required for locations that are stops, stations, or entrances/exits, which have location_type fields of 0, 1, and 2 respectively.

This field is optional for locations that are generic nodes or boarding areas, which have location_type fields of 3 and 4 respectively.

stop_lon Longitude Conditionally required

Contains the longitude of a stop, station, or station entrance.

This field is required for locations that are stops, stations, or entrances/exits, which have location_type fields of 0, 1, and 2 respectively.

This field is optional for locations that are generic nodes or boarding areas, which have location_type fields of 3 and 4 respectively.

zone_id ID Conditionally required Defines the fare zone for a stop. This field is required if you want to provide fare information with fare_rules.txt. If this record represents a station or station entrance, the zone_id is ignored.
stop_url URL Optional Contains the URL of a web page about a particular stop. Make this different from the agency_url and route_url fields.
location_type Enum Optional

Defines the type of the location. The location_type field can have the following values:

  • 0 or (empty): Stop (or "Platform"). A location where passengers board or disembark from a transit vehicle. Stops are called a "platform" when they're defined within a parent_station.
  • 1: Station. A physical structure or area that contains one or more platforms.
  • 2: Station entrance or exit. A location where passengers can enter or exit a station from the street. The stop entry must also specify a parent_station value that references the stop_id of the parent station for the entrance. If an entrance/exit belongs to multiple stations, it's linked by pathways to both, and the data provider can either pick one station as parent, or put no parent station at all.
  • 3: Generic node. A location within a station that doesn't match any other location_type. Generic nodes are used to link together the pathways defined in pathways.txt.
  • 4: Boarding area. A specific location on a platform where passengers can board or exit vehicles.
parent_station ID that references stops.stop_id Conditionally required

For stops that are physically located inside stations, the parent_station field identifies the station associated with the stop. Based on a combination of values for the parent_station and location_type fields, we define three types of stops:

  • A parent stop is an (often large) station or terminal building that can contain child stops.
    • This entry's location type is 1.
    • The parent_station field contains a blank value, because parent stops can't contain other parent stops.
  • A child stop is located inside of a parent stop. It can be an entrance, platform, node, or other pathway, as defined in pathways.txt.
    • This entry's location_type is 0 or (empty).
    • The parent_station field contains the stop ID of the station where this stop is located.
    • The stop referenced in parent_station must have location_type=1.
  • A standalone stop is located outside of a parent stop.
    • This entry's location type is 0 or (empty).
    • The parent_station field contains a blank value, because the parent_station field doesn't apply to this stop.
stop_timezone Timezone Optional

Contains the timezone of this location. If omitted, it's assumed that the stop is located in the timezone specified by the agency_timezone in agency.txt.

When a stop has a parent station, the stop has the timezone specified by the parent station's stop_timezone value. If the parent has no stop_timezone value, the stops that belong to that station are assumed to be in the timezone specified by agency_timezone, even if the stops have their own stop_timezone values.

In other words, if a given stop has a parent_station value, any stop_timezone value specified for that stop must be ignored. Even if stop_timezone values are provided in stops.txt, continue to specify the times in stop_times.txt relative to the timezone specified by the agency_timezone field in agency.txt. 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

Identifies whether wheelchair boardings are possible from the specified stop, station, or station entrance. This field can have the following values:

  • 0 or (empty): Indicates that there's no accessibility information available for this stop.
  • 1: Indicates that at least some vehicles at this stop can be boarded by a rider in a wheelchair.
  • 2: Indicates that wheelchair boarding isn't possible at this stop.

When a stop is part of a larger station complex, as indicated by the presence of a parent_station value, the stop's wheelchair_boarding field has the following additional semantics:

  • 0 or (empty): The stop inherits its wheelchair_boarding value from the parent station if it exists.
  • 1: Some accessible path exists from outside the station to the specific stop or platform.
  • 2: There are no accessible paths from outside the station to the specific stop or platform.

For station entrances/exits, the wheelchair_boarding field has the following additional semantics:

  • 0 or (empty): The station entrance inherits its wheelchair_boarding value from the parent station if it exists.
  • 1: The station entrance is wheelchair accessible, such as when an elevator is available to reach platforms that aren't at-grade.
  • 2: There are no accessible paths from the entrance to the station platforms.
level_id ID that references levels.level_id Optional Provides the level of the location. The same level can be used by multiple unlinked stations.
platform_code Text Optional Provides the platform identifier for a platform stop, which is a stop that belongs to a station. Just include the platform identifier, such as G or 3. Don't include words like "platform" or "track" or the feed's language-specific equivalent. This allows feed consumers to more easily internationalize and localize the platform identifier into other languages.

routes.txt

File: Required

Defines transit routes. A route is a group of trips that are displayed to riders as a single service.

Field name Type Required Description
route_id ID Required Identifies a route.
agency_id ID that references agency.agency_id Conditionally required Defines an 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's optional.
route_short_name Text Conditionally required

Contains the short name of a route. This is 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.

At least one of route_short_name or route_long_name must be specified, or both if appropriate. If the route has no short name, specify a route_long_name and use an empty string as the value for this field.

route_long_name Text Conditionally required

Contains the full name of a route. This name is generally more descriptive than the name from route_short_name and often includes the route's destination or stop.

At least one of route_short_name or route_long_name must be specified, or both if appropriate. If the route has no long name, specify a route_short_name and use an empty string as the value for this field.

route_desc Text Optional

Describes a route. Be sure to provide useful, quality information for this field. Don't simply duplicate the name of the route.

For example: "A" trains operate between Inwood-207 St, Manhattan and Far Rockaway-Mott Ave, Queens at all times. From about 6 AM until about midnight, additional "A" trains operate between Inwood-207 St and Lefferts Blvd (trains typically alternate between Lefferts Blvd and Far Rockaway).

route_type Enum Required

Describes the type of transportation used on a route. The following are valid values for this field:

  • 0: Tram, streetcar, or light rail. Used for any light rail or street-level system within a metropolitan area.
  • 1: Subway or metro. Used for 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 car. Used for street-level cable cars where the cable runs beneath the car.
  • 6: Gondola or suspended cable car. Typically used for aerial cable cars where the car is suspended from the cable.
  • 7: Funicular. Used for any rail system that moves on steep inclines with a cable traction system.
route_url URL Optional Contains the URL of a web page for a particular route. This URL needs to be different from the agency_url value.
route_color Color Optional

In systems that assigns colors to routes, the route_color field defines a color that corresponds to a route. If no color is specified, the default route color is white, FFFFFF.

The color difference between route_color and route_text_color needs to provide sufficient contrast when viewed on a black and white screen. The W3C techniques for accessibility evaluation and repair tools document offers a useful algorithm to evaluate color contrast. There are also helpful online tools to help you choose contrasting colors, such as the snook.ca Color Contrast Check application.

route_text_color Color Optional

Specifies a legible color for text that's drawn against the background color of route_color. If no color is specified, the default text color is black, 000000.

The color difference between route_color and route_text_color needs to provide sufficient contrast when viewed on a black and white screen. The W3C techniques for accessibility evaluation and repair tools document offers a useful algorithm to evaluate color contrast. There are also helpful online tools to help you choose contrasting colors, such as the snook.ca Color Contrast Check application.

route_sort_order Non-negative integer Optional Specifies the order in which to present the routes to customers. Routes with smaller route_sort_order values need to be displayed before routes with larger route_sort_order values.

trips.txt

File: Required

Defines trips for each route. A trip is a sequence of two or more stops that occur during a specific time period.

Field name Type Required Description
route_id ID that references routes.route_id Required Identifies a route.
service_id ID that references 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

Contains the text that appears on signage that identifies 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, you can override the trip_headsign with values from the stop_headsign field in stop_times.txt.

trip_short_name Text Optional

Contains the public-facing text that's shown to riders to identify the trip, such as the train numbers for commuter rail trips. If riders don't commonly rely on trip names, leave this field blank.

If a trip_short_name is provided, it needs to uniquely identify a trip within a service day. Don't use it for destination names or limited/express designations.

direction_id Enum Optional

Indicates the direction of travel for a trip. Use this field to distinguish between bi-directional trips with the same route_id. The following are valid values for this field:

  • 0: Travel in one direction of your choice, such as outbound travel.
  • 1: Travel in the opposite direction, such as inbound travel.

This field isn't used in routing, but instead provides a way to separate trips by direction when you publish time tables. You can specify names for each direction with the trip_headsign field.

For example, for a set of trips you could use the trip_headsign and direction_id fields together to assign names for travel in each direction. A trips.txt file could contain the following rows for use in its time tables:

trip_id,...,trip_headsign,direction_id
1234,...,Airport,0
1505,...,Downtown,1
block_id ID Optional Identifies the block to which the trip belongs. A block consists of a single trip or many sequential trips made with the same vehicle. The trips are grouped into a block by the use of a shared service day and block_id. A block_id can include trips with different service days, which then makes distinct blocks. For more details, see Blocks and service days example.
shape_id ID that references shapes.shape_id Optional Defines a geospatial shape that describes the vehicle travel for a trip.
wheelchair_accessible Enum Optional

Identifies whether wheelchair boardings are possible for the specified trip. This field can have the following values:

  • 0 or (empty): There's no accessibility information available for this trip.
  • 1: The vehicle 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

Identifies whether bicycles are allowed on the specified trip. This field can have the following values:

  • 0 or (empty): There's no bike information available for the trip.
  • 1: The vehicle used on this particular trip can accommodate at least one bicycle.
  • 2: No bicycles are allowed on this trip.

Blocks and service day example

The following table shows how to create trips for a single vehicle, where those trips fall into distinct blocks for every day of the week. The stop times correspond to the earliest arrival_time and the latest departure_time for the block, as given in stop_times.txt.

route_id trip_id service_id block_id First stop time Last stop time
red trip_1 mon-tues-wed-thurs-fri-sat-sun red_loop 22:00:00 22:55:00
red trip_2 fri-sat-sun red_loop 23:00:00 23:55:00
red trip_3 fri-sat red_loop 24:00:00 24:55:00
red trip_4 mon-tues-wed-thurs red_loop 20:00:00 20:50:00
red trip_5 mon-tues-wed-thurs red_loop 21:00:00 21:50:00

The following notes describe two of the blocks defined by the table above:

  • On Friday evening into Saturday morning, a single vehicle operates trip_1, trip_2, and trip_3, from 10:00 PM through 12:55 AM. The last trip occurs on Saturday, from 12:00 AM to 12:55 AM, but it's defined as part of the Friday "service day" because the times are 24:00:00 to 24:55:00.

  • On Monday, Tuesday, Wednesday, and Thursday, a single vehicle operates trip_1, trip_4, and trip_5 in a block from 8:00 PM to 10:55 PM.

stop_times.txt

File: Required

Provides the times when a vehicle arrives at and departs from individual stops for each trip.

Field name Type Required Description
trip_id ID that references trips.trip_id Required Identifies a trip.
arrival_time Time Conditionally required

Specifies the arrival time at a specific stop for a specific trip on a route. An arrival time must be specified for the first and the last stop in a trip.

If you don't have separate times for arrival and departure at a stop, enter the same value for arrival_time and departure_time.

For information on how to enter arrival times for stops where the vehicle strictly adheres to a schedule, see Timepoints.

departure_time Time Conditionally required

Specifies the departure time from a specific stop for a specific trip on a route. A departure time must be specified for the first and the last stop in a trip, even if the vehicle does not allow boarding at the last stop.

If you don't have separate times for arrival and departure at a stop, enter the same value for arrival_time and departure_time.

For information on how to enter departure times for stops where the vehicle strictly adheres to a schedule, see Timepoints.

stop_id ID that references stops.stop_id Required

Identifies the serviced stop. Multiple routes can use the same stop.

If location_type is used in stops.txt, all stops referenced in stop_times.txt must have location_type=0. Where possible, stop_id values should remain consistent between feed updates. In other words, stop A with stop_id=1 should have stop_id=1 in all subsequent data updates. If a stop isn't a timepoint, enter blank values for arrival_time and departure_time. For more details, see Timepoints.

stop_sequence Non-negative integer Required

Identifies the order of the stops for a particular trip. The values for stop_sequence must increase throughout the trip but do not need to be consecutive.

For example, the first stop on the trip could have a stop_sequence of 1, the second stop on the trip could have a stop_sequence of 23, the third stop could have a stop_sequence of 40, and so on.

stop_headsign Text Optional Contains the text, as shown on signage, that identifies the trip's destination to riders. Use this field to override the default trip_headsign when the headsign changes between stops. If this headsign is associated with an entire trip, use trip_headsign instead.
pickup_type Enum Optional

Indicates whether riders are picked up at a stop as part of the normal schedule or whether a pickup at the stop isn't available. This field also allows the transit agency to indicate that riders must call the agency or notify the driver to arrange a pickup at a particular stop. The following are valid values for this field:

  • 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
drop_off_type Enum Optional

Indicates whether riders are dropped off at a stop as part of the normal schedule or whether a dropoff at the stop is unavailable. This field also allows the transit agency to indicate that riders must call the agency or notify the driver to arrange a dropoff at a particular stop. The following are valid values for this field:

  • 0 or (empty): Regularly scheduled drop off
  • 1: No dropoff available
  • 2: Must phone agency to arrange dropoff
  • 3: Must coordinate with driver to arrange dropoff
shape_dist_traveled Non-negative float Optional

When used in the stop_times.txt file, the shape_dist_traveled field positions a stop as a distance from the first shape point. The shape_dist_traveled field represents a real distance traveled along the route in units such as feet or kilometers.

For example, if a bus travels a distance of 5.25 kilometers from the start of the shape to the stop, the shape_dist_traveled for the stop ID would be entered as 5.25. This information allows the trip planner to determine how much of the shape to draw when they show part of a trip on the map.

The values used for shape_dist_traveled must increase along with stop_sequence: they can't be used to show reverse travel along a route. The units used for shape_dist_traveled in the stop_times.txt file must match the units that are used for this field in the shapes.txt file.

timepoint Enum Optional

Indicates if the specified arrival and departure times for a stop are strictly adhered to by the transit vehicle, or if they're instead approximate or interpolated times. This field allows a GTFS producer to provide interpolated stop times that potentially incorporate local knowledge, but still indicate if the times are approximate.

For stop-time entries with specified arrival and departure times, the following are valid values for this field:

  • 0: Times are considered approximate.
  • 1 or (empty): Times are considered exact.

For stop-time entries without specified arrival and departure times, feed consumers must interpolate arrival and departure times. Feed producers can optionally indicate that such an entry is not a timepoint (with timepoint=0), but it's an error to mark an entry as a timepoint (with timepoint=1) without specifying arrival and departure times.

Timepoints

Timepoints are scheduled stops where the vehicle strictly adheres to the specified arrival and departure times. For example, if a transit vehicle arrives at a stop before the scheduled departure time, it holds until the departure time.

If a given stop isn't a timepoint, use either an empty string value for the arrival_time or departure_time fields or provide an interpolated time. To indicate that interpolated times have been provided, use a value of 0 for the timepoint field. If that's done, you must use a value of timepoint=1 to indicate times entered as timepoints.

Be sure to provide arrival and departure times for all stops that are timepoints.

calendar.txt

File: Conditionally required

Defines service dates when service is available for particular routes. Uses a weekly schedule. This file specifies start and end dates, as well as the days of the week when service is available. This file is required unless all of the dates of service are defined in calendar_dates.txt.

Field name Type Required 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. This value is referenced by the trips.txt file.
monday Enum Required

Indicates whether the service is valid for all Mondays within the date range specified by the start_date and end_date fields. The following are valid values for this field:

  • 1: Service is available for all Mondays in the date range.
  • 0: Service isn't available for Mondays in the date range.
tuesday Enum Required Functions similarly to the monday field, except for Tuesdays.
wednesday Enum Required Functions similarly to the monday field, except for Wednesdays.
thursday Enum Required Functions similarly to the monday field, except for Thursdays.
friday Enum Required Functions similarly to the monday field, except for Fridays.
saturday Enum Required Functions similarly to the monday field, except for Saturdays.
sunday Enum Required Functions similarly to the monday field, except for Sundays.
start_date Date Required Contains the start date for the service.
end_date Date Required Contains the end date for the service. This date is included in the service interval.

calendar_dates.txt

File: Conditionally required

The calendar_dates file allows you to explicitly activate or disable service by date. You can use it in two ways:

  • Recommended: Use calendar_dates.txt to create any exceptions to the default service categories defined in the calendar.txt file. This is a good approach if your service is generally regular with just a few changes on explicit dates, such as a school scedule or to accommodate special event services. In this case, calendar_dates.service_id is an ID that references calendar.service_id.

  • Alternate: Omit calendar.txt, and include every date of service in calendar_dates.txt. If your schedule varies most days of the month, or you want to programmatically output service dates without the need to specify a normal weekly schedule, this approach might be preferable. In this case, service_id is an ID.

Field name Type Required Description
service_id ID that references calendar.service_id, or ID Required

Identifies a set of dates when a service exception is available for one or more routes. Each pair of (service_id, date) can only appear once in calendar_dates.txt.

If the same service_id value appears in both the calendar.txt and calendar_dates.txt files, the information in calendar_dates.txt modifies the service information specified in calendar.txt.

This field is referenced by the trips.txt file.

date Date Required Specifies a particular date when service availability is different than normal. You can use the exception_type field to indicate whether service is available on the specified date.
exception_type Enum Required

Indicates whether service is available on the date specified in the date field. The following are valid values for this field:

  • 1: Service has been added for the specified date.
  • 2: Service has been removed for the specified date.

For example, suppose a route has one set of trips available on holidays and another set of trips available on all other days. You could have one service_id that corresponds to the regular service schedule and another service_id that corresponds to the holiday schedule. For a particular holiday, you would use the calendar_dates.txt file 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

Defines fare information for a transit agency's routes.

Field name Type Required Description
fare_id ID Required Identifies a fare class.
price Non-negative float Required Contains the fare price, in the units specified by currency_type.
currency_type Currency code Required Defines the currency used to pay the fare.
payment_method Enum Required

Indicates when the fare must be paid. The following are valid values for this field:

  • 0: The fare is paid when riders board.
  • 1: The fare must be paid before riders board.
transfers Enum Required

Specifies 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. The following are valid values for this field:

  • 0: No transfers are permitted on this fare.
  • 1: One transfer is permitted on this fare.
  • 2: Two transfers are permitted on this fare.
  • (empty): Unlimited transfers are permitted on this fare.
agency_id ID that references agency.agency_id Conditionally required

Identifies the relevant agency for a fare.

This field is required for datasets with multiple agencies defined in the agency.txt file. Otherwise, it's optional.

transfer_duration Non-negative integer Optional Specifies the length of time, in seconds, before a transfer expires. When used with a transfers value of 0, the transfer_duration field indicates how long a ticket is valid for a fare where no transfers are allowed. Unless you intend to use this field to indicate ticket validity, keep transfer_duration omitted or empty when transfers is set to 0.

fare_rules.txt

File: Optional

The fare_rules.txt file allows you to specify how fares in fare_attributes.txt apply to an itinerary. Most fare structures use some combination of the following rules:

  • The fare depends on the origin or destination stations.
  • The fare depends on which zones the itinerary passes through.
  • The fare depends on which route the itinerary uses.

For examples that demonstrate how to specify a fare structure with fare_rules.txt and fare_attributes.txt, see FareExamples in the GoogleTransitDataFeed open source project wiki.

Field name Type Required Description
fare_id ID that references fare_attributes.fare_id Required Identifies a fare class.
route_id ID that references routes.routes_id Optional

Associates the fare class with a route. If you have several routes with the same fare attributes, create a row in fare_rules.txt for each route.

For example, if fare class "b" is valid on the routes "TSW" and "TSE," the fare_rules.txt file would contain the following rows for the fare class:

fare_id,route_id
b,TSW
b,TSE
origin_id ID that references stops.zone_id Optional

Associates the fare class with an origin zone_id. If you have several origin zones with the same fare attributes, create a row in fare_rules.txt for each origin_id.

For example, if fare class "b" is valid for all travel that originates from either zone "2" or zone "8," the fare_rules.txt file would contain the following rows for the fare class:

fare_id,...,origin_id
b,...,2
b,...,8
destination_id ID that references stops.zone_id Optional

Associates the fare class with a destination zone_id. If you have several destination zones with the same fare attributes, create a row in fare_rules.txt for each destination_id.

For example, you could use the origin_ID and destination_ID fields 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 the following rows for the fare class:

fare_id,...,origin_id,destination_id
b,...,3,4
b,...,3,5
contains_id ID that references stops.zone_id Optional

Identifies the zones that a rider enters for a given fare class. Used in some systems to calculate the correct fare class.

For 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 file would contain the following rows:

zone_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 details, see FareExamples in the GoogleTransitDataFeed project wiki.

shapes.txt

File: Optional

Shapes describe the physical path that a vehicle takes, and they're defined in the file shapes.txt. Shapes are associated with individual trips, and they consist of a sequence of points. Trace the points in order to follow the path of the vehicle. The points don't need to match stop locations.

Field name Type Required Description
shape_id ID Required Identifies a shape.
shape_pt_lat Latitude Required Associates a shape point's latitude with a shape ID. Each row in shapes.txt represents a shape point used to define the shape.
shape_pt_lon Longitude Required Associates a shape point's longitude with a shape ID. Each row in shapes.txt represents a shape point used to define the shape.
shape_pt_sequence Non-negative integer Required

Associates the latitude and longitude of a shape point with its sequence order along the shape. The values for shape_pt_sequence must increase throughout the trip but don't need to be consecutive.

For example, if the shape "A_shp" has three points in its definition, the shapes.txt file might contain the following rows 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_traveled Non-negative float Optional

Provides the actual distance traveled along the shape from the first shape point to the point specified in this record. This information allows the trip planner to determine how much of the shape to draw when they show part of a trip on the map. The values used for shape_dist_traveled must increase along with shape_pt_sequence: they can't be used to show reverse travel along a route.

The units used for shape_dist_traveled in the shapes.txt file must match the units that are used for this field in the stop_times.txt file.

For example, if a bus travels along three points defined for the shape "A_shp," the additional shape_dist_traveled values, shown here in kilometers, would look like the following:

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

frequencies.txt

File: Optional

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

  • A frequency-based service, which uses exact_times=0. This service doesn't follow a fixed schedule throughout the day. Instead, operators attempt to strictly maintain predetermined headways for trips.

  • A compressed representation of schedule-based service, which uses exact_times=1. This service has the exact same headway for trips over a specified time period. In schedule-based service, operators try to strictly adhere to a schedule.

Field name Type Required Description
trip_id ID that references trips.trip_id Required Identifies a trip that the specified frequency of service applies to.
start_time Time Required Specifies the time at which the first vehicle departs from the first stop of the trip with the specified frequency.
end_time Time Required Specifies the time at which service changes to a different frequency (or ceases) at the first stop in the trip.
headway_secs Non-negative integer Required

Indicates the time, in seconds, between departures from the same stop, known as the headway, for this trip type. This applies during the time interval specified by start_time and end_time.

Within the same trip, multiple headways are allowed, but they can't overlap. However, a headway period can begin at the exact same time that another one ends.

exact_times Enum Optional

Indicates whether frequency-based trips are exactly scheduled based on the specified headway information. For more details, see the file description for frequencies.txt. The following are valid values for this field:

  • 0 or (empty): Frequency-based trips aren't exactly scheduled.
  • 1: Schedule-based trips that have the exact same headway throughout the day. In this case, the end_time value must be greater than the last desired trip's start_time but less than the last desired trip's start_time + headway_secs.

transfers.txt

File: Optional

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

Field name Type Required Description
from_stop_id ID that references 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 of its child stops.
to_stop_id ID that references 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 of its child stops.
transfer_type Enum Required

Indicates the type of connection for the specified pair (from_stop_id, to_stop_id). The following are valid values for this field:

  • 0 or (empty): This is a recommended transfer point between routes.
  • 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 rider to transfer between routes.
  • 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.
  • 3: Transfers aren't possible between routes at this location.
min_transfer_time Non-negative integer Optional Defines the amount of time, in seconds, that must be available in an itinerary to permit a transfer between routes at the specified stops. The min_transfer_time must be sufficient to permit a typical rider to move between the two stops, as well as some buffer time to allow for schedule variance on each route.

pathways.txt

File: Optional

Use pathways.txt to create a graph representation of the layout of a station. To go from an entrance node to a platform node, the rider must go through walkways, fare gates, stairs, or other pathways, which are represented as edges in the graph.

The list of intra-station pathways specified in pathways.txt must be exhaustive for a specific station. If a pathway is missing between nodes A and B, that means there's no direct connection between them. Therefore, the following common sense rules apply:

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

  • No locked platforms: Each platform must be connected to at least one entrance by some chain of pathways.

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

Field name Type Required Description
pathway_id ID Required Identifies the pathway. Different pathways can connect 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 directions, or when a stair and elevator both go from the same place to the same place.
from_stop_id ID that references stops.stop_id Required Defines the 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 that references stops.stop_id Required Defines the 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

Specifies the type of pathway between the specified pair (from_stop_id, to_stop_id). The following are valid values for this field:

  • 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. This is usually a physical payment gate.

    Fare gates might 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 route passengers through stations in a way that helps them avoid unnecessary payments.

  • 7: Exit gate. A pathway where passengers exit an area that required proof-of-payment to enter and which connects to an area where proof-of-payment is no longer required.
is_bidirectional Enum Required

Indicates in which directions the pathway can be used. The following are valid values for this field:

  • 0: Unidirectional pathway. It can only be used in the direction of from_stop_id toward to_stop_id.
  • 1: Bidirectional pathway. It can be used in either direction.

Fare gates (pathway_mode=6) and exit gates (pathway_mode=7) can't be bidirectional.

length Non-negative float Optional

Specifies the horizontal length, in meters, of the pathway. The length is measured from the origin location, defined in from_stop_id, to the destination location, defined in to_stop_id.

This field is recommended for walkways, fare gates, and exit gates, which have pathway_mode equal to 1, 6, and 7 respectively.

traversal_time Positive integer Optional

Specifies the average time needed to walk through the pathway. The following are valid values for this field:

  • (empty): Unknown travel time.
  • A positive integer: The number of seconds needed to traverse this pathway on foot.

This field is recommended for mechanical pathways, such as moving sidewalks, escalators, and elevators, which have pathway_mode equal to 3, 4, and 5 respectively.

stair_count Non-null integer Optional

Specifies the number of stairs of the pathway. A positive stair_count implies that the passenger walks up from from_stop_id to to_stop_id. A negative stair_count implies that the passenger walks down from from_stop_id to to_stop_id.

This field is recommended for stairs and escalator pathways, which have pathway_mode equal to 2 and 4 respectively.

As a best practice, we recommend the approximation of a change of one floor as equal to 15 stairs, or 12 for an escalator.

max_slope Float Optional

Specifies the maximum slope ratio of the pathway. The following are valid values for this field:

  • 0 or (empty): No slope.
  • A float: The slope ratio of the pathway, positive for upwards and negative for downwards.

Only use this field with walkways and moving sidewalks, which have the pathway_mode 1 and 3 respectively.

As an example, the maximum slope ratio allowed in the US for hand-propelled wheelchairs is 0.083 (also written 8.3%). This means that there's a vertical increase of 0.083 m for each 1 m horizontally.

min_width Positive float Optional

Contains the minimum width of the pathway, in meters.

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

signposted_as Text Optional Contains an exact string of text from physical signage that's visible to transit riders. The string can be used to provide text directions to users. Enter the language text in this field exactly how it's printed on the signs, without translation.
reversed_signposted_as Text Optional Same as the signposted_as field, but used when the pathway is traveled in the backward direction, that is, from the to_stop_id to the from_stop_id.

levels.txt

File: Optional

Describes the different levels of a station. The levels.txt file is mostly useful when used in conjunction with pathways.txt.

Field name Type Required Description
level_id ID Required Identifies the level of the station.
level_index Float Required

Indicates the relative position of this level in relation to other levels. Levels with higher indices are assumed to be located above levels with lower indices.

Use an index of 0 to indicate ground level, with levels above ground indicated by positive indices and levels below ground by negative indices.

level_name Text Optional

Provides the name of the level. Be sure the name matches the level lettering or numbering used inside the building or station.

This field is useful for elevator routing, such as directions to take the elevator to the levels "Mezzanine," "Platforms," or "-1."

feed_info.txt

File: Optional

The feed_info.txt file contains information about the feed itself, rather than the services that the feed describes. GTFS has an agency.txt file to provide information about the agencies that operate the services described by the feed. However, the publisher of the feed is sometimes a different entity than any of the agencies, such as in the case of regional aggregators. In addition, there are some fields that are really feed-wide settings, rather than agency-wide.

Field name Type Required Description
feed_publisher_name Text Required Contains the full name of the organization that publishes the dataset. This can be the same as one of the agency_name values in agency.txt.
feed_publisher_url URL Required Contains the URL of the dataset publishing organization's website. This can be the same as one of the agency_url values in agency.txt.
feed_lang Language code Required Specifies the default language used for the text in this dataset. This setting helps GTFS consumers choose capitalization rules and other language-specific settings for the feed.
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.

If both feed_end_date and feed_start_date are given, the end date must not precede the start date. Dataset providers are encouraged to give schedule data outside this period to advise passengers of likely future service, but dataset consumers should be mindful of its non-authoritative status.

If calendar.txt and calendar_dates.txt omit any active calendar dates that are included within the timeframe defined by feed_start_date and feed_end_date, this is an explicit statement that there's no service on those omitted days. That is, calendar.txt and calendar_dates.txt are assumed to be an exhaustive list of the dates when service is provided.

feed_end_date Date Optional For details on this field, see feed_start_date above.
feed_version Text Optional Specifies a string that indicates the current version of the GTFS dataset. GTFS-consuming applications can display this value to help dataset publishers determine whether the latest version of their dataset has been incorporated.
feed_contact_email Email Optional Provides an email address for communication about the GTFS dataset and data publishing practices. The feed_contact_email field provides a technical contact for GTFS-consuming applications. To provide customer service contact information, use the fields in agency.txt.
feed_contact_url URL Optional Provides a URL for contact information, a web form, support desk, or other tool for communication about the GTFS dataset and data publishing practices. The feed_contact_url field provides a technical contact for GTFS-consuming applications. To provide customer service contact information, use the fields in agency.txt.