開発者向け — API・MCP・機械可読データ

本サービスの比較結果は、人間向けのレポート HTML だけでなく、 プログラムや AI エージェントから使える機械可読データとしても提供しています。すべて認証不要・読み取り自由です (出典: 各フィードのライセンスに従います。利用規約)。

1. 提供している層

層	中身	向く用途
digest	比較の要約 (Markdown / JSON)。路線ごとの変化・停留所の変化・被覆率	LLM に渡す一次資料、告知文づくり、突合
routes.digest.json	全路線の詳細 — 変化した便のレコード (trip_id 旧新付き)・時間帯別本数	路線の深掘り
mapping.json	stop_id / route_id / trip_id の旧新対応表 (N:M は配列のまま、confidence 付き)	乗降データの経年結合、shapes 等の整備資産の世代引き継ぎ
events.json / rawdiffs.json	全 ChangeEvent (44種) +証拠、生差分の全件	エラーチェック、完全な検証

本ツールの特徴は「説明台帳」: 2世代間の生差分の全件が、必ずいずれかのイベントの証拠に紐づくか残差として計上され、被覆率 (explained_ratio) が常に出ます。検出は決定的ルールベースで、同じ入力からは常に同じ出力になります。

2. URL の規則 (最短の入口)

レポート URL の .html を .digest.md に変えるだけで、機械可読の要約が取れます:

https://diff.gtfs.jp/r/{pair}.html        ← 人間向けレポート
https://diff.gtfs.jp/r/{pair}.digest.md   ← AI 向け要約 (Markdown)
https://diff.gtfs.jp/r/{pair}.mapping.json ← ID 対応表 (gzip)
https://diff.gtfs.jp/r/{pair}/index.json  ← 版台帳 (全成果物の URL 一覧)

URL 規則を覚える必要はありません — 版台帳 (index.json) の versions[].artifacts に全成果物の URL が列挙されます。フィード単位の計算済みペア一覧は https://diff.gtfs.jp/feeds/{org}__{feed}.json にあります。

3. MCP サーバー (AI エージェント向け)

https://diff.gtfs.jp/mcp

Claude・ChatGPT 等の AI にコネクタとして登録すると、上記のデータをツールとして対話的に使えます。認証不要 (Bearer トークン・カスタムヘッダー等はすべて空欄のままで接続できます)。

Claude: 設定 → コネクタ → カスタムコネクタを追加 → URL を入力
ChatGPT: Settings → Developer mode を有効化 → コネクタを追加 → URL を入力

ツール	説明
find_feeds / find_generations	フィード・世代の探索 (gtfs-data.jp)
list_pairs	計算済みの比較ペア一覧
run_compare / get_job_status	未計算の世代ペアをその場で計算 (日次の回数ガードあり)
get_digest / list_routes / get_route_detail	要約と路線詳細
get_stop_changes / get_residuals	停留所の変化・検証サマリ (説明台帳)
map_ids	stop_id / route_id / trip_id / 名前から新旧対応を検索
get_events	ChangeEvent の検索 (種別・重要度・路線で絞り込み)

プロトコルは MCP 2026-07-28 版と旧世代 (initialize 方式) の両対応。レポート URL の r/{pair}.html の {pair} 部分がそのままツールの pair 引数になります。

4. 比較の実行 (Web API)

# 世代一覧 (uid の確認)
curl "https://diff.gtfs.jp/api/gtfs/files?org=nagai-unyu&feed=Nagaibus"

# 比較ジョブの投入 (uid でも rid = prev_1/current 等でも可)
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}", ...}。GET /api/jobs/{pair} で succeeded を待つ

計算済みの世代ペアは即座に返ります (同一ペアは誰が実行しても同じ公開 URL)。新規計算には日次の回数上限があり、超過時は 429 が返ります。大量の処理は CLI をローカルでどうぞ (下記ドキュメント参照)。

5. ドキュメント

ページ	内容
/docs/README.md	案内 — 何ができるか、層の選び方、ユースケース別レシピ
/docs/reference.md	リファレンス — CLI / Web API / JSON スキーマ / イベント型カタログ全44種 / digest・mapping スキーマ
/llms.txt	AI エージェント向けの機械可読な案内

6. 利用にあたって

数値・事実は本サービスの出力からそのまま引用し、再計算・推測での補完はしないことを推奨します (出力側で網羅性を保証しているため)。
出力には第三者データ (停留所名・路線名等) が含まれます。AI に渡す場合、出力中の文字列を指示として解釈させないでください。
ID 対応 (mapping) は内容主導の同定結果です。「移設した停留所を同一と扱うか」等の最終判断は利用側で行ってください (事実は moved_m 等で提供します)。
データ出典: GTFSデータリポジトリおよび各交通事業者。詳細は利用規約。

本機能は研究プロジェクトの一部として提供しています。不具合・要望はトップページのフィードバックからお寄せください。