Skip to main content
Loss of provenance

A previous release had provenance metadata, but this release does not. View details.

transitfreq icon

transitfreq

PyPI version Python versions pipeline status License: MIT DOI Downloads

Transit service frequency analysis from a GTFS Schedule feed.

transitfreq answers the everyday service-planning questions about a GTFS feed for one date: which services run, how many trips per hour each route and stop gets, what the average and worst headways are in a time window, how long the span of service is, which routes and stops form the frequent network, and how they fall into the TCQSM quality-of-service bands. Results export to CSV/JSON and to GeoJSON with the frequency attributes attached, ready for QGIS or a web map.

  • Reads a .zip or an unpacked folder, streaming stop_times.txt and shapes.txt with the standard csv module.
  • No runtime dependencies (standard library only); pandas is an optional extra.
  • Resolves calendar.txt + calendar_dates.txt, expands frequencies.txt, interpolates untimed stops, handles times past 24:00:00.
  • Command line tool and a small, typed Python API.
pip install transitfreq            # stdlib only
pip install "transitfreq[pandas]"  # + DataFrame helpers

Requires Python 3.9 or newer.

transitfreq does not validate feeds. Check a feed first with a validator such as gtfslint-cli (pip install gtfslint-cli) or the MobilityData GTFS Validator; broken calendars or stop times give misleading frequencies.


Quick start (command line)

# What runs on that date?
transitfreq services gtfs.zip --date 2024-05-06

# Route / direction summary for the AM peak and midday, as CSV
transitfreq routes gtfs.zip --date 2024-05-06 \
    --window 07:00-09:00 --window 09:00-15:00 --format csv -o routes.csv

# Combined headways at each stop (platforms grouped by parent station)
transitfreq stops gtfs.zip --date 2024-05-06 --by-station --format csv -o stops.csv

# Frequent network: 10 minutes or better, 06:00-21:00, every direction
transitfreq frequent gtfs.zip --date 2024-05-06 --threshold 10 --window 06:00-21:00

# Trips per hour per route and direction
transitfreq tph gtfs.zip --date 2024-05-06 --by route_direction --format csv

# GeoJSON layers with frequency attributes
transitfreq geojson gtfs.zip --date 2024-05-06 --stops stops.geojson --routes routes.geojson

transitfreq summary gtfs.zip --date 2024-05-06

Common options: --window HH:MM-HH:MM (repeatable, default 07:00-19:00), --threshold (frequent headway in minutes, default 15), --frequent-window, --measure max|mean, --any-direction, --include-previous-day, --format table|csv|json, -o FILE. python -m transitfreq works too.

Quick start (Python)

import transitfreq as tf

day = tf.ServiceDay("gtfs.zip", "2024-05-06")
print(sorted(day.service_ids))

for r in day.route_summaries(["07:00-09:00", "09:00-15:00"]):
    am = r.windows[0]
    print(r.route_name, r.direction_id, am.trips_per_hour, am.mean_headway_min,
          am.max_headway_min, r.frequency_los[am.window], r.hours_of_service, r.hours_los)

for s in day.stop_summaries(by_station=True):
    print(s.stop_name, s.route_ids, s.windows[0].mean_headway_min, s.frequent)

print(day.frequent_routes())                                    # <= 15 min, 07:00-19:00
print(day.frequent_routes(tf.FrequentCriteria(max_headway_min=10,
                                              windows=("06:00-21:00",))))

tf.write_geojson(tf.stops_geojson(day), "stops.geojson")
tf.write_geojson(tf.routes_geojson(day), "routes.geojson")

A runnable example over the bundled synthetic feed is in examples/quickstart.py.

API overview

