mcpField
E
espn-api

espn-api

github.com/sejaldua数据与数据库12187 次安装28 周前更新
代码仓库

关于 espn-api

espn-api 是一项查询 ESPN 非官方、未公开文档的 JSON API 的技能，面向需要获取体育数据的开发者。它提供按数据类型选择接口、构造请求和解析响应的参考，并强调接口可能变更及稳健处理。

主要功能

  1. 01查询比分、排名和球队信息
  2. 02获取球员数据与比赛记录
  3. 03访问赔率、伤病和新闻
  4. 04参考联赛标识与接口目录
  5. 05处理响应结构和常见问题

适用场景

  1. 01获取指定日期的联赛比分
  2. 02查看球队名单或球员赛季数据
  3. 03查询比赛赔率和伤病报告
  4. 04编写带缓存与错误处理的 API 调用

MCP 相关

输入未说明该技能与 MCP 的关系。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/sejaldua/espn-api --skill espn-api

安装后在 Claude Code 中输入/espn-api确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

LICENSE
.gitignore
README.md
references/
league-slugs.md
endpoints.md
gotchas.md
response-schemas.md
scripts/
espn_fetch.sh
espn_fetch.py

详细介绍

ESPN Public API 技能

你擅长使用 ESPN 未公开文档的公共 JSON API 获取体育数据。这些 API 为 espn.com 和 ESPN 移动应用提供支持。无需身份验证，返回 JSON。

**重要：**这些 API 并非官方 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 域名。请根据数据需求选择：

域名基础 URL用途
Site APIhttps://site.api.espn.com/apis/site/v2/sports/{sport}/{league}/比分、球队、阵容、新闻、伤病、比赛摘要
Site API v2https://site.api.espn.com/apis/v2/sports/{sport}/{league}/仅排名（site/v2 路径返回的排名数据为占位内容）
Core API v2https://sports.core.api.espn.com/v2/sports/{sport}/leagues/{league}/运动员、详细数据、赔率、比赛实况、场馆、教练
Core API v3https://sports.core.api.espn.com/v3/sports/{sport}/{league}/丰富的运动员数据、领先者
Web API v3https://site.web.api.espn.com/apis/common/v3/sports/{sport}/{league}/球员赛季数据、比赛日志、拆分数据、排行榜
CDNhttps://cdn.espn.com/core/{league-abbrev}/完整比赛数据包（技术统计 + 比赛实况 + 胜率）。需要 ?xhr=1
Now APIhttps://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
seasontype1=季前赛，2=常规赛，3=季后赛，4=休赛期2
week周数1
limit每页结果数100
page页码1
groups分区 ID（大学体育）8（SEC）
xhrCDN 端点必需1
active筛选现役运动员true

赛季类型

类型值描述
季前赛1表演赛/季前赛
常规赛2常规赛
季后赛3季后赛
休赛期4休赛期

博彩服务商 ID

按服务商筛选赔率时：

服务商ID
Caesars38
FanDuel37
DraftKings41
BetMGM58
ESPN BET68
Bet3652000

编写代码

当用户想要编写调用 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 代码最佳实践
  • 始终设置超时（建议设为 30s）
  • 为不常变化的数据（球队、排名、阵容）实现缓存
  • 妥善处理 404（无效 ID、休赛期端点）
  • 对 429（速率限制）进行指数退避处理
  • 该 API 没有文档，因此访问嵌套字段前务必验证响应结构
  • 使用 User-Agent 标头标识你的应用

深入参考

评论

支持 Markdown