Skip to main content

GTFS Documentation

About This Document

This document describes the MBTA's GTFS feed. It is intended to supplement, not replace, documentation on GTFS itself.

Upcoming Changes

Richer station models with entrances, transfer times, elevators, escalators, parking, bike cages, and more are expected in late 2017.

Watch the MassDOT/MBTA Developers Google Group for announcements with more details.

Accessing the MBTA GTFS Feed

The MBTA GTFS feed can be downloaded here. It is updated at least 4 times a year, but is subject to change at any time. We recommend checking for a new feed on a daily basis. It is always available at the above URL. 

We recommend using the "Last Modified" header to see whether there's been an update. 

Previously, this header was unreliable for this purpose, so we recommended that developers have their applications download the current feed_info.txt file here, and compare it to their current feed_info.txt file from their last GTFS download. This approach is now deprecated. However, feed_info.txt will continue to be available as its own file until April 2018.

Archived files are also available. 

About the Fields in This Document

  • Status field indicates whether field is in use
    • Included (some records)
    • Included (empty): Included, but not populated
    • N/A: Part of GTFS specifications, but not included in MBTA GTFS
    • Coming soon: Will be included in upcoming GTFS version
    • Deprecated: No longer supported
    • Persistent: Value for record will not change between one feed_version and the next
  • GTFS Spec field
    • Required
    • Optional
    • Experimental: Not part of GTFS specifications, but included in MBTA GTFS

GTFS Files

Table NameGTFS SpecStatusNotes
Table Nameagency.txtGTFS SpecRequiredStatusIncludedNotes 
Table Namecalendar.txtGTFS SpecRequiredStatusIncludedNotes
Generated programmatically. May not be easy for humans to read.
Table Namecalendar_dates.txtGTFS SpecOptionalStatusIncludedNotes
Generated programmatically. May not be easy for humans to read.
Table Namefare_attributes.txtGTFS SpecOptionalStatusN/ANotes 
Table Namefare_rules.txt GTFS SpecOptionalStatusN/ANotes 
Table Namefeed_info.txtGTFS SpecOptionalStatusIncludedNotes 
Table Namefrequencies.txtGTFS SpecOptionalStatusIncludedNotes
frequencies.txt is only used for Massport airport shuttles. If these move to a different feed, then frequencies.txt will be removed.
Table Namemulti_route_trips.txtGTFS SpecExperimentalStatusIncludedNotes
For trips that travel on more than one route, this file identifies additional routes the trip should be associated with.
Table Nameroutes.txtGTFS SpecRequiredStatusIncludedNotes 
Table Nameshapes.txtGTFS SpecOptionalStatusIncludedNotes 
Table Namestops.txtGTFS SpecRequiredStatusIncludedNotes 
Table Namestop_times.txtGTFS SpecRequiredStatusIncludedNotes 
Table Nametransfers.txtGTFS SpecOptionalStatusIncludedNotes 
Table Nametrips.txtGTFS SpecRequiredStatusIncludedNotes 

agency.txt

Agencies include the MBTA, CapeFlyer, and Massport (for airport shuttles). CapeFlyer and Massport may move to separate GTFS feeds in the future.

Field NameGTFS SpecStatusNotes
Field Nameagency_idGTFS SpecOptionalStatusIncludedNotesMBTA agency_id = 1.
Field Nameagency_nameGTFS SpecRequiredStatusIncludedNotes 
Field Nameagency_urlGTFS SpecRequiredStatusIncludedNotes 
Field Nameagency_timezoneGTFS SpecRequiredStatusIncludedNotes 
Field Nameagency_langGTFS SpecOptionalStatusIncludedNotes 
Field Nameagency_phoneGTFS SpecOptionalStatusIncludedNotes 
Field Nameagency_fare_urlGTFS SpecOptionalStatusN/ANotes 
Field Nameagency_emailGTFS SpecOptionalStatusN/ANotes 

calendar.txt

