espn-api

ESPN Public API スキル

ESPN の非公開ドキュメントのパブリック JSON API を使って、スポーツデータを取得するエキスパートです。これらの API は espn.com と ESPN モバイルアプリを支えています。認証は不要で、JSON を返します。

重要： これらは非公式で、ドキュメント化されていない API です。予告なく変更される可能性があります。リクエスト頻度に配慮し、可能な場合はキャッシュを実装し、エラーを適切に処理してください。

このスキルの使い方

1. ユーザーが必要としているものを特定します（スコア、順位表、選手の統計、オッズなど）
2. references/league-slugs.md のスラッグ一覧を使って、スポーツとリーグを特定します
3. references/endpoints.md から、適切な API ドメインとエンドポイントを選びます
4. URL を組み立てて、データを取得します
5. references/response-schemas.md のパターンを使って、JSON レスポンスを解析します
6. references/gotchas.md に記載されているよくある落とし穴に注意します

API ドメイン

ESPN API には 6 つのドメインがあります。必要なデータに応じて選択してください。

ドメイン	ベース URL	用途
Site API	https://site.api.espn.com/apis/site/v2/sports/{sport}/{league}/	スコア、チーム、ロースター、ニュース、負傷情報、試合の概要
Site API v2	https://site.api.espn.com/apis/v2/sports/{sport}/{league}/	順位表のみ（site/v2 のパスは順位表のスタブを返します）
Core API v2	https://sports.core.api.espn.com/v2/sports/{sport}/leagues/{league}/	選手、詳細な統計、オッズ、プレーごとのデータ、会場、コーチ
Core API v3	https://sports.core.api.espn.com/v3/sports/{sport}/{league}/	強化された選手データ、ランキング上位選手
Web API v3	https://site.web.api.espn.com/apis/common/v3/sports/{sport}/{league}/	選手のシーズン統計、試合記録、スプリット、ランキング
CDN	https://cdn.espn.com/core/{league-abbrev}/	試合の全データ（ボックススコア＋プレー＋勝利確率）。?xhr=1 が必要です
Now API	https://now.core.api.espn.com/v1/sports/news	リアルタイムのニュースフィード

クイックスタートの例

今日の全リーグのスコアを取得

curl "https://site.api.espn.com/apis/site/v2/sports/{sport}/{league}/scoreboard"
# Example: NBA scores today
curl "https://site.api.espn.com/apis/site/v2/sports/basketball/nba/scoreboard"
# Scores for a specific date
curl "https://site.api.espn.com/apis/site/v2/sports/basketball/nba/scoreboard?dates=20250315"

順位表を取得

# IMPORTANT: Use /apis/v2/ NOT /apis/site/v2/ (the latter returns a stub)
curl "https://site.api.espn.com/apis/v2/sports/basketball/nba/standings"
curl "https://site.api.espn.com/apis/v2/sports/football/nfl/standings"

全チームを取得

curl "https://site.api.espn.com/apis/site/v2/sports/basketball/nba/teams"

チームのロースターを取得

# Team IDs: look them up from the teams endpoint first
curl "https://site.api.espn.com/apis/site/v2/sports/basketball/nba/teams/13/roster"

試合の全概要を取得（ボックススコア＋プレー＋ランキング上位選手）

curl "https://site.api.espn.com/apis/site/v2/sports/basketball/nba/summary?event=401765432"

選手のシーズン統計を取得

# Uses the Web API v3 domain. Works for NFL, NBA, NHL, MLB.
curl "https://site.web.api.espn.com/apis/common/v3/sports/basketball/nba/athletes/3136776/stats"

選手の試合記録を取得

curl "https://site.web.api.espn.com/apis/common/v3/sports/basketball/nba/athletes/3136776/gamelog"

試合のベッティングオッズを取得

curl "https://sports.core.api.espn.com/v2/sports/basketball/leagues/nba/events/{eventId}/competitions/{eventId}/odds"

リーグ全体の負傷者レポートを取得

curl "https://site.api.espn.com/apis/site/v2/sports/football/nfl/injuries"

リアルタイムのニュースを取得

curl "https://now.core.api.espn.com/v1/sports/news?sport=basketball&league=nba&limit=20"

CDN 経由で試合の全データを取得（最も豊富なデータ）

# Returns gamepackageJSON with drives, plays, win probability, boxscore, odds
curl "https://cdn.espn.com/core/nba/game?xhr=1&gameId=401765432"
curl "https://cdn.espn.com/core/nfl/boxscore?xhr=1&gameId=401671793"

よく使うクエリパラメーター

パラメーター	説明	例
dates	日付フィルター（YYYYMMDD または範囲）	20250315 または 20250301-20250331
season	シーズンの年	2025
seasontype	1=プレシーズン、2=レギュラーシーズン、3=ポストシーズン、4=オフシーズン	2
week	週番号	1
limit	1 ページあたりの結果数	100
page	ページ番号	1
groups	カンファレンス ID（大学スポーツ）	8（SEC）
xhr	CDN エンドポイントで必須	1
active	現役の選手に絞り込む	true

シーズンの種類

種類	値	説明
プレシーズン	1	エキシビション／プレシーズンの試合
レギュラーシーズン	2	レギュラーシーズン
ポストシーズン	3	プレーオフ／ポストシーズン
オフシーズン	4	オフシーズン

ベッティングプロバイダー ID

プロバイダーでオッズを絞り込む場合：

プロバイダー	ID
Caesars	38
FanDuel	37
DraftKings	41
BetMGM	58
ESPN BET	68
Bet365	2000

コードの作成

ユーザーが ESPN API を呼び出すコードを作成したい場合：

Python（requests または httpx）

import requests

def get_nba_scoreboard(date=None):
    url = "https://site.api.espn.com/apis/site/v2/sports/basketball/nba/scoreboard"
    params = {}
    if date:
        params["dates"] = date  # YYYYMMDD format
    resp = requests.get(url, params=params, timeout=30)
    resp.raise_for_status()
    data = resp.json()
    return data["events"]

JavaScript/TypeScript（fetch）

async function getNBAScoreboard(date?: string) {
  const url = new URL("https://site.api.espn.com/apis/site/v2/sports/basketball/nba/scoreboard");
  if (date) url.searchParams.set("dates", date);
  const resp = await fetch(url.toString());
  if (!resp.ok) throw new Error(`ESPN API error: ${resp.status}`);
  const data = await resp.json();
  return data.events;
}

ESPN API コードのベストプラクティス

• 常にタイムアウトを設定してください（推奨：30 秒）。
• 頻繁には変更されないデータ（チーム、順位表、ロースター）にはキャッシュを実装してください。
• 404 が発生した場合（無効な ID、シーズンオフのエンドポイント）は適切に処理してください。
• 429（レート制限）が発生した場合は、指数バックオフで処理してください。
• API はドキュメント化されていないため、ネストされたフィールドにアクセスする前に、必ずレスポンスの形式を検証してください。
• アプリを識別できるように User-Agent ヘッダーを使用してください。

詳細なリファレンス

• すべてのエンドポイント一覧： references/endpoints.md
• すべてのスポーツおよびリーグのスラッグ： references/league-slugs.md
• JSON レスポンススキーマと例： references/response-schemas.md
• よくある落とし穴と注意点： references/gotchas.md
• Python の取得ヘルパー： scripts/espn_fetch.py
• Bash の取得ヘルパー： scripts/espn_fetch.sh