Installation

Install it from PyPI with UV, say, via uv add gtfs_kit.

Examples

In the Marimo notebook notebooks/examples.py.

Authors

• Alex Raichev (2019-09), maintainer

Documentation

The documentation is built via Sphinx from the source code in the docs directory then published to Codeberg Pages at araichev.codeberg.page/gtfs_kit_docs.

Conventions

• Throughout GTFS Kit, date means GTFS service date and is encoded as a YYYYMMDD string. In conformance with GTFS, times are HH:MM:SS service-day offsets that can exceed 24 hours. Time-series functions preserve those offsets instead of wrapping them modulo 24 hours. Their date column identifies the service date, while datetime can fall on a later calendar date. For example, 25:30:00 on date 20250101 becomes datetime 2025-01-02 01:30:00 and retains date 20250101. Route, stop, and network stats and timetables use the same date convention. See also gtfs_kit.trips.is_active_trip, which is used in gtfs_kit.routes.compute_route_stats, gtfs_kit.stops.compute_stop_stats, and gtfs_kit.miscellany.compute_network_stats.

• ‘DataFrame’ and ‘Series’ refer to Pandas DataFrame and Series objects, respectively.

• Aggregate service metrics distinguish no service from unknown distance. A group or time bin with no active service has zero distance, duration, and speed. If any contributing trip has unknown distance, aggregate service_distance and service_speed are NA while counts and service_duration remain available. This rule applies to route and network stats and time series, so results remain consistent across aggregation levels and time frequencies.

Notes

• This project’s development status is Alpha. I use GTFS Kit at my job and change it breakingly to suit my needs.

• This project uses semantic versioning.

• I aim for GTFS Kit to handle the current GTFS. In particular, i avoid handling GTFS extensions. That is the most reasonable scope boundary i can draw at present, given this project’s tiny budget. If you would like to fund this project to expand its scope, please email me.

• Thanks to MRCagney for periodically donating to this project.

• Constructive feedback and contributions are welcome. Please issue pull requests from a feature branch into the develop branch and include tests.

• GTFS time is measured relative to noon minus 12 hours, which can mess things up when crossing into daylight savings time. I don’t think this issue causes any bugs in GTFS Kit, but you and i have been warned. Thanks to user Github user derhuerst for bringing this to my attention in closed Issue 8.

• With release 10.0.0, i removed the validation module validators.py to avoid duplicating the work of what is now the canonical feed validator (written in Java).

• I might require Pandas 3 in the future to take advantage of its new features.

Maintainer Notes

• After pushing to master, update the published docs via uv run make -C docs publish-docs