Field NameGTFS SpecStatusNotes
Field Nameservice_idGTFS SpecRequiredStatusIncludedNotes 
Field NamemondayGTFS SpecRequiredStatusIncludedNotes 
Field NametuesdayGTFS SpecRequiredStatusIncludedNotes 
Field NamewednesdayGTFS SpecRequiredStatusIncludedNotes 
Field NamethursdayGTFS SpecRequiredStatusIncludedNotes 
Field NamefridayGTFS SpecRequiredStatusIncludedNotes 
Field NamesaturdayGTFS SpecRequiredStatusIncludedNotes 
Field NamesundayGTFS SpecRequiredStatusIncludedNotes 
Field Namestart_dateGTFS SpecRequiredStatusIncludedNotes 
Field Nameend_dateGTFS SpecRequiredStatusIncludedNotes 

calendar_dates.txt

Field NameGTFS SpecStatusNotes
Field Nameservice_idGTFS SpecRequiredStatusIncludedNotes 
Field NamedateGTFS SpecRequiredStatusIncludedNotes 
Field Nameexception_typeGTFS SpecRequiredStatusIncludedNotes 

feed_info.txt

Field NameGTFS SpecStatusNotes
Field Namefeed_publisher_nameGTFS SpecRequiredStatusIncludedNotes 
Field Namefeed_publisher_urlGTFS SpecRequiredStatusIncludedNotes 
Field Namefeed_langGTFS SpecRequiredStatusIncludedNotes 
Field Namefeed_start_dateGTFS SpecOptionalStatusIncludedNotesWhen comparing two GTFS feeds the newer feed will always have a newer feed_start_date.
Field Namefeed_end_dateGTFS SpecOptionalStatusIncludedNotes 
Field Namefeed_versionGTFS SpecOptionalStatusIncludedNotes 

frequencies.txt

frequencies.txt is only used for Massport airport shuttles. If these move to a different feed,  then frequencies.txt will be removed.

Field NameGTFS SpecStatusNotes
Field Nametrip_idGTFS SpecRequiredStatusIncludedNotes 
Field Namestart_timeGTFS SpecRequiredStatusIncludedNotes 
Field Nameend_timeGTFS SpecRequiredStatusIncludedNotes 
Field Nameheadway_secsGTFS SpecRequiredStatusIncludedNotes 
Field Nameexact_timesGTFS SpecOptionalStatusN/ANotes 

multi_route_trips.txt

This is an experimental file. 

Some transit trips serve more than one route. For example, Commuter Rail trips that travel partly on the Lowell Line and partly on the Haverhill Line, or bus trips labeled "route 62/76" that should be shown on the respective schedules for both route 62 and route 76. This applies when a trip serves one route and then the other, but also when the trip serves a unique combination of stops from each route.

This file indicates routes that a trip is associated with, in addition to the route_id identified with this trip in trips.txt. If showing a schedule of all service on a route, that display should include trips associated with the route in multi_route_trips.txt. If showing general information about a trip in a different context, the route_id identified with the in trips.txt is still the best route to label the trip with. 

If a route’s every trip appears here, that route does not have any trips of "its own" and should probably not be shown to customers in lists of routes. Examples include route 62/76, which to a customer is an indication of route 62 service and route 76 service, not its own route.

Field NameGTFS SpecStatusNotes
Field Nameadded_route_idGTFS SpecExperimentalStatusIncludedNotesAn additional route_id associated with the given trip_id. Can appear repeatedly if more than one trip is added to it.
Field Nametrip_idGTFS SpecExperimentalStatusIncludedNotesThe trip_id of the trip which has the additional route associated with it. Can appear repeatedly if it is being added to more than one route.

routes.txt

Field NameGTFS SpecStatusNotes
Field Nameroute_idGTFS SpecRequiredStatusIncluded (persistent)Notes 
Field Nameagency_idGTFS SpecOptionalStatusIncluded (persistent)Notes 
Field Nameroute_short_nameGTFS SpecRequiredStatusIncluded (some records)Notes