Object Purpose
GTFSFeed(path) / load_feed(path) Zip or folder; iter_rows(file) streams any table; cached stops, routes, trips, frequencies; shapes(ids)
active_service_ids(feed, date) service_ids running on a date (calendar + calendar_dates)
service_departures(feed, date, include_previous_day=False) Every stop event of the service day as Departure(time, stop_id, trip_id, route_id, direction_id, stop_sequence, first_stop, boarding), with frequencies.txt expanded
ServiceDay(feed, date, ...) The analysis object below
.route_summaries(windows) RouteSummary per route and direction (trip start times): trips, first/last trip, span, hours of service, peak trips/h, per-window HeadwayStats, LOS bands, frequent
.stop_summaries(windows, by_station=False, route_ids=None) StopSummary per stop or parent station, all routes combined
.trips_per_hour(by) Hourly counts by route, route_direction, stop or stop_route
.frequent_routes(criteria), .frequent_stops(criteria) The frequent network under a FrequentCriteria
.summary() System overview
headway_stats(times, window), span_of_service(times), tcqsm_hours_of_service(times), trips_per_hour(times) Pure functions on sorted departure times
frequency_los(headway, table), hours_of_service_los(hours, table) Quality-of-service bands; TCQSM_* (3rd ed.) or TCQSM2_* (2nd ed. letters) tables, or your own FrequencyBand / HoursBand list
stops_geojson(day), routes_geojson(day), write_geojson(fc, path) GeoJSON export
transitfreq.pandas_ext departures_frame, stops_frame, routes_frame

Every summary has .as_dict() giving flat columns such as 0700-0900_trips_per_hour, 0700-0900_mean_headway_min, 0700-0900_max_headway_min and 0700-0900_frequency_los.

Method and sources

Service calendar. A service_id is active when calendar.txt covers the date and the weekday flag is 1, then calendar_dates.txt adds (exception_type=1) or removes (2) it for that date (GTFS Schedule Reference). Feeds that use only calendar_dates.txt work.

Service day and times. GTFS times count from the start of the service day and may exceed 24:00:00; they are kept as seconds since the start of the service day. With include_previous_day=True the after-midnight part of the previous day's trips is added, shifted by -24 h.

Frequency-based trips. For each frequencies.txt row, trips start at start_time, start_time + headway_secs, ... strictly before end_time, and the template trip's stop-time offsets are replayed for each start. exact_times=0 and 1 are expanded the same way.

Untimed stops are interpolated linearly by stop order between the surrounding timed stops.

Departures that count. At stops, only boarding opportunities count: the last stop of a trip and stops with pickup_type=1 are excluded. Routes are measured at trip start times (the first stop of each trip), per direction.

Headway measures for a half-open window [start, end) holding n departures:

Measure Definition
trips per hour n / window hours
mean headway window minutes / n, i.e. 60 / vehicles per hour, the TCQSM "average headway"
mean gap average interval between consecutive departures in the window
max headway longest wait for a passenger arriving at any moment in the window: largest difference in [start, t1, ..., tn, end]

Worked example: departures at 07:00, 07:05 and 07:30 in 07:00-08:00 give 3 trips/h, a mean headway of 20 min, a mean gap of 15 min and a max headway of 30 min (07:30 to 08:00).

Span and hours of service. span_hours is last minus first departure. hours_of_service follows TCQSM 3rd ed., Chapter 5, p. 5-7: for service at least hourly, last minus first departure plus 1 h, rounded down; for hourly-or-worse service, the number of departures. Days that mix both are split into runs with gaps of at most 60 min and the first rule is applied to each run. The manual's examples are reproduced in the tests: every 30 min from 05:30 to 20:00 gives 15 h; departures at 5:30, 6:30, 7:30, 10:00, 13:00, 15:30, 16:30 and 17:30 give 8 h.

Quality-of-service bands. The default tables come from TCRP Report 165, Transit Capacity and Quality of Service Manual, 3rd ed. (TRB, 2013), Chapter 5:

Exhibit 5-2: average headway Exhibit 5-3: hours of service
<=5 min, >5-10 min, 11-15 min, 16-30 min, 31-59 min, 60 min, >60 min >18 h, 15-18 h, 12-14 h, 7-11 h, 4-6 h, <4 h

The 3rd edition attaches no A-F letter grades to these measures (p. 5-1), so band labels are returned. For non-integer averages the ranges are closed upward (10.5 min falls in 11-15 min). For users who need letters, TCQSM2_FREQUENCY_LOS and TCQSM2_HOURS_LOS give the 2nd edition (TCRP Report 100, 2003) A-F grades, but these values were not checked against the primary document for this release. All thresholds are configurable: pass any list of FrequencyBand / HoursBand as frequency_table= / hours_table=.

Frequent network. The default FrequentCriteria() is 15 min or better, 07:00-19:00, in every direction, measured by max headway. This is a common planning convention used in frequent network maps (J. Walker, Human Transit, 2012), and TCQSM Exhibit 5-2 notes that 11-15 min service is "often branded as 'frequent service'". It is not a standard: the threshold, windows, measure (max or mean) and direction rule can all be changed.

