Draft California Minimum GTFS Guidelines
**These guidelines are currently in draft format and will be updated in August 2020 based on feedback. Provide your feedback at: email@example.com by July 21, 2020.**
Table of Contents
The California Minimum General Transit Feed Specification (GTFS) Guidelines help ensure that data for transit operators in the State meets the needs of the travellers as well as planners and operators to manage and operate the transportation network.
These Guidelines reference pre-existing data standards and best-practices documentation to avoid placing additional burden on transit agencies. They were developed as part of the California Integrated Travel Program (Cal-ITP) dedicated to making travel simpler and cost-effective for all.
The Guidelines are an agency commitment to the following principles, which should be reflected in agency processes consistent with the Data Process Checklist:
- Provide the public accurate information in order to plan journeys for any ability; We provide standardized schedule, service, fare, access and geographic data that is complete, correct, and up-to-date.
- Provide riders information for making efficient decisions along their journey by providing riders accurate information about vehicle arrivals.
- Make our information easy-to-use in any application by providing standardized and public static and realtime GTFS data feeds.
- Pursue industry standardization in order to provide better coordination and service delivery in the future.
In order to adhere to the above principles, transit agencies shall follow processes that are consistent with the following checklist:
- Publish static GTFS data feeds that conform to GTFS, includes shapes.txt, and implements all recommendations made in the GTFS Best Practices for all routes open to the general public that it is responsible for.
- Publish GTFS-Realtime 2.0 Vehicle Positions, Trip Updates, and Alerts feeds for every fixed-route in the agency’s officially-published static GTFS data feed. Real-time vehicle information should be updated every 20 seconds or faster.
- Publish GTFS-pathways for infrastructure operated by the agency with stairs, escalators, elevators or other important accessibility considerations.
- Publish GTFS and GTFS-Realtime 2.0 feeds at static fetch urls.
- Describe planned service changes in the static GTFS feed when they are known in advance. Publish a static GTFS feed update at least one week ahead of service updates to provide time for engaging with feedback from apps and developers.
- GTFS and GTFS-Realtime data is offered without signing an extensive legal agreement, preferably under an open data license.
- Make Agency GTFS and GTFS-Realtime data feeds available on the feed aggregators https://transit.land/ and https://openmobilitydata.org.
- GTFS-Realtime APIs should have an uptime of greater than 99%.
- Publish a single point of contact for GTFS data on the agency's website in the feed info component of GTFS as well as offer a way for data consumers to register with the agency so that they can be easily reached.
- Maintain a process for tracking and improving accuracy of technology systems and revisiting best practices and guidelines.
- Shapes.txt http://gtfs.org/reference/static#shapestxt
- Pathways.txt http://gtfs.org/reference/static/#pathwaystxt
Why did Caltrans develop the Guidelines?
Caltrans developed the Guidelines to help ensure that data for transit operators in the State meets the needs of the travellers as well as planners and system managers to 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 agency need to follow the Guidelines?
We recommend that all agencies follow these Guidelines in order to best serve the public good by providing accurate, complete and up-to-date transit information.
How do transit riders “see” all the data that agencies 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),
- agency signage, and
- commercial displays (for example at coffee shops, offices, and apartment buildings).
The Guidelines are currently in draft stage through July 21, 2020. We welcome your feedback on the draft Guidelines via email to: firstname.lastname@example.org
We anticipate finalizing the Guidelines by August 2020 and updating them on an annual basis henceforth. Annual updates will be driven by advances in the adopted GTFS specification.
GTFS specification and best practices assistance
Caltrans, on behalf of Agencies within California, has a subscription with MobilityData IO to serve as a limited technical resource about the GTFS specification itself as well as best practices. The quickest way to get assistance is to join the MobilityData IO chat on Slack. To join the Slack community, sign up at https://mobilitydata-io.herokuapp.com. To ask a question via email, please contact email@example.com.
Caltrans, as part of the California Integrated Travel Project, has been assembling small groups of staff at similar-sized agencies to discuss their technology stacks. Please let us know if you would like to participate at firstname.lastname@example.org.
Selecting and implementing a data license
If possible, agency GTFS data should be offered under the latest Creative Commons Attributions license (currently CC-BY 3.0), which is consistent with the license required by the National Transit Map. Other “attribution” licenses are also practical; however, “share-alike” type licenses limit the use of the data by some user applications and should be avoided.
Implementing static URLs
Static URLs for your GTFS and GTFS-realtime feeds are critical in order to enable user-facing applications as well as the general public to always know where to go to find the latest information. Changing the URL each time your GTFS data is updated may cause your agency’s information to disappear from user-facing applications.
The GTFS Best Practices provide guidance on the recommended practice of hosting the GTFS data on the agency website. A consistent link to cloud storage or an FTP location would also satisfy the Guidelines, and as a last resort, posting the feeds each time they change to https://openmobilitydata.org 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.
Representing occupancy in response to COVID-19
Agencies may choose to represent the level of vehicle crowding using the experimental field OccupancyStatus in GTFS-realtime. In response to COVID-19 social distancing, MobilityData has provided guidance about how to use this field – limiting the values to:
- Many seats available
- Few seats available
Several consumer facility applications are able to display this value to riders so that they are able to better-plan their transit trips. Agencies who want help understanding what it would take for their systems to provide occupancy on a real-time basis should contact email@example.com.
There is also an open question as to whether to standardize on the experimental occupancy_percentage field or continue using OccupancyStatus. Few producers are currently providing occupancy data and practice to represent occupancy is in a state of evolution.
Data consumer registration
If an agency doesn’t already have a contact database, customer relationship management (CRM) software or an existing way to manage stakeholders, there are a number of freely-available lightweight services that can add an email signup to your agency’s website.
MobilityData is developing a canonical GTFS validator which 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 many more validation checks.
The Center for Urban Transportation Research (CUTR) at University of South Florida (USF) has 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 process more transparent.
Real-time system best practices
At this time, no official GTFS-realtime best practices have been published. There are some resources that can help agencies define best-practices in real-times system specifications:
- MobilityData maintains a working document for real-time systems requirements that can be used for procurement in order to meet several of the guidelines pertaining to GTFS-realtime.
- Oregon DOT’s Real-time Transit Information Whitepaper contains a useful overview of real-time system components, operations, procurement options, and recommended specifications.
In order to provide a concrete example of what the Guidelines look like at a real agency, we have done a hypothetical assessment of Monterey-Salinas Transit.
We’re here to help you understand and successfully implement the Guidelines. Email us at firstname.lastname@example.org if you are having financial or technical difficulties implementing the Guidelines and we will try and help.
We anticipate adding the following extensions to the Guidelines when they are officially adopted into the official GTFS definition.
Flex 2.0, which describes “flexible” or “demand responsive” transit – any transit service where riders do not board or alight 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 pickup or drop off riders, and
- Transit services where riders can board or alight anywhere within a zone.
Flex 2.0, when adopted, will be required as part of the Guidelines for any Agency who operates demand-responsive transit.
For agencies who 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-ContinuousStopsGTFS-Flex v is currently supported in OpenTripPlanner.
- GTFS-ContinuousStops Proposal: https://bit.ly/gtfs-continuous-stops
- GTFS-Flex v1: https://gtfsflex.com
Anticipated Adoption: 2021
GTFS-fares 2.0, which significantly expands the fare related functionality of GTFS including rush hour fares, fare containers, and multiple fare products.GTFS-fares 2.0, when adopted, will be required as part of the guidelines for all agencies with fares
Anticipated Adoption: Early 2021
GTFS-vehicles encodes transit vehicle characteristics such as seating capacity, bike capacity and various accessibility-related attributes.
GTFS-vehicles, when adopted, will be required as part of the Guidelines for all agencies with fleets that are not able to represent their accessibility via wheelchair at the trip or stop level.
Anticipated Adoption: Late 2020
GTFS-ServicesChanges fills a gap between schedule changes that occur between short notice (less than an hour) and those that are known in advance (more than one week). This is especially useful when service is operated in response to events such as sporting events where the end time is not necessarily known in advance.
GTFS-Service Changes, when adopted, will be recommended for all agencies with service that cannot be represented by the current static and real-time update frequencies.
GTFS-ServiceChanges will likely be adopted incrementally, like many other proposed extensions. Currently there is a proposal open for discussion to implement a subset of GTFS-ServiceChanges, “Support DUPLICATED trips in GTFS-RT” (Issue #221).
Anticipated Adoption: Incremental
Shared Infrastructure Identifiers
MobilityData is developing a Mobility Database (working title) that will create stable identifiers for transit infrastructure that is shared between feeds.
Where relevant and feasible, infrastructure (i.e. stations, pathways) that is shared among agencies with separate GTFS feeds shall include external identifiers to shared infrastructure in Mobility Database.
Anticipated Adoption: 2021