Populated for service with branches (such as Green Line or Silver Line), local bus, express bus, limited service bus, key bus routes, and Massport.

If route_short_name is populated for a record and route_long_name is not, then "Route route_short_name" is an appropriate way to describe the route.

Field Nameroute_long_nameGTFS SpecRequiredStatusIncluded (some records)Notes

Populated for Commuter Rail, CapeFlyer, rapid transit, ferry, and Massport.

For services with branches, both route_long_name and route_short_name are populated. 

route_short_name contains the branch designation only, and route_long_name identifies both the route and the branch.

Field Nameroute_descGTFS SpecOptionalStatusIncluded (some records)Notes

Categorizes type of service. For example, identifies whether bus service is express bus or local bus, identifies if service is rapid transit.

Note that "Rapid Transit" route_desc values are associated with multiple route_type values.

Possible Values:
Airport Shuttle
Commuter Rail
Rapid Transit
Local Bus
Key Bus Route (Frequent Service)
Limited Service
Express Bus
Ferry

Field Nameroute_typeGTFS SpecRequiredStatusRequiredNotesIndicates the type of vehicle that operates the route. It is not recommended to use this field's values to categorize MBTA service.
Field Nameroute_urlGTFS SpecOptionalStatusIncluded (some records)Notes 
Field Nameroute_colorGTFS SpecOptionalStatusIncluded (some records)Notes 
Field Nameroute_text_colorGTFS SpecOptionalStatusIncluded (some records)Notes 
Field Nameroute_sort_orderGTFS SpecExperimentalStatusIncludedNotesInteger value that can be used for ordering routes in a way that is ideal for presentation to customers.

shapes.txt

Field NameGTFS SpecStatusNotes
Field Nameshape_idGTFS SpecRequiredStatusIncludedNotes 
Field Nameshape_pt_latGTFS SpecRequiredStatusIncludedNotes 
Field Nameshape_pt_lonGTFS SpecRequiredStatusIncludedNotes 
Field Nameshape_pt_sequenceGTFS SpecRequiredStatusIncludedNotes 
Field Nameshape_dist_traveledGTFS SpecOptionalStatusIncluded (empty)Notes 

stops.txt

Watch the MassDOT/MBTA Developers Google Group and this space for news about upcoming changes to stops.txt, including new stop_types, new platform fields, and more.

Field NameGTFS SpecStatusNotes
Field Namestop_idGTFS SpecRequiredStatusIncluded (persistent)NotesExpect field length to not exceed 45 characters.
Field Namestop_codeGTFS SpecOptionalStatusIncludedNotesField is populated only for subway and bus stops, where it has the same value as stop_id. Not prominently displayed or widely used, but visible on some bus stop signs.
Field Namestop_nameGTFS SpecRequiredStatusIncludedNotes

For bus stop, indicates geographic location of stop, with first street listed as the street the bus is traveling on, and second street listed (after "@" or "opp") as the cross street. For subway stop, indicates inbound or outbound direction.

For records with a parent_station value, use the child stop_name to indicate specific boarding location, but use the parent stop_name to identify the stop generally.

Average stop_name length is 24 characters. Expect field length to not exceed 60 characters.

Bus stops do not contain "stop" with a few exceptions ("Terminal B stop 1","Terminal B stop 2"). Subway and commuter rail stations do not contain "station" with a few exceptions ("North Station","South Station").

Field Namestop_descGTFS SpecOptionalStatusIncluded (some records)NotesCurrently only used for one stop
Field Namestop_latGTFS SpecRequiredStatusIncludedNotesRecords with a parent_station value currently have the same stop_lat value as the parent_station. However, the parent_station and child stop_lat values will differ in future versions of GTFS.
Field Namestop_lonGTFS SpecRequiredStatusIncludedNotesRecords with a parent_station value currently have the same stop_lon value as the parent_station. However, the parent_station and child stop_lon values will differ in future versions of GTFS.
Field Namezone_idGTFS SpecOptionalStatusIncluded (empty)Notes 
Field Namestop_urlGTFS SpecOptionalStatusIncluded (empty)Notes 
Field Namelocation_typeGTFS SpecOptionalStatusIncludedNotes 
Field Nameparent_stationGTFS SpecOptionalStatusIncluded (some records)Notes

