cricket-data

クリケットデータ（ESPN + Cricsheet）

クエリを作成する前に、エンドポイント、ID の規則、データの形式について references/api-reference.md を参照してください。Cricsheet の大会コードについては、references/competitions.md を参照してください。

クイックスタート

CLI を優先してください。Python のインポートパスに関する問題を回避できます。バックエンドは ESPN（ほぼリアルタイム）と Cricsheet（過去データ）の 2 つです。

# ESPN backend (live-ish) — discover series first, then use its numeric ID
sports-skills cricket get_series
sports-skills cricket get_scoreboard --series_id=8048
sports-skills cricket get_standings --series_id=8048
sports-skills cricket get_game_summary --series_id=8048 --event_id=1535465
sports-skills cricket get_news --series_id=8048

# Cricsheet backend (historical, completed matches) — uses letter codes
sports-skills cricket get_competitions
sports-skills cricket get_matches --competition=ipl --season=2026
sports-skills cricket get_match_deliveries --competition=ipl --match_id=1473508
sports-skills cricket get_player_stats --competition=ipl --player="V Kohli"
sports-skills cricket find_player --name=kohli

重要：クエリを実行する前に

重要：データエンドポイントを呼び出す前に、次の点を確認してください。

• ESPN のシリーズ ID はリーグ単位ではなく、シリーズ単位です。 必ず最初に get_series で確認してください。定期開催の大会では、シーズンごとに ID が変わります（例：IPL はシーズンごとに異なる ID です）。ID をハードコードしないでください。例にある 8048 は説明用であり、固定値ではありません。
• ID の体系は 2 種類あります。 get_series は ESPN ID（ライブ、数値。例：8048）を返します。get_competitions は Cricsheet コード（過去データ、英字コード。例：ipl）を返します。両者に関連性はありませんが、試合単位では例外です。Cricsheet の match_id は ESPNcricinfo の試合 ID と同じため、2 つのバックエンドを結び付けることができます。
• Cricsheet が対象とするのは終了済みの試合のみです（試合終了後、およそ 1 日遅れで反映されます）。ライブの試合や今後の試合には、ESPN のコマンド（get_scoreboard、get_series）を使用してください。
• get_player_stats には Cricsheet での正確な選手名の表記が必要です（例："Virat Kohli" ではなく "V Kohli"）。先に find_player で表記を確認してください。
• ICC ランキングはありません（v1 の制約により、無料の情報源がありません）。シリーズの順位表は get_standings で取得できますが、二国間ツアーの多くは空です（順位表を公開しているのはリーグやグループ形式の大会のみです）。
• 大会ごとに、Cricsheet への初回呼び出し時には zip をダウンロードします。 テスト、ODI、IPL などの大規模な大会では数十 MB になります。zip は ~/.cache/sports-skills/cricsheet/ に 24 時間キャッシュされるため、同じ日の 2 回目以降の呼び出しは高速です。

エージェントは scripts/validate_params.sh を実行して、クエリを実行する前に --competition、--series_id、--date を検証できます。

コマンド

ESPN バックエンド（ほぼリアルタイム）

コマンド	必須パラメーター	説明
get_series	—	現在開催中のクリケットシリーズを、ESPN シリーズ ID とライブイベントとともに一覧表示します
get_scoreboard	series_id（date は任意）	シリーズの試合、スコア、状況を表示します
get_standings	series_id	シリーズの順位表を表示します（二国間ツアーの多くは空です）
get_game_summary	event_id、series_id（開催中のシリーズでは任意）	試合の詳細：ロースター、リーダー、試合カード、各イニングのスコアカード、会場情報
get_news	series_id	シリーズのニュース記事を表示します

Cricsheet バックエンド（過去データ、ODC-BY 1.0）

コマンド	必須パラメーター	説明
get_competitions	—	Cricsheet の大会コードを一覧表示します
get_matches	competition（season は任意）	大会の終了済み試合を新しい順に表示します
get_match_deliveries	competition、match_id（innings は任意）	終了済み試合の投球ごとのデータを表示します
get_player_stats	competition、player（season は任意）	選手の打撃と投球の集計統計を表示します
find_player	name	Cricsheet の選手レジストリを検索し、ESPNcricinfo ID との対応を返します

日付には YYYYMMDD または YYYY-MM-DD を指定できます。season は開始年です（例：2020 を指定すると、Cricsheet の "2020/21" に一致します）。パラメーターと戻り値の形式の詳細については、references/api-reference.md を参照してください。

ワークフロー

ライブまたは最近のシリーズを確認する

1. get_series → シリーズを選び、その series_id を確認します。
2. get_scoreboard --series_id=<id> → 試合を状況とスコアとともに表示します。
3. 1 試合の詳細を確認するには、get_game_summary --series_id=<id> --event_id=<id> を実行します。

順位表（リーグ大会）

1. get_series → 大会の series_id を確認します。
2. get_standings --series_id=<id> を実行します。結果が空の場合は、順位表が公開されていない二国間ツアーです。

過去の選手統計

1. find_player --name=<substring> → name の正確な表記を確認します。
2. get_player_stats --competition=<code> --player="<exact name>" を実行します（--season は任意です）。

投球ごとの履歴

1. get_matches --competition=<code> [--season=<year>] → match_id を特定します。
2. get_match_deliveries --competition=<code> --match_id=<id> [--innings=N]。

クリケットニュース

クリケットニュースはシリーズ単位であり、全体向けのフィードはありません。

1. get_series → 該当するシリーズを選び、series_id を控えます。
2. get_news --series_id=<id> → 記事を提示します。

存在しないコマンド — 絶対に呼び出さないでください

• get_player / get_player_info — 存在しません。名前を特定するには find_player を使い、キャリア成績を取得するには get_player_stats を使います。
• get_match — 存在しません。過去の試合一覧には get_matches、ESPN の特定の試合の詳細には get_game_summary を使います。
• get_rankings — 存在しません。無料で利用できる ICC ランキングのデータソースはありません（v1 の制限事項）。
• get_teams / get_team_roster — 存在しません。ロスターは get_game_summary に含まれています。
• get_play_by_play — 存在しません。完了した試合の投球ごとのデータには get_match_deliveries を使います。

上記の Commands テーブルに記載されていないコマンドは存在しません。

帰属表示

Cricsheet のデータは ODC-BY 1.0 ライセンスで提供されています。Cricsheet のすべてのレスポンスには attribution フィールド（"Data from Cricsheet (cricsheet.org), ODC-BY 1.0"）が含まれています。データを再公開する際は、この帰属表示文字列をそのまま保持してください。