metadata

体育元数据

封装免费的 TheSportsDB API，用于获取球队徽标、球员照片和球场信息。无需 API 密钥，也无需注册。

快速开始

sports-skills metadata get_team_logo --team_name="Arsenal"
sports-skills metadata get_team_info --team_name="Real Madrid"
sports-skills metadata get_player_photo --player_name="Messi"
sports-skills metadata search_teams --query="Manchester"
sports-skills metadata search_players --query="LeBron"

Python SDK：

from sports_skills import metadata

metadata.get_team_logo(team_name="Arsenal")
metadata.get_team_info(team_name="Real Madrid")
metadata.get_player_photo(player_name="Messi")
metadata.search_teams(query="Manchester")
metadata.search_players(query="LeBron")

重要：执行任何查询前

重要：调用任何元数据命令前，请确认：

• 球队名称使用完整的官方名称——NBA 尤其如此（例如 "Los Angeles Lakers"，而不是 "Lakers"）。
• 对于 get_team_logo，sport 参数默认为 "Soccer"。如果球队不属于足球队，请传入 sport="Basketball"、"American Football"、"Baseball"、"Ice Hockey"、"Motorsport" 或 "Cricket"；否则，查询会回退到任意运动项目中的相近名称匹配。如果没有与请求名称相近的结果，则会返回错误，并列出 TheSportsDB 提供的选项。
• 搜索球员时只需使用球员姓名（例如 "Messi"、"LeBron James"、"Tiger Woods"）。

覆盖范围

球队（徽标、横幅、球场信息）：

• 足球：全球 100 多个联赛（英超、西甲、德甲、意甲、MLS 等）
• NFL（美式橄榄球）
• NBA（篮球）——需要使用完整球队名称
• MLB（棒球）
• NHL（冰球）
• F1（赛车）
• 板球（IPL、国际赛事）

球员（照片、简介）：

• 上述所有团队运动
• 网球（ATP/WTA 球员）
• 高尔夫（PGA/LPGA 球员）

不支持： MMA/UFC、橄榄球、电子竞技、拳击。

命令

命令	必需参数	可选参数	说明
get_team_logo	team_name	sport	球队徽标 / 徽章 URL
get_team_info	team_name		球队完整信息：球场、描述、社交链接、横幅
get_player_photo	player_name		球员照片 URL
search_teams	query		跨运动项目模糊搜索球队
search_players	query		跨运动项目模糊搜索球员

工作流

丰富积分榜响应

1. 调用特定运动项目的技能（例如 football get_season_standings）获取积分榜。
2. 对积分榜中的每支球队，调用 get_team_logo --team_name=<name> 以附加徽章 URL。
3. 在球队名称旁显示徽标，呈现积分榜。

构建球队资料页

1. 调用 get_team_info --team_name="<name>" 获取球场、描述、成立年份和社交链接。
2. 同一响应中包含 badge 和 banner URL——无需再次调用。

确认含糊的球队名称

1. 调用 search_teams --query="<partial-name>" 以消除歧义。
2. 后续调用 get_team_info 时，使用结果中的确切 name 字段。

示例

示例 1：获取英超球队徽标 用户说：“阿森纳的徽标是什么样的？” 操作：

1. 调用 get_team_logo(team_name="Arsenal")——sport 默认为 "Soccer"，此处设置正确。 结果：徽标 URL、运动项目、联赛和国家/地区。

示例 2：NBA 球队——必须使用完整名称 用户说：“获取湖人队的徽标” 操作：

1. 调用 get_team_logo(team_name="Los Angeles Lakers", sport="Basketball")——必须同时使用完整名称和运动项目筛选条件。 结果：来自 TheSportsDB NBA 分类的湖人队徽章。

示例 3：球员照片 用户说：“给我看看梅西的照片” 操作：

1. 调用 get_player_photo(player_name="Messi")。 结果：球员照片 URL、运动项目、球队和国籍。

示例 4：消除“Manchester”的歧义 用户说：“帮我找曼彻斯特的球队” 操作：

1. 调用 search_teams(query="Manchester")。 结果：与 "Manchester" 匹配的球队列表——例如曼联、曼城等——每项都附有运动项目、联赛和国家/地区。

不存在的命令——切勿调用

• get_stadium_info——不存在。球场信息包含在 get_team_info 中。
• get_league_logo——不存在。get_team_logo 仅用于获取球队徽章。
• get_player_stats——此技能中不存在。TheSportsDB 元数据不包含统计数据；请使用特定运动项目的技能（例如 football get_player_profile、nba get_player_stats）。
• search_leagues——不存在。

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

故障排查

错误：get_team_logo 返回了错误的球队 原因：较短或有歧义的球队名称（例如 “Lakers”“Arsenal”）先匹配到了其他运动项目中的球队 解决方案：传入明确的 sport 参数，并使用球队的完整官方名称

错误：get_team_logo / get_team_info 提示 “No team named ... found” 原因：TheSportsDB 的免费搜索只返回了名称与查询内容不太接近的球队（例如 “St. Louis Cardinals” -> “Louisville”） 解决方案：使用球队的完整官方名称，或使用 search_teams --query=<partial> 查找

错误：get_player_photo 返回 null / 空值 原因：TheSportsDB 中没有该球员，或姓名拼写不同（例如，“Cristiano Ronaldo” 与 “Ronaldo”） 解决方案：先使用 search_players --query=<partial> 查找标准拼写，然后重试

错误：徽标 URL 可以正常访问，但图片分辨率较低 原因：TheSportsDB 会原样返回贡献者提交的徽标 解决方案：这是上游限制。大多数徽标至少为 200×200；非常小的图标说明提交内容质量较低。没有变通方法。

错误：“TheSportsDB rate limit: the free API key allows 30 requests per minute”（status_code: 429） 原因：免费密钥在一分钟内收到第 31 个请求时会返回 HTTP 429，随后锁定约 2 分钟。客户端会将请求速率控制在限制以下（每批 5 个请求，然后约每 2.4 秒一个请求），因此出现此错误意味着长批次请求超出了控制速率，或另一个进程也在使用此密钥 解决方案：等待错误消息中指定的时间，然后重试。重复查询会缓存 5 分钟，因此应复用之前的结果，而不是在循环中重复查询