1. Home
  2. Cal-ITP
  3. California Minimum GTFS Guidelines Version 1

California Minimum GTFS Guidelines Version 1

This version of the Guidelines was replaced on August 30, 2021. For the most recent version of the Guidelines, click here.

Version 1.0 – Finalized September 8, 2020

Table of Contents

  • Purpose
  • Overview
  • Principles
  • Data Process Checklist
  • Referenced Documents
  • Guideline Development Process
  • Frequently Asked Questions
  • Feedback and Update Processes
  • Tools and Resources

    • Purpose

    The California Minimum General Transit Feed Specification (GTFS) Guidelines help ensure that transit data in California meets the needs of the public which seeks to understand and use transit, and the agencies and operators - providers - that plan, manage, and run the transportation network.

    Overview

    These Guidelines are composed of overarching Principles as well as a Data Process Checklist that articulate the technical requirements to support the Principles and comply with the Guidelines.

    The Data Process Checklist references existing data standards and best practices to avoid placing additional burden on transit providers. They were developed as part of the California Integrated Travel Project (Cal-ITP), which is dedicated to making travel simpler and cost-effective for all.

    Principles

    A public transit provider shall commit to the following principles, which should be reflected in transit provider processes that are consistent with the Data Process Checklist:

    • Provide the public with accurate information in order to plan journeys for any ability–standardized schedule, service, fare, access, and geographic data that is complete, correct, and up-to-date.
    • Provide riders with real-time information for making efficient decisions along their journey through accurate information about vehicle arrivals.
    • Make information easy-to-use in any application by providing standardized and public static and real-time GTFS data feeds.
    • Pursue industry standardization in order to provide better coordination, service delivery, and clear information for the industry in the future.

    Data Process Checklist

    In order to adhere to the above principles, public transit providers shall follow processes that are consistent with the following prioritized checklist:

    1. Publish current transit data (GTFS and GTFS Realtime 2.0 feeds) at static fetch URLs.
    2. Publish static GTFS data feeds that include a high-fidelity shapes.txt, persistent agency, stop and route identifiers, and implement all recommendations made in the Best Practices for GTFS for transit services open to the general public for which the provider is responsible.
    3. Describe planned service changes in the static GTFS feed when they are known in advance. Publish a static GTFS feed update at least two weeks ahead of service updates to provide time for engaging with feedback from developers and data feed consumers. 
    4. Publish GTFS Realtime 2.0 Vehicle Positions, Trip Updates, and Service Alert feeds for fixed routes in the provider’s officially published static GTFS data feed. Real-time vehicle information should be updated every 20 seconds or faster, have a trip_id that matches the static GTFS feed, persistent unique vehicle ids, and per-vehicle timestamps.
    5. Make their GTFS and GTFS Realtime data feeds available on the feed aggregators https://transit.land/ and openmobilitydata.org.
    6. Publish static GTFS pathways (pathways.txt, levels.txt) for infrastructure operated by the provider with stairs, escalators, elevators, or other accessibility considerations. 
    7. Offer GTFS and GTFS Realtime data without an extensive legal agreement, preferably under an open data license.
    8. GTFS Realtime APIs should have an uptime of greater than 99%.
    9. Publish a single point of contact for GTFS data on the provider’s website, and in the feed info component of GTFS, as well as offer a way for data consumers to register with the transit provider so that they can be easily reached. 
    10. Maintain a process for tracking and improving accuracy of technology systems and revisiting best practices and these Guidelines.

    Referenced Documents

    1. GTFS Specification: https://developers.google.com/transit/gtfs/reference
    2. GTFS Realtime 2.0 Specification: https://developers.google.com/transit/gtfs-realtime
    3. GTFS Best Practices: http://gtfs.org/best-practices/

    Guideline Development Process

    These Guidelines were developed by the California Integrated Travel Project team at Caltrans. Draft Guidelines were posted in May 2020 and open for comment through July 21, 2020. The 1.0 version of the Guidelines includes several minor changes from the posted draft, in response to requests for clarification and prioritization that were received in the public comments.

    The Guidelines will be updated every year, at which time Caltrans will evaluate potential changes based on feedback, experience, and additional opportunities consistent with global data standards and/or technology. Please send comments with suggested edits to the Guidelines to gtfsrt@dot.ca.gov. Caltrans may update or simplify the wording of the Guidelines on a more frequent basis for clarity, which would result in a minor update (i.e., from 1.0 to 1.1) to the version number

    Caltrans anticipates adding the following GTFS extensions to the Guidelines after they are adopted in the official GTFS definition. Caltrans encourages transit providers to actively participate in the discussion and development of these proposals by:

    • Commenting on the draft documents themselves;
    • Participating in MobilityData member meetings (base membership is free for public agencies);
    • Discussing issues and proposed incremental changes to the specifications in the GTFS specification repository ; or
    • Emailing gtfsrt@dot.ca.gov to express your priorities so that we can help you navigate the process, advocate on your behalf, and/or evaluate additional information-sharing mechanisms. 

    GTFS-Flex

    GTFS-Flex describes “flexible” or “demand responsive” transit–any transit service where riders do not get on or off at fixed stops along a fixed route, such as:

    • Transit services with dial-a-ride or similar request-triggered trips,
    • Transit services where a vehicle can deviate from a fixed route to pick up or drop off riders, and 
    • Transit services where riders can board or alight anywhere within a zone.

    For providers that wish to include demand-responsive transit ahead of Flex 2.0 adoption, a subset of Flex 2.0 for hail-and-ride services is proposed as GTFS-ContinuousStops and is partially supported in some trip planners.

    Anticipated Adoption: 2021

    GTFS-Fares

    GTFS-Fares 2.0 significantly expands the fare-related functionality of GTFS, including rush-hour fares, fare containers, and multiple-fare products. 

    Anticipated Adoption: 2021 

    GTFS-Pathways

    While the core components of GTFS-Pathways have been fully incorporated into GTFS, there are several outstanding items in the full GTFS-Pathways proposal that are on track to be adopted at a later date, and are critical to creating comprehensive accessibility to transit route-planning and wayfinding:

    • Additional fields in pathways.txt, such as text-to-speech instructions, wheelchair assistance information, equipment-failure reporting, tactile strips, etc.
    • GTFS-PathwaysEvolutions, which indicates planned or scheduled entrance or exit closures, elevator outages, escalator outages, etc. 
    • GTFS-StationUpdate, the real-time pathways component that encodes real-time information and alerts about outages to pathways such as elevators and escalators.

    Anticipated Adoption: 2021 

    GTFS-Text to Speech

    The GTFS-Text-To-Speech specification extension has been partially adopted but is not yet functional in most mapping applications. 

    Anticipated Adoption: 2021 

    GTFS-Vehicles

    GTFS-Vehicles encodes transit vehicle characteristics, such as seating capacity, bike capacity, and various accessibility-related attributes. 

    GTFS-Vehicles, when adopted, will be part of the Guidelines for transit providers with fleets that are not able to represent their accessibility via wheelchair or mobility device at the trip or stop level.

    Anticipated Adoption: 2021 

    Shared Infrastructure Identifiers

    MobilityData is developing a Mobility Database that will create stable identifiers for transit infrastructure that is shared between feeds. These stable identifiers will serve as aliases and not replace any local transit provider identifiers (stop and route ids). 

    Where relevant and feasible, infrastructure (e.g., stations, pathways) that is shared among transit providers with separate GTFS feeds shall include external identifiers to shared infrastructure in the Mobility Database.

    Anticipated Adoption: 2021 

    Interagency/Interfeed Relationships (e.g., fares)

    MobilityData’s Mobility Database will have the ability to represent relationships between transit providers and GTFS feeds. 

     Where relevant and feasible, inter-feed relationships for data within the scope of GTFS, particularly fares, will be maintained in the Mobility Database.

    Anticipated Adoption: 2021 

    Frequently Asked Questions

    What is GTFS?

    The General Transit Feed Specification (“GTFS”) is the global standard for describing transit digitally. GTFS is used by thousands of agencies world-wide, including roughly half of all transit agencies in the US.

    First created in 2006 through a public-private partnership between Trimet— the public transit agency in Portland, Oregon—and Google, the continued development and refinement of the GTFS specification is carried out by a global community of public and private GTFS data producers and consumers. Officially recognized additions and modifications of the spec are reviewed and approved by the independent nonprofit organization MobilityData.

    Why did Caltrans develop these Guidelines?

    Caltrans developed the California Minimum GTFS Guidelines to help ensure that data for transit providers in California meets the needs of travelers as well as planners and system managers who plan, manage, and operate the transportation network. The Guidelines provide a consistent minimum expectation to ensure that people of all abilities can easily move throughout the statewide public transportation network. 

    Does my organization need to follow the Guidelines?

    We recommend that transit providers follow these Guidelines in order to best serve the public good by providing accurate, complete, and up-to-date transit information. In growing ridership - by making transit more visible - Caltrans expects transit operators and the public to benefit, and to ensure that projects funded by Caltrans achieve the benefits of integration among operators. 

    How do I know if my organization is compliant with these Guidelines?

    We recommend working with the department or vendor who provides your organization’s technical services to review the Data Process Checklist. If you need assistance in assessment, please contact gtfsrt@dot.ca.gov. 

    How can I comply with these Guidelines if I don't already? How can I get help implementing these?

    There are a number of potential pathways toward Guideline compliance depending on current statuses of your data pipeline. This can include:

    • identifying funding for equipment,
    • adding these guidelines in future vendor contracts and procurements,
    • collecting and maintaining additional data, and
    • updating website language.

     We’re here to help you understand and successfully implement these Guidelines no matter your circumstances. Email us at gtfsrt@dot.ca.gov if you are having difficulties implementing these Guidelines, and we will try to help.

     How do transit riders and the public "see" the data that transit providers provide?

    The most common ways for transit riders to see the data is via:

    • a consumer-facing application (through a web browser or phone interface),
    • transit provider signage, and
    • commercial displays (for example at coffee shops, offices, sports and events venues, and apartment buildings). 

     California’s raw GTFS data can be seen:

    Feedback and Update Processes

    We welcome your feedback on the Guidelines via email to: gtfsrt@dot.ca.gov

    We will update the Guidelines every year. Updates will be influenced by advances in the adopted GTFS specification, equipment sufficiency, and unforeseen events such as COVID-19.

    Tools and Resources

    GTFS Specification and Best Practices Assistance

    Caltrans, on behalf of transit riders within California, has a subscription to MobilityData to serve as a limited technical resource about the GTFS specification itself as well as best practices. Assistance is available by joining MobilityData IO chat on Slack. To join the Slack community, sign up at using a Mobility Data Form. To ask a question via email, please contact gtfsrt@dot.ca.gov.

    Peer Groups

    Caltrans, as part of the California Integrated Travel Project, has been assembling small groups of staff at similar-sized transit providers to discuss their technology stacks. Please let us know if you would like to participate at gtfsrt@dot.ca.gov.

    Selecting and Implementing a Data License

    Agency GTFS data should be offerctingGed under the latest version of the Open Data Commons Attributions (ODC-BY) or Creative Commons Attributions license (currently CC-BY 3.0), which is consistent with the license required by the National Transit Map. These licenses should be adopted as-is, without additional requirements that would add undue complexity down the line.

    Other “attribution” licenses are often attractive and are also fine to use; however, “share-alike” type licenses limit the use of the data by some user applications and should be avoided.

    Best Practices

    The GTFS Best Practices are a community-driven set of requirements above and beyond the minimum GTFS specification, and are managed by MobilityData to facilitate a more seamless customer experience

    Implementing Static URLs

    Static URLs (web addresses that don’t change) for your GTFS and GTFS Realtime feeds are critical in order to enable user-facing applications – as well as the general public – know where to go to find your latest information. Changing the URL each time your GTFS data is updated may cause your transit provider’s information to disappear from user-facing applications (due to a broken link). 

    The GTFS Dataset Publishing & General Practices provide guidance on the recommended practice of hosting the GTFS data on a transit provider website. A consistent link to cloud storage or an FTP location would also satisfy these Guidelines, and as a last resort, posting the feeds each time they change to http://openmobilitydata.org also works.

    Providing a static URL for the most recent data does not prevent you from storing historical GTFS data on your website at different addresses.

    Uploading a GTFS file to the Google Transit Partner portal does not satisfy the static URL guideline, nor does hosting it on the transit provider website with a date or version in the file name or URL structure.

     Providing a static URL for the most recent data does not prevent you from storing historical GTFS data on your website at different addresses. 

     The following are example data links for current and historical data (these links are only for demonstration and are not active):

    • http://mytransitagency.gov/data/gtfs/current/gtfs.zip
    • http://mytransitagency.gov/data/gtfs/2020-01-02_2020-03-22/gtfs.zip
    • http://mytransitagency.gov/data/gtfs/2020-03-23_2020-04-01/gtfs.zip
    • http://mytransitagency.gov/data/gtfs/2020-04-02_2020-04-30/gtfs.zip

    Feeds with Overlapping Time Frames

    A feed with multiple service calendar time periods is required to satisfy the Guideline of representing any changes to transit service at least fourteen (14) days in advance of it taking effect. Merged feeds can be created by adding additional service_ids to calendar.txt and concatenating the two GTFS feed files (with appropriate references to each service_id).

    Adding GTFS Feeds to Feed Aggregators

    The following links are instructions for posting transit data to various transit data aggregators:

    1. OpenMobilityData.org: submit an issue
    2. TransitLand Atlas: add a new feed
    3. Google Transit Data Partner dashboard: accessing the dashboard
    4. Bing Maps email
    5. Apple email

    Representing Occupancy in Response to COVID-19

    GTFS-Realtime has OccupancyStatus as an experimental field. In response to COVID-19 social distancing, MobilityData provides guidance for how to use this field—limiting the values to: 

    • Many seats available
    • Few seats available
    • Full

    Several consumer-facing applications are able to display this value to riders so that they are better able to plan their transit trips. Transit providers that want help understanding what it would take for their systems to provide occupancy on a real-time basis should contact gtfsrt@dot.ca.gov.

     See issue 222 on the GTFS specification repository for further discussion.

    Data Consumer Registration

    If a transit provider doesn’t already have a contact database, customer relationship management (CRM) system, or an existing way to manage stakeholders, there are a number of freely available lightweight services that can add an email signup to your provider’s website.

    Data Validators

    MobilityData is developing a canonical GTFS validator that is currently available as open source code on GitHub. Future development will include a friendlier user experience via a hosted instance, as well as implementation of additional validation checks.

     The Center for Urban Transportation Research (CUTR) at University of South Florida (USF) developed an open-source GTFS Realtime validator.

     Note that passing the MobilityData or CUTR validators does not guarantee that your data will pass the validation of all transit rider applications, although work is being done to make that easier.

    GTFS-Pathways Builder and Visualizer

    GTFS-Pathways is a nascent extension and thus does not have the same level of tools built around it that other GTFS components do. However, there is a limited-functionality, open-source, web-based tool available that can help get you started with editing and visualizing pathways data.  

    Real-Time System Best Practices

    No official GTFS Realtime best practices have been published. There are resources that can help transit providers define best practices in real-time system specifications:

    Transit Provider Guideline Evaluation Examples

    In order to provide a concrete example of what the Guidelines look like at a real transit provider, we performed a hypothetical assessment of Monterey-Salinas Transit.

    Request Assistance

    We're here to help you understand and successfully implement the Guidelines. Email us at gtfsrt@dot.ca.gov if you are having difficulties implementing the Guidelines and we will try to help.