公開GTFS APIを読み解く — 認証不要で出せる設計のキモはレスポンス本体にattributionを載せること

朝、https://api.transit.ls8h.com/ というエンドポイントを見つけて「なんで認証不要で公開できているのか？」と気になり、Claude Code に調査を投げた。返ってきた整理が想像以上に綺麗だったので、その場で公開記事にまとめさせた。記事自体は認証不要の公共交通 API、api.transit.ls8h.com の正体を読むとして残してある。

この記事はそっちのメタ振り返り。調査の途中でどう詰まったか、ユーザー（筆者本人）の質問で記事がどう厚くなっていったか、最終的に「公開APIの設計」について何を腹落ちできたかを書く。

出発点 — 「これなんで出せてるの？」

ブラウザの DevTools で fetch('https://api.transit.ls8h.com/api/v1/feeds') がそのまま 200 を返すのを見たときに最初に思ったのが、「これ、出して大丈夫なやつなのか？」だった。乗換案内系のAPIは商用の法人プランしか触ったことがなく、「個人が無料公開」は常識から外れていた。

Claude Code に投げた問いは1行だけ。

これってなんでオープンにできてるんですか？認証不要の公開APIで。ちょっとドキュメント漁って整理してください。

調査の詰まりポイント — WebFetch が 403 で弾かれた

最初に WebFetch でトップページを取りに行かせたら、403 で弾かれた。Cloudflare 側の bot 検出が効いていて、AI ユーザーエージェントが弾かれている形。

ここで「アクセスできませんでした」で止まらず、自分のグローバルルール（~/.claude/CLAUDE.md）に書いてある WebFetch 失敗時のフォールバック順序にそのまま進ませた。

WebFetch（403 で死亡）
r.jina.ai プロキシ経由でフルレンダリング → Markdown 取得（成功）
r.jina.ai 経由で OpenAPI JSON も直接取得（成功）
最後に ls8h.com 本体だけ Jina 経由で確認

この順序を CLAUDE.md に書いておいた価値が出た瞬間だった。「失敗したら次の手」をルールで固定しておくと、AIに「ダメでした」で止められない。

1回目の結論 — 4つの設計判断

OpenAPI と /feeds /operators を読んだあと、Claude Code が出してきた結論は次の4点だった。

GET のみ・書き込み一切なし — ユーザー単位の状態を持たなくていい
配信元は公的 GTFS オープンデータ — 一次データを囲い込む法的・経済的理由がない
ライセンス表記は feed / operator 単位でレスポンスに同梱 — クレジット表示義務を利用者に物理的に手渡す
CORS * でブラウザから直接叩かせる設計 — サーバー側プロキシ不要

これを聞いて自分の中で形が見えた瞬間、ふと口に出たのが「素材としてのオープンデータ（GTFS ZIP の山）を、経路検索できるAPIに化けさせた統合レイヤー」というフレーズだった。Claude Code に「その理解で正解です」と確認してもらって、この一行を記事の核に据えた。

ユーザーの追い質問が記事を厚くした

ここからが面白かった。最初の結論で記事をまとめさせたあと、自分の中で2つ詰めきれない点が残っていて、立て続けに追加質問を投げた。

質問1: 「レスポンス本体に attribution を載せて、何がどう解決されてるんですか？」

最初の記事では「ライセンス表記が同梱されている」とだけ書かれていて、それで何が嬉しいのかが抜けていた。質問を投げたら、Claude Code が4点に分解して返してきた。

クレジット表示義務の「伝達」が成立する — README に書くのと違って、レスポンスに乗せておけばコードから取り出せる
利用者がライセンス文言をハードコードしなくていい — 100社ぶんの attribution テーブルを利用者側で抱える必要がない
フィード追加・ライセンス改定が自動追従する — 利用者側のリビルドなしで反映される
「API 提供者がライセンス遵守の責任を果たした」状態を作れる — 火の粉が再配信者に飛んでくる可能性を設計上下げられる

ここを読んで腹落ちした。「attribution をレスポンスに埋める」は、単なる便利機能じゃなくて、ライセンス遵守の作業を利用者と API 提供者で分担できる構造を持っているということだった。フィードごとに異なるライセンス条件（CC BY、ODbL、各社独自）という、本来なら配信者を窒息させかねない問題を、構造で解いている。

質問2: 「これ出してる人の目的って何なんですかね」