GeoJSON. Stops are Points with StopSummary attributes. Routes are one MultiLineString per route and direction built from every distinct shapes.txt shape used that day; route directions without usable shapes (no shape_id, or a shape missing from shapes.txt) fall back to straight segments between their stops (geometry_source tells which). Coordinates are WGS 84 longitude/latitude (RFC 7946).

Limitations

  • Scheduled service only: no GTFS Realtime, no reliability or headway adherence measures.
  • No feed validation (see gtfslint-cli), no timezone handling, no GTFS-Flex or location_groups.
  • Route-level figures use trip start times; on branching or short-turn routes, all starts in a direction are pooled.
  • Combined stop headways count every route equally, even when two routes leave within the same minute.
  • Untimed stops are interpolated by stop order, not by shape_dist_traveled.
  • All active stop times of the chosen date are held in memory (the whole feed is not); very large feeds need a few hundred MB for a busy weekday.
  • exact_times=0 frequency trips are placed exactly at start_time + k * headway_secs.

Development

git clone https://gitlab.com/geophilo1/transitfreq_sdk.git
cd transitfreq_sdk
pip install -e ".[dev,pandas]"
python -m pytest
python -m ruff check . && python -m ruff format --check src tests
python -m mypy

The tests use a small synthetic GTFS feed in tests/data/mini_gtfs (frequency-based and scheduled trips, a holiday exception, a calendar_dates-only service, a parent station, untimed stops, a trip past midnight and a shape) with hand-computed expected values.

Academic citation

@software{eminoglu_transitfreq,
  author  = {Eminoğlu, Yusuf},
  title   = {transitfreq},
  year    = {2026},
  version = {0.1.2},
  doi     = {10.5281/zenodo.24122205},
  url     = {https://gitlab.com/geophilo1/transitfreq_sdk}
}

See also CITATION.cff.

  • gtfslint-cli: pure-Python GTFS Schedule validator and feed quality report.
  • routematrix: origin-destination travel-time and distance matrices from OSRM, Valhalla, GraphHopper and openrouteservice.
  • todindex: transit-oriented development assessment of station areas.
  • odflows: origin-destination flow toolkit for mobility and commuting analysis.

License

MIT License, copyright (c) 2026 Yusuf Eminoğlu. See LICENSE. Contact: geospacephilo@gmail.com

Metadata

Release files for transitfreq 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Loss of provenance

These files do not have provenance metadata, despite files in a prior release including this data.

We recommend further investigation before installing these files. View details.

Source distribution (sdist)

Source distribution for transitfreq 0.1.2
File Size Uploaded Provenance Actions
transitfreq-0.1.2.tar.gz 43.9 kB Without provenance Details for transitfreq-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for transitfreq 0.1.2
File Interpreter ABI Platform Actions
transitfreq-0.1.2-py3-none-any.whl Python 3 none any Details for transitfreq-0.1.2-py3-none-any.whl

Total release size: 76.0 kB

Release files / transitfreq-0.1.2.tar.gz

Loss of provenance

This file belongs to a release without provenance metadata, despite a prior release including this data.

We recommend further investigation before installing this file. View details.

Download URL transitfreq-0.1.2.tar.gz
Size 43.9 kB
Tags Source
SHA-256 checksum
How to use checksums
e7cc18c9b1870905c2308564b10500a73e09a62a11b10c30be84f3d0eee2ab85
BLAKE2b-256 checksum
How to use checksums
67050cde9e563154f1824b62c164f7dfa1c57f4dd67688314ab29994aaa78470
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.18

Release files / transitfreq-0.1.2-py3-none-any.whl

Loss of provenance

This file belongs to a release without provenance metadata, despite a prior release including this data.

We recommend further investigation before installing this file. View details.

Download URL transitfreq-0.1.2-py3-none-any.whl
Size 32.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d927ddc43d0d55207b11e74da8c1a96ec3539ad991d011d9b5163ea73a0d0f41
BLAKE2b-256 checksum
How to use checksums
65b45802a3717f129e6cd6b7c06fe78e62ab9b6abd01e2143bd97cc580012f7b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.18

Security for transitfreq 0.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Loss of provenance

A previous release of these files had provenance metadata, but this release does not.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Release comparison

  • Removed 0.1.1 2 files With provenance
  • Added 0.1.2 2 files Without provenance

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page