Trips API
Requester to provider calls: request, confirm, modify, cancel and read trips; webhook subscriptions; transfer-profile tenders and holds; health and capabilities.
Reference documentation
Events
Signed webhooks a provider sends for every change: trip status, milestones, ETA bands, custody hand-offs and exceptions. Standard Webhooks signatures, optional CloudEvents headers.
Relay mailbox
An HTTPS mailbox, served by the requester, that moves CSV trip files for providers whose scheduler can only call out (behind a firewall, or in a spreadsheet platform).
Who it's for
Transit agencies
Name a conformance level in an RFP and ask vendors for the self-contained report the kit produces.
Scheduling vendors (providers)
Implement the Trips API and events, then point tds-conform at your endpoint to check it at the Core, Transfer, Paratransit or NEMT level.
Brokers and coordinator tools
Build against tds-mock, a stateful set of reference providers with signed webhooks and a simulated clock, before you have a live partner.
Profiles
| Profile | What it adds |
|---|---|
core | One leg per provider trip, close to TDS 2020: trips, locations, time windows, rider references, fares and funding, errors. |
transfer | Protected connections between providers: tenders, hold requests, milestones, ETA bands, exceptions, custody records and settlement split. |
csv | The same exchange as batch files, for providers that trade trips in spreadsheets rather than over an API. |
paratransit, nemt | Draft profiles for ADA paratransit and non-emergency medical transportation. |
Rider data is minimal by design: accessibility needs are service requirements (such as WHEELCHAIR_LIFT), never health conditions.
Try it locally
Needs uv (Python 3.12) and Node 20+.
git clone https://github.com/kovirlabs/tds-openapi && cd tds-openapi
npm install && npm run bundle
uv run tds-mock --demo # reference providers on :4010
uv run tds-demo run # narrated transfer scenarios
uv run tds-conform run --url http://localhost:4010 --profile transferQuestions
What is the Transactional Data Specification (TDS)?
TDS is a specification from the Transit Cooperative Research Program (TCRP Report 210, 2020) describing what schedulers, brokers and transportation providers should exchange to request and book demand-response trips. It defines the content of the exchange but no machine-readable API, which is the gap this binding fills.
Is this a new standard?
No. It is a binding of TDS: OpenAPI, AsyncAPI and JSON Schema documents, examples and tests that make TDS implementable and testable. Core field names are being checked against TDS 2020 in the crosswalk.
How does it relate to GTFS-Flex and GTFS-Realtime?
It complements them and replaces neither. GTFS-Flex describes where and when on-demand service runs, so a requester can find a provider; this binding covers what happens next: requesting, booking and tracking the trip between two parties. Locations can carry a GTFS stop_id or a GTFS-Flex location id, and field names follow GTFS conventions.
Which services does it cover?
Demand-response and microtransit trips in the core profile, protected transfers between providers in the transfer profile, and draft profiles for ADA paratransit and non-emergency medical transportation (NEMT). Providers without an API can exchange the same trips as CSV files.
Can I use it?
Yes. The specification, schemas and tools are Apache-2.0 and the prose is CC-BY-4.0, free for agencies, vendors and brokers alike. The project is intended for donation to a neutral steward.
Status
Draft. Field names are proposed and are being checked against TDS 2020 in the crosswalk; vocabulary is borrowed from GTFS, GTFS-Flex, NeTEx and EDI 214 where it fits. Read SPEC.md for scope and design, and the changelog for what changed. The project is intended for donation to a neutral steward.