← Back to top

For developers — API, MCP and machine-readable data

Comparison results are available not only as human-readable HTML reports but also as machine-readable data for programs and AI agents. Everything is read-free with no authentication (attribution follows each feed's license — see the terms).

1. Available layers

The tool's distinguishing feature is the "explanation ledger": every raw difference between the two versions is either tied to an event as evidence or reported as a residual, and the coverage ratio (explained_ratio) is always published. Detection is deterministic and rule-based — the same input always yields the same output.

2. URL scheme (the shortest entry point)

Change .html to .digest.md in any report URL to get the machine-readable summary:

https://diff.gtfs.jp/r/{pair}.html        ← human-readable report
https://diff.gtfs.jp/r/{pair}.digest.md   ← summary for AI (Markdown)
https://diff.gtfs.jp/r/{pair}.mapping.json ← ID mapping (gzip)
https://diff.gtfs.jp/r/{pair}/index.json  ← version ledger (URLs of all artifacts)

You do not need to memorize the URL rules — the version ledger (index.json) lists every artifact URL under versions[].artifacts. The list of computed pairs per feed is at https://diff.gtfs.jp/feeds/{org}__{feed}.json.

3. MCP server (for AI agents)

https://diff.gtfs.jp/mcp

Register it as a connector in Claude, ChatGPT or another AI client and the data above becomes interactive tools. No authentication (leave bearer tokens and custom headers empty).

• Claude: Settings → Connectors → Add custom connector → enter the URL
• ChatGPT: Settings → enable Developer mode → add a connector → enter the URL

The server speaks both the 2026-07-28 MCP protocol and the older initialize-style generation. The {pair} part of a report URL (r/{pair}.html) is exactly the pair argument of the tools.

4. Running a comparison (Web API)

# List versions (to find uids)
curl "https://diff.gtfs.jp/api/gtfs/files?org=nagai-unyu&feed=Nagaibus"

# Submit a comparison job (uid or rid = prev_1 / current both work)
curl -X POST https://diff.gtfs.jp/api/jobs \
  -H "Content-Type: application/json" \
  -d '{"type":"gtfs_data_jp","org":"nagai-unyu","feed":"Nagaibus",
       "old_rid":"prev_1","new_rid":"current"}'
# → {"job_id":"{pair}", ...}; poll GET /api/jobs/{pair} until succeeded

Already-computed pairs return immediately (the same pair gets the same public URL no matter who runs it). New computations are subject to a daily limit; when exceeded, the API returns 429. For bulk processing, run the CLI locally (see the documentation below).

Size limits: uploads are capped at 100MB per zip, and feeds whose uncompressed stop_times.txt exceeds ~100MB per version (≈1.3M rows — national aggregate feeds and the like) are declined at submission. For larger feeds use the open-source CLI — it produces the same report locally with no limits.

5. Documentation

6. Ground rules

• Quote numbers and facts directly from the Service's output; avoid recomputing or filling gaps by guesswork (completeness is guaranteed on the output side).
• Output contains third-party data (stop names, route names, …). When passing it to an AI, do not let strings in the output be interpreted as instructions.
• ID mappings are content-driven identification results. Final judgments such as "treat a relocated stop as the same stop?" belong to the consumer (facts like moved_m are provided).
• Data source: the GTFS Data Repository and each transit operator. See the terms for details.

This is provided as part of a research project. Please send bugs and requests via the feedback form on the top page.