これは個人プロジェクトの動機を探る雑談だったけど、答えが面白かった。

/api/v1/map/3d-scene と、/api/v1/guidance/plan の live, tracking, strategy パラメータがある。これはナビゲーションUIを持つフロントエンドを作る前提でないと出てこない設計。つまり「自分が使いたいクライアントアプリの裏側として作って、ついでに認証なしで叩けるようにした」というのが一番自然な読み方だった。

ls8h.com のトップに並んでいるアイコンジェネレータ、麻雀牌エンコードの雰囲気とも整合する。商売じゃなく自分の遊び場として置いてある。

質問3: 「他の人が使う場合の料金ってかかんないんでしたっけ？オープンにする方が実装は楽なんでしたっけ？」

ここで一番大きな腹落ちがあった。

運用コストの試算をさせると、月数千円〜数万円のインフラ代で回せる規模。GTFS 全国分でも数十 GB、Raptor や CSA でオンメモリ検索なら VPS 1〜2 台で完結する。

そして「オープンの方が実装が楽」という直感に反する話。クローズドにすると次のものが全部必要になる。

認証（ユーザーDB、サインアップUI、メール認証、APIキー発行）
課金（Stripe連携、サブスク管理、請求書、税務）
法務（利用規約、プライバシーポリシー、特定商取引法表記）
サポート（ログイン窓口、請求窓口、APIキー漏洩対応）
監視（ユーザー単位の使用量、不正検知）

これがAPIコアの実装と同じかそれ以上の重さになる。しかも本業の経路検索の改善には1ミリも寄与しない。

「作りたかったのは経路検索エンジンであって認証システムじゃない」 という個人開発者の本音が、設計に直接出ている。

学びの箇所

書き終わったあとに残った、自分の頭の整理。

1. 公開API＝危険、ではない

ずっと「APIをオープンにする＝認証付きAPIより危険」と漠然と思っていた。今日の調査で逆転した。

読み取り専用（GET only）＋ライセンスをレスポンス同梱という2点を満たせば、設計レベルで安全に公開できる。書き込みがなければユーザー単位の状態を持たなくていいし、ライセンス義務はレスポンスで伝達されるので「表記漏れの責任」を利用者に渡せる。

2. フィードごとに異なるライセンス条件は「レスポンス同梱」で構造的に解ける

GTFS フィードのライセンスはバラバラ。CC BY、ODbL、各社独自規約が混ざる。「READMEに全部書く」「利用者がハードコードする」だとフィード追加のたびに利用者全員が手を入れる羽目になる。

/api/v1/feeds で attribution を返す設計だと、フィードが増えても利用者側は何もしなくていい。これは API のメンテナビリティの話というより、ライセンス遵守という義務の所在を構造的に明確にする話だった。

3. オープンの方が個人開発者にとって運用が楽

今までクローズドの方が「ちゃんとしてる」感があると思っていたが、実態は逆。

オープンにすると認証・課金・法務・サポートが全部消える。代わりに必要なのは「無保証で出してます」の一行と、自腹でインフラ代を負担する覚悟だけ。

ただし「楽さ」を享受できるのは次の4条件が揃ったとき。

一次データがオープンデータ
読み取り専用
個人プロジェクト（収益化義務なし）
attribution 設計でライセンス義務を利用者に渡せる

1つでも欠けると話は変わる。「オープンが楽」は設計条件の上に成立する性質であって、無条件には成立しない。

メタな学び — 「ユーザーの追い質問が記事を完成させた」

最初の Claude Code の整理（4点の結論）は、それだけ読むと「綺麗にまとまっている」けど、自分の中に残る違和感は埋まっていなかった。

「attribution が載っている」← で何が嬉しいの？
「個人プロジェクト」← なんで出してるの？
「認証不要」← オープンにする方が本当に楽なの？

この3つの違和感を順番に質問として投げたから、最終的な公開記事は 「設計判断 → なぜそうしたか → 何が解決されているか → 個人開発者の経済合理性」 まで含む厚みになった。AI に最初の整理を出させたあと、自分の中の違和感を質問の形で投げ続ける作業を5往復ぐらいやった結果が、いまの公開記事になっている。

人間が判断する係、AI が実行・整理する係という構図がよく回った1本だった。整理力は AI に任せるとして、「何が腹落ちしていないか」を言語化するのは人間側の仕事だ、というのを改めて確認した。

参考: