1. Home
  2. Cal-ITP
  3. California Minimum General Transit Feed Specification (GTFS) Guidelines

California Minimum General Transit Feed Specification (GTFS) Guidelines

Version 2.0 – Finalized August 31, 2021 

Table of Contents

  • Purpose
  • Applicability
  • Overview
  • Principles
  • Data Process Checklist
  • Guideline Development Process
  • Tools and Resources
  • Frequently Asked Questions

    • Purpose

    The purpose of this document is to explain the data standard that enables riders to understand when their next bus or train is arriving, how much their fare will be, and other important factors that impact each potential customer’s ability to easily access transit, and to establish expectations for this standard as State of California Guidelines.

    To achieve accurate and robust transit information sharing, California’s Department of Transportation (Caltrans) supports use of the globally recognized General Transit Feed Specification (GTFS) standard to describe trip-planning information, and with these guidelines establishes consistent expectations for quality (accuracy, completeness, availability, and stability) of this data. With universal, standardized, high-quality trip-planning information, California’s transit riders, providers, and regulators can more effectively understand the transportation network—and riders can find transit on trip-planning maps and apps.

    Within the State of California, transit providers are expected by Caltrans to work toward compatibility with these Guidelines. These Guidelines describe the data that transit riders deserve, and Caltrans understands that many of these improvements can take months to achieve (such as procuring new vendors) or, in limited cases, even years (when new technologies and practices are needed).

    Caltrans staff at the Division of Rail and Mass Transportation (DRMT) are available to assess a transit provider’s current GTFS data and co-develop a Transit Data Improvement Strategy. A Strategy outlines the steps that both the transit provider and Caltrans will take over the next two years to help the provider achieve compatibility. Learn about the Data Assessment process.

    Applicability

    These Guidelines pertain to public transit operations. GTFS effectively supports all modes of public transit: rail, bus, ferries, streetcars, subways, cable cars, trolleybuses, gondolas, and more. GTFS best represents public transit operations with both fixed routes and fixed schedules, though more flexible systems will be included through the upcoming GTFS-Flex extension.

    Overview

    This Guidelines document has four sections:

    1. Principles: the goals that shaped the Guidelines
    2. Data Process Checklist: a list of outcomes for transit providers to meet that will ensure their GTFS data is of high quality
    3. Tools and resources: an explanation of Caltrans GTFS Helpdesk and other resources available to help California transit providers meet these Guidelines
    4. Frequently asked questions, including many standard GTFS terms

    Principles

    These Guidelines were shaped by adopted transportation policy in California as well as the desire to realize a transportation network that:

    • Provides the public with complete, correct, and up-to-date information—including standardized schedule, service, fare, access, and geographic data—to help riders of any ability plan journeys—as is nearly ubiquitous in the maps and apps on mobile phones
    • Provides riders with real-time vehicle arrival and departure information for making efficient decisions along their journey
    • Makes information easy to use in any application by providing schedule and real-time GTFS data feeds that are both standardized and public
    • Pursues industry standardization in order to provide better coordination, service delivery, and clear information for the transit industry—providers as well as their vendors— in the future

    Data Process Checklist

    In order to adhere to the above principles, transit providers (including rail, bus, and ferry) shall deliver the following outcomes:

    Schedule data

    Schedule data helps transit riders understand when service is scheduled to run, and how to understand a network of providers. To achieve complete Schedule data, transit providers must:

    1. Publish GTFS Schedule (also known as GTFS Static) data at a stable URL from which it can be “fetched” automatically by trip-planning applications such as Google maps, Apple maps, transit.app.
    2. Publish the following files and fields included in the base GTFS Schedule specification and the GTFS Schedule Best Practices (version 1.0 or later):
      • Fares data using the Fares v2 format and applicable proposed files. This includes: fare_leg_rules, rider_categories, fare_containers, fare_products, and fare_capping.
      • Text-to-Speech for stop names that are pronounced incorrectly in most mobile applications.
      • Shapes.txt, with route shapes that do not inaccurately cut across buildings or roadways.
      • The wheelchair_boarding fields for both stops.txt and trips.txt
      • The Pathways extension for any stops described using the child/parent stop relationship. This is intended to include any named, dedicated transit facility, serving any mode where an uninformed first-time visitor could reasonably expect more than one level.
    3. Achieve a score of “passing” or “perfect” in all categories of the GTFS Grading Scheme version 1.
    4. Publish changes to the base schedule at least one week in advance of every service change.
    5. Produce no critical errors in the MobilityData GTFS Validator in the previous month, as reported at reports.calitp.org. “Critical” errors are those that impede or challenge the ability of transit riders to confidently plan or execute their journey. See List of Critical Validation Errors.

    Realtime data

    Realtime data give riders up-to-date information about the location of transit vehicles (including rail, bus, and ferry). In order to achieve complete GTFS-Realtime data, transit providers must:

    1. Publish all three versions of standard GTFS Realtime consistent with the GTFS Realtime Best Practices: Trip Updates, Vehicle Positions, and Alerts.
    2. Publish updates to Trip Updates and Vehicle Positions feeds at least once every 20 seconds.
    3. Publish information for at least 99% of the vehicles in service at all times.
    4. Ensure that 100% of trip_ids for planned trips are consistent between the GTFS Schedule and GTFS Realtime sources.
    5. Produce no critical errors in the Center for Urban Transportation Research (CUTR) GTFS Realtime Validator, as reported in the previous month at reports.calitp.org. “Critical” errors are those that impede or challenge the ability of transit riders to confidently plan or execute their journey. See List of Critical Validation Errors.

    Access to data

    Transit providers must minimize any barriers to riders’ ability to access accurate trip-planning data. They must do so in the following ways:

    1. Publish a link to all GTFS Schedule and all GTFS Realtime data feeds. Transit providers can either publish the GTFS data directly on their websites or refer to a regional partner where the data can be found. These local and regional websites must be in agreement on the canonical version of each provider’s GTFS data.
    2. Publish all GTFS and GTFS Realtime data feeds to both of the two larger global GTFS aggregators: transit.land and openmobilitydata.org.
    3. Identify an open license that allows commercial use. See Caltrans’ model language for examples, or read more about what makes a license open.
    4. If a provider chooses to require an API key to access GTFS Realtime feeds, it is reasonable and allowed to require users to register for a unique API key. API registration must incorporate:
      • Posting easily discoverable instructions to register for an API key on either the transit provider’s or a regional partner’s website.
      • Automating the registration process so that approval is not contingent on the applicant’s intended use.
      • Specifying terms of use for the API key, including recommended access rates and the process for reinstating an account that has exceeded rate limits.

    Technical contacts

    To ensure that consumers of GTFS data can report any potential data quality issues, transit providers should:

    1. Identify a specific technical contact who knows how to triage inquiries about GTFS. This contact could be, for example, staff at the transit provider or a vendor.
    2. Take care to reassure the public that the recommended contact is indeed an appropriate technical contact. This can be achieved in one of three ways:
      • Use a GTFS-specific email address, such as “gtfs@agency.org” or “support@GTFSvendor.org.”
      • Designate an individual who is knowledgeable about GTFS, such as “name@agency.org.”
      • On a transit provider’s website, it is possible to reassure the viewer that a general contact is appropriate for GTFS questions. For example: “Send your GTFS feedback to our customer support.” If this is explained on the website, the GTFS feed can refer to the same contact.
    3. Provide technical contacts in two locations:
      • Alongside the GTFS feeds on either their (or their regional partner’s) website.
      • Within the published GTFS Schedule dataset in the feed_contact_email field within the feed_info.txt file.

    Maintenance

    Transit providers should make a plan to keep GTFS data accurate and complete into the future. Have a specific, time-bound plan in place to meet and remain consistent with these Guidelines. This should include co-developing a Transit Data Improvement Strategy with Caltrans’ Division of Rail and Mass Transportation (DRMT).

    Guideline development process

    These Guidelines were developed by the California Integrated Travel Project (Cal-ITP) team at Caltrans. Version 1.0 was published in September 2020. A release candidate for this version 2.0 was published in June 2021. This document will be updated once a 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 Guideline edits 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 to the version number (e.g., from 2.0 to 2.1).

    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/
    4. GTFS Realtime 2.0 Best Practices: https://gtfs.mobilitydata.org/best-practices/gtfs-realtime

    Future GTFS extensions

    Caltrans anticipates adding the GTFS extensions listed in this section to the Guidelines once 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.
    • 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-Fares

    GTFS-Fares 2.0 significantly expands the fare-related functionality of GTFS, including rush-hour fares, fare containers (such as physical cards and apps that can store purchased fares), and multiple-fare products (such as weekly and monthly passes). Caltrans is in close coordination with the data producers and consumers (such as journey-planning maps and apps) that are advancing the adoption of this extension, and are confident enough in its progress to include it in this version of the GTFS Minimum Guidelines.

    Anticipated Adoption: Summer 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 that 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 adopted for stop_name, and proposals for other fields are awaiting adoption. Those other fields include:

    • Agency name
    • Route name (short name and long name)
    • Trip name
    • Headsign (trip and stop)

    Anticipated adoption: 2021

    Shared identifiers

    When one transit provider overlaps with another—for example, when multiple transit agencies serve the same train or bus station, or when systems offer interagency fare discounts—it would be helpful for the providers to describe that relationship.

    MobilityData is developing a Mobility Database that will create stable identifiers for items like shared infrastructure and agency IDs. These stable identifiers will serve as aliases and not replace any local transit provider identifiers (such as stop or route IDs).

    Anticipated adoption: 2021

    GTFS-Flex

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

    • Dial-a-ride/paratransit services
    • Transit services where a vehicle can deviate from a fixed route to pick up or drop off riders
    • Transit services where riders can board or alight anywhere within a zone

    Transit providers should begin including GTFS-Flex services as part of their GTFS feeds in order to support inclusion in trip-planning applications. For providers that wish to include demand-responsive transit ahead of Flex 2.0 adoption, the GTFS-ContinuousStops proposal has been adopted into core GTFS and is partially supported in some trip planning maps and applications already.

    Anticipated adoption: Spring 2022

    General On-Demand Feed Specification (GOFS)

    GOFS is an effort to expand the range of on-demand mobility services covered by GTFS and GTFS-Flex. The types of transportation intended to be covered by GOFS 1.0 include:

    • Private taxi services
    • Private transportation network companies (TNCs), such as Uber and Lyft
    • Demand-responsive transit services that would otherwise be covered by GTFS-Flex

    GOFS 1.0 extends supported use cases envisioned as part of GTFS-Flex to add:

    • Realtime service updates
    • Accurate pricing information, including booking trips via deep-linking

    Anticipated adoption: 2022

    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. In addition, the extension will allow transit providers to describe vehicle propulsion type (diesel, electric, etc.), which will enable statewide aggregation and reporting.

    Anticipated adoption: 2022

    Overview

    Caltrans maintains several resources to support transit providers in their efforts to meet these Guidelines.

    Data assessments

    How well does a transit provider meet the outcomes listed in the Data Process Checklist? Caltrans is available to formally assess this consistency on request by California transit providers. Caltrans staff are reviewing every California transit provider’s consistency with the checklist once a year and reaching out to each transit provider to share and discuss those findings. To proactively request an assessment, contact GTFSRT@dot.ca.gov.

    If transit providers would like support in resolving identified gaps, Caltrans provides technical assistance to create a Transit Data Improvement Strategy. A Transit Data Improvement Strategy:

    • Has a two-year planning horizon with clear annual milestones.
    • Articulates how the transit provider will meet the California Minimum GTFS Guidelines, naming any specific hurdles.
    • Defines which resources Caltrans will provide to help the provider overcome these specified hurdles.
    • Will be updated in 2022 while Caltrans evaluates next steps.

    Click here for more about the data assessment process.

    Products and services

    For California transit providers that do not currently have GTFS Schedule data, Caltrans offers technical assistance via a vendor to create and maintain this data on their behalf, at no cost to transit providers, through 2021.

    For California transit providers that do not currently have the hardware or software to create GTFS Realtime, Caltrans’ Cal-ITP offers GTFS Realtime as a Service (GRaaS), which, using ultra-low hardware costs and no software costs, produces GTFS Realtime data. The Cal-ITP team is available to support implementation at no cost to transit providers and can help support initial hardware acquisition. For more information, contact GTFSRT@dot.ca.gov.

    For other hardware and software that providers need in order to produce and maintain GTFS Schedule or GTFS Realtime, Cal-ITP invites providers to acquire these services through pre-negotiated, competitively bid contracts at camobilitymarketplace.org, as they become available.

    Click here for more information about Caltrans’ inventory of available technical services for GTFS.

    Transit Working Groups

    Cal-ITP hosts gatherings of transit agency staff around specific topics to facilitate the open exchange of questions and experiences. These groups meet online once a quarter. These sessions typically include a peer presentation on a topic selected by the participants in advance. Cal-ITP staff and consultants facilitate the meetings, present relevant updates on the Cal-ITP project, and document and integrate relevant issues that are raised into Cal-ITP's roadmap.

    Click here to learn more about the Transit Working Groups or contact hello@calitp.org to join.

    Helpdesk

    Have a specific or exploratory question about transit data or strategy development? Caltrans’ team of technical experts is available at no cost to advise and support California transit providers. Contact GTFSRT@dot.ca.gov to get started.

    Frequently Asked Questions

    What is GTFS?

    The General Transit Feed Specification (GTFS) is the global standard for describing transit schedules and operations for use by trip-planning applications. GTFS is used by thousands of agencies worldwide and is by far the most common data standard produced by U.S. transit agencies.

    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 according to the GTFS Extension Process and approval is facilitated by the independent nonprofit organization MobilityData.

    How do transit riders and the public "see" this GTFS data?

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

    • A consumer-facing application such as Google maps, Apple maps, or transit.app (through a web browser or phone interface)
    • Transit provider signage
    • Commercial displays (for example at coffee shops, offices, sports and events venues, and apartment buildings)

    California’s raw GTFS data can be seen:

    Why did Caltrans develop these Guidelines?

    Caltrans developed the California Minimum GTFS Guidelines to ensure that data for transit providers in California meets the needs of travelers, as well as those who plan, manage, and operate the transportation network, including fare payment and other services contracted by providers. The Guidelines provide a consistent minimum expectation to ensure that the transit network is understandable and accessible for people with all levels of ability.

    Does my organization need to follow the Guidelines?

    We recommend that transit providers follow these Guidelines in order to best serve the public by providing accurate, complete, and up-to-date transit information. Research shows that transit riders respond positively to high-quality transit information, both in terms of reducing perceived wait times and increasing ridership. See The Data Transit Riders Want, published by TransitCenter in 2018, for more information.

    Vendors with products and services that support consistency with the Guidelines are encouraged to participate in these Requests for Proposals.

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

    Encourage the department or vendor providing 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 the current data pipeline. This can include:

    • Identifying funding for equipment
    • Adding these Guidelines in future vendor contracts and procurements
    • Collecting and maintaining additional data
    • Updating website language

    See Tools and Resources for a list of specific offerings to help transit providers meet these Guidelines.

    What is a “stable URL?”

    A stable (or “static”) URL is one that doesn’t change. This is especially important for GTFS Schedule data because it assures data consumers that they can reliably access the latest version of data. When new GTFS data is posted in a different location, it’s not obvious that the data from the old location is now invalid, which can result in transit riders being given out-of-date information, or none at all.

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

    Providing a static URL for the most recent data does not prevent storage of historical GTFS data on websites 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.

    Can a local or regional government impose guidelines that are stricter than these Guidelines?

    Yes. Caltrans welcomes the California transit community to provide more information than is specified in these minimum Guidelines, as long as these additional or stricter requirements don’t conflict with or dilute these Guidelines.

    Can a provider’s GTFS feeds overlap?

    In order to meet the requirement of describing planned service changes at least one week into the future, subsequent GTFS updates could be published that overlap each other. This is supported by the GTFS standard and service_ids. Click here to read more about service_ids.

    How do I publish my GTFS data to aggregators?

    OpenMobilityData and TransitLand are the two largest and most stable feed repositories. Data consumers rely on these to find GTFS feeds for their applications, and being absent from these aggregators can preclude a transit provider from inclusion in maps and trip-planning applications. Transit providers and vendors can submit their feeds to these aggregators directly by following the instructions below.

    How do I publish my GTFS data to trip-planning applications?

    Once published, transit providers will want to get their GTFS data into popular trip-planning applications for the general public to discover and use. Each application has its own process, and key applications are listed below:

    How do I select an open data license?

    Agency GTFS data should be offered 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. See Model Website Language for more information.

    What are the GTFS and GTFS Realtime Best Practices?

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

    What does it mean to have my data validated?

    MobilityData maintains an open-source program that checks GTFS data for consistency with the rules of the GTFS standard. It checks for issues that can be automated, such as missing required fields and impossibly fast travel time between stops. The Center for Urban Transportation Research (CUTR) has also produced a validator for GTFS Realtime information.

    Both of these validators offer useful insights, but both require a high level of comfort running technical applications. While Caltrans is developing user-friendly interfaces to make these both easier to use, any California transit provider can email GTFSRT@dot.ca.gov to request that Caltrans run these validators on their data and share the results.

    How can I create Fares or Pathways data?

    These are both still relatively new additions to the GTFS standard, so there aren’t many tools to support them. The Metropolitan Transportation Commission (MTC) is providing access to these extensions to their local San Francisco Bay Area transit partners and at least one limited-functionality Pathways editor exists as of spring 2021. Transit providers should request this data from their GTFS vendors and contact GTFSRT@dot.ca.gov for more information.

    What does a Transit Data Assessment look like?

    To see how the Guidelines look in the context of a real transit provider, review this hypothetical assessment of Monterey-Salinas Transit.

    Where can I get more support?

    Caltrans is here to help transit providers understand and successfully implement the Guidelines. Email GTFSRT@dot.ca.gov to get started.