For subway stations, the parent_station stop represents the whole facility and the child stop represents a specific platform. Use for identifying a station and indicating where specifically to enter a vehicle, respectively.

All subway stops have a parent station. If a commuter rail stop also serves the subway, then it will have a parent station. The future update will include parent stations for all commuter rail stops.

Field Namestop_timezoneGTFS SpecOptionalStatusN/ANotes 
Field Namewheelchair_boardingGTFS SpecOptionalStatusIncludedNotes 

stop_times.txt

Field NameGTFS SpecStatusNotes
Field Nametrip_idGTFS SpecRequiredStatusIncludedNotes 
Field Namearrival_timeGTFS SpecRequiredStatusIncludedNotes 
Field Namedeparture_timeGTFS SpecRequiredStatusIncludedNotes 
Field Namestop_idGTFS SpecRequiredStatusIncluded (persistent)Notes 
Field Namestop_sequenceGTFS SpecRequiredStatusIncludedNotes 
Field Namestop_headsignGTFS SpecOptionalStatusIncluded (empty)NotesMay be used in the future.
Field Namepickup_typeGTFS SpecOptionalStatusIncludedNotesA pickup_type of 3 represents a commuter rail "flag" stop marked with "F" on the schedule. Customer must visible to the approaching train to board.
Field Namedrop_off_typeGTFS SpecOptionalStatusIncludedNotesA drop_off_type of 3 represents a commuter rail "flag" stop marked with "F" on the schedule. Customer must notify the conductor to exit.
Field Nameshape_dist_traveledGTFS SpecOptionalStatusN/ANotes 
Field NametimepointGTFS SpecOptionalStatusIncludedNotesOn Commuter Rail, stops that are not timepoints and are not the last stop are labeled "L" on printed schedules to indicate that the train may leave early. MBTA bus and subway operation does not have many scheduled hold points so very few of their stop_times have a timepoint value of 1.

transfers.txt

Field NameGTFS SpecStatusNotes
Field Namefrom_stop_idGTFS SpecRequiredStatusIncludedNotes 
Field Nameto_stop_idGTFS SpecRequiredStatusIncludedNotes 
Field Nametransfer_typeGTFS SpecRequiredStatusIncludedNotes 
Field Namemin_transfer_timeGTFS SpecOptionalStatusIncluded (some records)NotesAs specified in the GTFS standard, this field is the sum of min_walk_time and suggested_buffer_time.
Field Namemin_walk_time GTFS SpecExperimentalStatusIncluded (some records)NotesMinimum time required to travel by foot from from_stop_id to to_stop_id.
Field Namemin_wheelchair_timeGTFS SpecExperimentalStatusIncluded (some records)NotesMinimum time required to travel by wheelchair from_stop_id to to_stop_id. If the transfer is not wheelchair accessible, this field will be blank.
Field Namesuggested_buffer_timeGTFS SpecExperimentalStatusIncluded (some records)NotesRecommended buffer time to allow to make a successful transfer between two services. This is also partly based on the significance of missing the transfer (due to service frequency).
Field Nameaccessible_transferGTFS SpecExperimentalStatusIncluded (some records)Notes1 if a transfer is wheelchair accessible, 2 if it is not.

trips.txt

Field NameGTFS SpecStatusNotes
Field Nameroute_idGTFS SpecRequiredStatusIncluded (persistent)Notes 
Field Nameservice_idGTFS SpecRequiredStatusIncludedNotes 
Field Nametrip_idGTFS SpecRequiredStatusIncluded (persistent)Notes 
Field Nametrip_headsignGTFS SpecOptionalStatusIncludedNotes

