gtfs-scorecard

# GTFS Scorecard

> Daily, plain-language GTFS quality scorecards for small transit agencies:
> see the current grade, the three things to fix, and why each one matters.

[![CI](https://github.com/ChelseaKR/gtfs-scorecard/actions/workflows/ci.yml/badge.svg)](https://github.com/ChelseaKR/gtfs-scorecard/actions/workflows/ci.yml)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-GTFS%20Scorecard%20gate-2ea44f?logo=github)](https://github.com/marketplace/actions/gtfs-scorecard-gate)
[![Live site](https://img.shields.io/badge/live-gtfsscorecard.org-2ea44f)](https://gtfsscorecard.org)
[![Sponsor](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-ea4aaa?logo=githubsponsors)](https://github.com/sponsors/ChelseaKR)

[![GTFS Scorecard: plain-language GTFS quality and prioritized fixes](https://gtfsscorecard.org/og.png)](https://gtfsscorecard.org)

GTFS Scorecard is a daily data-quality service for small transit agencies and
the program staff, maintainers, and vendors who support them. It publishes
dated grades, prioritized fixes, history, program views, practitioner tools,
and open data. It does not implement a competing GTFS validator. Correctness
findings come from MobilityData's canonical validator.

## Quickstart

Requires Python 3.12+, [uv](https://docs.astral.sh/uv/), and Java 17+
(the validator jar is downloaded automatically on first run).

```sh
cd pipeline
uv sync
uv run scorecard run --all
```

This fetches today's snapshot of every current configured feed, validates and
scores it, and writes artifacts to `data/artifacts/<agency>/<date>.json` plus a
`latest.json` and a cross-agency `index.json`. Retired aliases are excluded
from the batch; an explicit historical rescore writes a dated record without
recreating mutable current files. Re-running a day is idempotent. Checks (from
the repo root; mirrors the CI gate):

```sh
make verify
```

### Run the web app locally

The frontend reads the JSON artifacts over HTTP. Serve the repo root and open
the page through `http://`, not by double-clicking the file:

```sh
cd ..            # repo root, so data/artifacts/ is reachable
python3 -m http.server 8000
# then open http://localhost:8000/web/index.html
```

Opening `web/index.html` as a `file://` URL leaves the page stuck on
"Loading scorecards…": browsers block ES module loading and `fetch` over
`file://`, so the app never runs. Any static server works; the only requirement
is that `data/artifacts/` sits one level above `web/`, which the
`../data/artifacts` fallback in `web/src/app.js` expects.

## Where it fits

GTFS Scorecard is the evidence and triage layer:

1. [Mobility Database](https://mobilitydatabase.org/) and
   [Transitland](https://www.transit.land/) help identify public feeds and
   their sources or versions.
2. The [MobilityData GTFS validator](https://github.com/MobilityData/gtfs-validator)
   supplies canonical specification findings.
3. An agency, vendor, editor, or support program changes and publishes the
   feed through its existing workflow.
4. A 90-day GTFS Scorecard pilot is testing the final handoff: link an accepted
   action to the intended feed, run a comparable recheck, and preserve the
   result.

The [California GTFS Quality Dashboard](https://reports.dds.dot.ca.gov/)
inspired the project's daily scorecard and support-program framing. GTFS
Scorecard is independent and is not an official compliance determination.

Pilot agencies: [Unitrans](https://unitrans.ucdavis.edu) (ASUCD / City of
Davis) and [Yolobus](https://yolobus.com) (Yolo County Transportation
District). Beyond the pilots, the registry contains more than 2,600 curated
feed records, mostly in the United States and Canada, plus reviewed canaries
across Europe, Asia-Pacific, and South America. Scoring is scheduled daily for
every registered feed, and the public status page reports the exact current
configured and published counts along with when the latest run completed. Read
the published total there rather than from this repository: automation stopped
committing generated data at the S3 cutover (see
[docs/follow-ups.md](docs/follow-ups.md)), so what git carries is a fallback
snapshot that moves only when it is deliberately re-materialized from the live
corpus (last refreshed 2026-08-07),
with more than 2,100 numeric scorecards published. CI can only gate the
snapshot figure, because `make verify` runs offline. A feed record is not
always a distinct transit agency: regional feeds and modal variants are counted
separately while the identity registry is reconciled. A record the Mobility
Database has retired in favor of another is no longer one of them: it keeps
its dated artifacts and redirects its old URL, and only its successor publishes
a current grade, so one agency does not carry two
(`docs/feed-supersessions.md`). That leaves the published count lower than it
was, and right.

**Live:** [gtfsscorecard.org](https://gtfsscorecard.org/) — with the latest
completed-run evidence at [gtfsscorecard.org/status](https://gtfsscorecard.org/status/).

**Status:** Beta. The public scorecards and daily evidence service are live.
The remediation workflow is being tested and is not yet a proven service.
Realtime quality is scored only when a usable realtime feed is configured and
measured; otherwise it is shown neutrally as not yet measured. Any agency can
be added through `registry/intake.yaml`.

## Use, adopt, or contribute

- **Check a feed:** browse
  [gtfsscorecard.org](https://gtfsscorecard.org/), or
  request a [one-off score](https://github.com/ChelseaKR/gtfs-scorecard/issues/new?template=score-a-feed.yml).
- **Track an agency:** use the
  [self-serve submission form](https://gtfsscorecard.org/submit.html), or follow
  the [repository walkthrough](docs/add-your-agency.md) to open a pull request.
- **Gate a feed in CI:** add the
  [GTFS Scorecard Marketplace Action](https://github.com/marketplace/actions/gtfs-scorecard-gate)
  to a feed repository.
- **Test what happens after the scorecard:** read
  [the remediation pilot request](https://github.com/ChelseaKR/gtfs-scorecard/issues/185)
  if you can take a finding through an accepted request and same-feed recheck.
- **Contribute:** choose a
  [bounded open issue](https://github.com/ChelseaKR/gtfs-scorecard/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
  or read [CONTRIBUTING.md](CONTRIBUTING.md). Feed corrections, accessibility
  review, and practitioner feedback are useful without changing scoring code.
- **Get help, or fund the work:** [SUPPORT.md](SUPPORT.md) is the front door for
  both. Scoring is free for every agency and stays that way; the
  [support page](https://gtfsscorecard.org/support/) explains what running the
  service costs, what sponsorship would pay for, and what it never buys.
- **Report on every agency you support:** the program rollups
  (`/program/<state>/`) are free; the paid
  [program report bundle](https://gtfsscorecard.org/bundle/) packages a branded
  board report per agency into one archive.

## What an agency gets

- An overall grade from the categories that can be measured: correctness,
  freshness, rider experience completeness, and, when available, realtime
  quality.
- "Top 3 things to fix", in plain language with effort hints. Findings are
  framed as fixes, never as failures.
- For U.S. agencies only, an NTD GTFS-readiness read (published, valid,
  current, and `agency_id` present) plus a neutral check of whether `agency_id`
  happens to equal the five-digit NTD ID. Equality is optional; RY2026 presence
  and the P-50 crosswalk are not.
- Trend history, one JSON artifact per agency per day.
- An embeddable grade badge (`<agency>/badge.svg`) the agency can put on its
  own developer page.

The scoring methodology, with citations to the California Transit Data
Guidelines v4.0 and the validator's rule taxonomy, is in
[docs/rubric.md](docs/rubric.md). Methodology changes are governed: a
validator-version bump must attach the shadow-run impact report from
`scorecard canary` before it lands (rubric.md, "Governed upgrades").
The grade, weights, thresholds, and fix order are GTFS Scorecard policy choices,
not an official MobilityData grade or a universal quality standard.
Feed sources and licenses are in
[docs/feeds.md](docs/feeds.md). Forward planning is split in two: the
infrastructure and scaling plan is in [docs/roadmap.md](docs/roadmap.md), and
what the product becomes for its users is in
[docs/product-roadmap.md](docs/product-roadmap.md).

## What's on the site

Each agency gets a scorecard page, plus three companion pages written for the
different seats at an agency check-in: a board one-pager
(`/agency/<id>/board/`), a call-prep brief (`/brief/`), and, when comparable
finding-clearance records exist, a clearance log (`/fixes/`). Around those sit:

- **Coverage views** — the coverage overview (`/pulse/`), most common problems
  (`/problems/`), realtime reliability (`/realtime/`), optional-feature
  adoption and accessibility data coverage (`/adoption/`), a consumer feature
  finder with translation-language and accessibility filters
  (`/app/#/?view=features`), and worldwide
  agency and route maps (`/map/`, `/routes/`). U.S.-specific NTD readiness
  (`/ntd/`) and equity (`/equity/`) stay available as regional modules.
- **Program pages** (`/program/<state>/`) for 46 states plus DC and named
  cohorts from [`rollups.yaml`](rollups.yaml), each with the fixes shared
  across the group.
- **Practitioner tools** — request a one-off score through GitHub or run it
  locally (`/try.html`), check a feed before publishing (`/check/`), compare two agencies (`/compare/`),
  query the dataset with SQL in the browser (`/query/`), and put feed quality
  in a vendor contract (`/procurement/`).
- **Board-ready outputs** — each agency has a printable one-pager; see the
  [live Unitrans example](https://gtfsscorecard.org/agency/unitrans/board/),