きっぷナビ 公開APIの使い方

きっぷナビは、乗車券・定期券・IC定期券の分割候補を検索するGET APIを公開しています。認証・APIキー・利用登録は不要です。サーバーや、HTTP取得が可能なAIツールから利用できます。ブラウザから別オリジンで呼ぶ場合のCORS対応は保証していません。

• OpenAPI 3.1仕様
• 正式駅名一覧（JSON）
• この説明のMarkdown版
• AI向け案内

APIが返すもの

応答は分割境界となる駅名の候補です。金額・節約額・全経由駅・時刻表・購入手続きは含みません。金額を知りたい場合は、計算画面で確認してください。回答に金額を推測して付け足さないでください。

以下は応答形式の説明用の例で、実際の計算結果ではありません。

{"normal":["東京","横浜"],"results":[["東京","蒲田","横浜"]]}

normalは指定した発駅と着駅です。resultsの各配列は、発駅・分割境界駅・着駅の順に並ぶ1つの候補です。上の例は東京→蒲田と蒲田→横浜に分割する1つの候補を表します。["東京","横浜"]なら分割なしの候補です。候補が複数あれば、それぞれ独立した候補として示してください。

駅名は完全一致が必要です

from・to・noSplitStationには、正式駅名一覧のnameをそのまま使ってください。APIは曖昧検索や駅名の表記補正をしません。全角・半角、括弧、英字や仮名の大小も区別します。from・toの前後に空白を付けないでください。noSplitStationの前後の空白・空値・重複の扱いは後述します。

• 中央線の大久保駅は（中）大久保です。大久保や(中)大久保では一致しません。
• 大久保駅には（中）大久保・（陽）大久保・（奥）大久保があります。路線・地域が不明なら利用者に確認してください。
• ＪＲ総持寺の英字は全角大文字です。JR総持寺とは異なります。
• 姉ケ崎は大きいケです。姉ヶ崎では一致しません。

一覧は分割検索画面と共通の駅データから生成します。nameがAPIへ渡す正式駅名、kanaが読みです。同名駅にはおおくぼ（東京都）のような地域の補足があるので、識別に使ってください。icPassAreaNameはIC定期券エリアの補助情報で、未設定の場合はnullです。掲載は全券種・全区間で計算できることを保証するものではありません。区間・券種によっては経路不成立になります。数値の駅IDや推測した別名を送らないでください。

エンドポイントとパラメーター

ベースURLはhttps://kippu-navi.com、メソッドはすべてGETです。

• /api/split-ticket：乗車券。from・toが必須です。
• /api/split-pass：定期券。from・to・monthsが必須です。
• /api/split-icpass：IC定期券。from・to・monthsが必須です。

monthsは定期券の有効期間（月）で、1・3・6のいずれかを指定します。

乗車券・定期券には任意のmaxSplits（0〜10）を指定できます。これは分割回数で、1なら最大2区間です。省略または0は無制限です。IC定期券は最大2区間（1分割）に固定され、maxSplitsを送っても無視されます。

任意のnoSplitStationは分割境界にしない駅です。複数指定する場合はnoSplitStation=駅名1&noSplitStation=駅名2のようにキーを繰り返します。公開APIでは値の前後の空白を除去し、空値と重複を取り除いてから計算します。駅名そのものは正式表記で指定してください。

呼び出し例

日本語や括弧はURLエンコードしてください。curlの--data-urlencode、JavaScriptのURLSearchParamsが利用できます。

curl --get 'https://kippu-navi.com/api/split-ticket' \
  --data-urlencode 'from=東京' --data-urlencode 'to=横浜'

curl --get 'https://kippu-navi.com/api/split-pass' \
  --data-urlencode 'from=東京' --data-urlencode 'to=横浜' \
  --data-urlencode 'months=3'

curl --get 'https://kippu-navi.com/api/split-icpass' \
  --data-urlencode 'from=東京' --data-urlencode 'to=横浜' \
  --data-urlencode 'months=6'

サーバー側JavaScriptでの例です。

const query = new URLSearchParams({ from: '東京', to: '横浜' });
const url = `https://kippu-navi.com/api/split-ticket?${query}`;
const response = await fetch(url);
if (!response.ok) throw new Error(`APIエラー: ${response.status}`);
const result = await response.json();
console.log(result.results);

エラー・利用上の注意

• 400：必須項目不足、不正な期間、存在しない駅名、同一の発着駅など。入力を直してください。
• 405：GET以外のメソッドです。
• 422：指定条件で経路が成立しないなどの計算条件エラーです。
• 429：Cloudflareのレートリミットです。Retry-Afterがあれば従い、時間を空けてください。
• 500・502・503：計算処理や転送の失敗、一時的な利用不可です。

アプリケーションのエラーは通常{"error":"説明"}ですが、CloudflareやプロキシのエラーはHTMLやテキストの場合もあります。HTTPステータスとContent-Typeを確認し、エラーを計算結果として扱わないでください。連続再試行や大量アクセスは避けてください。応答はキャッシュされる場合があり、可用性や即時更新を保証しません。

チャットAIから利用する手順

1. この説明と正式駅名一覧を取得してください。ツールにHTTP取得機能がなければ、呼び出したと装わず利用者へAPIリンク・計算画面を案内してください。
2. 利用者が示した路線・地域と、一覧のkanaに含まれる地域の補足を手がかりに、正式駅名に対応付けてください。例えば「中央線の大久保」は（中）大久保です。同名駅が複数あって絞れない場合は質問してください。Unicode正規化などで一覧の正式駅名を書き換えないでください。
3. 券種と定期期間を確認し、APIをGETで呼んでください。未指定の任意条件を推測して追加しないでください。
4. 成功応答に含まれる分割駅だけを説明し、参照したAPI URLと、金額を確認できる計算画面へのリンクを添えてください。

計算画面へのリンク

画面のパスは乗車券が/split/auto/ticket、定期券が/split/auto/pass、IC定期券が/split/auto/ic-passです。from・toと、指定したmaxSplits・noSplitStationを引き継いでください。

定期期間は画面URLもAPIもmonthsです。例えばAPIにmonths=3を指定した場合、画面にもmonths=3を付けます。

• 乗車券の計算画面
• 定期券3箇月の計算画面
• IC定期券6箇月の計算画面

チャットAIへの依頼例

例えばチャットAIには次のように依頼できます。

https://kippu-navi.com/developers/api.md を読み、正式駅名を確認して、東京から横浜の乗車券の分割候補をAPIで調べてください。実際の応答に基づいて答え、金額は推測しないでください。

文書の公開は、すべてのAIが自動的にAPIを認知・実行することを保証しません。利用するAIの検索・HTTP取得機能によって使い方が異なります。