The average trip_headsign length is 13 characters. Expect field length to not exceed 80 characters.

Formats:
Destination
Example: Park Street
Destination via Street or Landmark
Example: Andrew via South Bay Center
Destination via Street or Landmark & Second Street or Landmark
Example: Wood Island via Market Basket & Admiral's Hill
Destination via Street or Landmark and Second Street or Landmark 
Example: Downtown Express via Airport and Paradise Road
Destination (Express)
Example: Haymarket (Express)
Destination (Limited Stops)
Example: Boston Medical Center (Limited Stops)
Destination via Street or Landmark (Express)
Example: Woburn via Medford Square (Express)
Destination via Street or Landmark and Second Street or Landmark (Express)
Example: Marblehead via Central Sq & Humphrey St (Express)

Field Nametrip_short_nameGTFS SpecOptionalStatusIncluded (some records)Notestrip_short_name is only a persistent identifier for Commuter Rail and CapeFlyer, field is blank for other modes. Even though it is not an "ID" field it can be used to keep track of trips through schedule changes. Do not assume that every commuter rail trip will have a trip_short_name.
Field Namedirection_idGTFS SpecOptionalStatusIncluded (persistent)NotesRefer to trip_headsign value to determine which destination indicates inbound or outbound direction for route.
Field Nameblock_idGTFS SpecOptionalStatusIncluded (some records)Notes

block_id does not imply that a customer can remain on a vehicle through to the next trip, although there are some routes where this is permitted. These routes will be identified in a future GTFS change. 

Routes that allow ride-through to next trip:
26, 43, 67, 76, 741, 742, 749

Field Nameshape_idGTFS SpecOptionalStatusIncludedNotesGenerally included, but not guaranteed.
Field Namewheelchair_accessibleGTFS SpecOptionalStatusIncludedNotesFor MBTA vehicles that are wheelchair accessible, the value is always 1.
Field Namebikes_allowedGTFS SpecOptionalStatusN/ANotes 
Field Nametrip_route_typeGTFS SpecOptionalStatusIncluded (some records)NotesIndicates the type of vehicle that operates the particular trip if the type of vehicle is not the same as specified in the route's route_type (i.e. if part of Blue Line subway service is replaced with a shuttle bus for one weekend). Definitions match those of route_type. For most trips, this is empty.

The MBTA GTFS Archive

For those interested in historical schedule data, an archive of GTFS files previously published by the MBTA are available. They are organized by the dates for which they were available and valid. 

We made a few adjustments to the archive for accuracy:

  • Added feed_info.txt to files that did not have it
  • Adjusted the feed_start_date and feed_end_date to reflect the best date range to use for each file
  • When a feed was published to correct an error in another, we replaced the erroneous feed, rather than adding a new feed

We have not gone through earlier feeds to correct errors that were not identified at the time, or to add fields introduced in later feeds. We do not plan to do this in the future. Descriptions of each file, including their URLs, are available in CSV format in archived_feeds.txt. This file contains the following fields:

Field NameDescription
Field Namefeed_start_dateDescriptionFirst date for which this feed should be used (matches same field in feed_info.txt)
Field Namefeed_end_dateDescriptionLast date for which this feed should be used (matches same field in feed_info.txt)
Field Namefeed_versionDescriptionA human-readable name for the feed (matches same field in feed_info.txt)
Field Namearchive_urlDescriptionA URL where the feed is available for download
Field Namearchive_noteDescriptionNotes on the content of the feed

Recent Changes

11/19/17:

  • Removed "persistent" from trip_id description to reflect that over time, what customers consider the same trip might have different trip_id's.
  • Updated trip_route_type from "coming soon" to "included (some records)." 
  • Various clarifications as part of document migration.

Use of MBTA data is governed by the MassDOT Developers License Agreement.