tennis-data

网球数据（ATP + WTA）

编写查询前，请先查阅 references/api-reference.md，了解端点、ID 约定和数据结构。

快速开始

优先使用 CLI，避免 Python 导入路径问题：

sports-skills tennis get_scoreboard --tour=atp
sports-skills tennis get_rankings --tour=wta
sports-skills tennis get_calendar --tour=atp --year=2026
sports-skills tennis get_wta_entry_list --tournament_id=901 --year=2025
sports-skills tennis get_wta_player_results --player_id=320760 --year=2025 --limit=10

关键：执行任何查询前

关键：调用任何数据端点前，请确认：

• 已指定 tour 参数（atp 或 wta）——没有默认值。
• 年份根据系统提示中的 currentDate 推导——不要硬编码。

tour 参数

大多数由 ESPN 提供支持的命令都需要 --tour=atp 或 --tour=wta：

• ATP：男子职业网球巡回赛
• WTA：女子职业网球巡回赛

如果用户未指定，请询问他们需要哪个巡回赛，或调用两次该命令并同时展示两者的数据。

命令

命令	说明
get_scoreboard	某个巡回赛的实时/近期赛事比分
get_rankings	ATP 或 WTA 球员排名
get_calendar	完整赛季赛事日历
get_player_info	单个网球球员资料
get_news	网球新闻文章
get_wta_entry_list	某届赛事的 WTA 参赛名单（单打球员和双打组合）——WTA API
get_wta_player_results	某位 WTA 球员最近的比赛结果（限定窗口），按时间从近到远排列——WTA API

完整参数列表和返回结构请参阅 references/api-reference.md。

WTA API 命令使用 WTA 原生 ID

get_wta_entry_list 和 get_wta_player_results 读取的是 WTA 公开 API（api.wtatennis.com），而非 ESPN：

• tournament_id 和 player_id 是 WTA 自己的数字 ID，必须为正整数且不能有前导零（例如赛事 ID 901、球员 ID 320760）。get_rankings / get_player_info / get_scoreboard 返回的 ESPN ID 在此处不可用，二者之间也没有 ID 映射。
• get_wta_player_results 返回的是最近比赛结果的限定窗口（最多 limit 场，可选按一个 year 限定），而非职业生涯历史。没有结果总数：has_more 仅表示还有更多比赛，且 history_complete 始终为 false。绝不要把 count 说成职业生涯或赛季总数。
• 结果日期采用赛事开始日期（tournament_start_date），而非每场比赛的实际日期。绝不要将其说成比赛日期。
• 同一赛事内的比赛按提供方的顺序排列，该顺序不一定是比赛进行顺序。不要声称它们在赛事内的确切时间顺序。
• winner_code 是提供方原始的比赛方代码；系统不会据此推断胜负。不要据此说明谁赢了。
• 两个命令返回的都是 WTA 发布的快照（source.fetched_at），缓存最长可达 10 分钟。不要称其为完整数据或实时数据。在 SPORTS_SKILLS_REPLAY=replay/fill 模式下，source.fetched_at 为 null，而 source.served_at 仅表示本地提供数据的时间，并不代表数据的新鲜度。

工作流

实时赛事查询

1. get_scoreboard --tour=<atp|wta>
2. 按轮次展示当前比赛。
3. 查询球员资料时，使用 get_player_info --player_id=<id>。

排名查询

1. get_rankings --tour=<atp|wta> --limit=20
2. 展示排名、积分和趋势。

赛季日历

1. get_calendar --tour=<atp|wta> --year=<year>
2. 筛选特定赛事。

WTA 参赛名单

1. get_wta_entry_list --tournament_id=<wta_id> --year=<year>
2. 按赛事项目（format：单打/双打）展示种子选手和参赛类型。这是参赛名单，不是签表。

WTA 球员状态

1. get_wta_player_results --player_id=<wta_id> --year=<year> --limit=20
2. 按赛事分组；说明这些是最近的 count 场比赛，并且当 has_more 为 true 时，表示还有更早的比赛尚未获取。

示例

示例 1：正在进行的比赛 用户说：“现在正在进行哪些 ATP 比赛？” 操作：

1. 调用 get_scoreboard(tour="atp") 结果：按轮次整理的当前锦标赛比赛及其比分和状态

示例 2：女子排名 用户说：“给我看看 WTA 排名” 操作：

1. 调用 get_rankings(tour="wta", limit=20) 结果：排名前 20 的 WTA 球员及其排名、姓名、积分和趋势

示例 3：即将举行的大满贯赛事日期 用户说：“今年法国网球公开赛什么时候举行？” 操作：

1. 从 currentDate 推导年份
2. 调用 get_calendar(tour="atp", year=<derived_year>)
3. 搜索结果中的 “Roland Garros”（法国网球公开赛的官方名称） 结果：法国网球公开赛的日期、举办地（巴黎）和场地类型（红土）

不存在的命令——绝不要调用

• get_matches — 不存在。使用 get_scoreboard 获取当前比赛比分。
• get_draw — 不存在。此 API 不提供锦标赛签表数据。
• get_head_to_head — 不存在。此 API 不提供交手记录。
• get_standings — 不存在。网球使用 get_rankings，而非积分榜。
• get_match_stats — 不存在。ESPN 不会发布网球的单场比赛统计数据（ACE 球、双误、破发点）：比分板的 statistics 列表为空，单场比赛统计端点会返回 "No competitor stats found"，即使是大满贯决赛也如此。只有各盘比分可用。

如果某个命令未列在上方的 Commands 表格中，则该命令不存在。

故障排除

错误：get_scoreboard 未返回任何比赛 原因：网球锦标赛只在特定周举行；本周可能没有安排锦标赛 解决方案：调用 get_calendar(tour=...) 查找下一场赛事的安排时间

错误：排名为空 原因：排名每周一更新；更新过程中可能会有短暂间隔 解决方案：该命令会自动重试前几周的数据。如果仍为空，请几分钟后重试

错误：球员档案失败 原因：球员 ID 不正确 解决方案：使用 get_rankings 从当前排名列表中查找球员 ID，或通过 ESPN 网球 URL 核实

错误：get_wta_entry_list / get_wta_player_results 拒绝该 id 或返回 HTTP 404 原因：传入了 ESPN id（或非数字值）；这些命令只接受 WTA 原生数字 id 解决方案：使用 WTA 自己的锦标赛/球员 ID。不要用 ESPN ID 替代

错误：get_wta_player_results --year=... 失败，并显示 "outside year ... inconclusive" 原因：WTA API 返回了其他年份的比赛，因此它可能忽略了年份筛选条件 解决方案：报告无法确认该赛季的结果。不要在不传入 year 的情况下重试并将这些比赛作为该赛季的结果呈现

错误：get_wta_entry_list 执行成功，但返回 count: 0 原因：WTA 尚未发布该锦标赛和年份的参赛名单，或该 ID/年份组合不存在 解决方案：读取 note 字段并告知用户目前没有可用的参赛名单——不要报告球员字段为空

错误：比分似乎有延迟或没有实时更新 原因：比分会在每盘/每场比赛结束后更新，而非逐分更新 解决方案：这是预期行为。定期刷新 get_scoreboard 以获取更新后的各盘比分