Sports Metadata 是一个体育元数据查询技能,封装了 TheSportsDB 的免费 API(key=3),用于获取球队队徽、球员照片和球场信息。无需 API key,也无需注册。
【主要能力】 提供五个命令:get_team_logo(球队队徽/徽章 URL,必填 team_name,可选 sport)、get_team_info(完整球队信息,含球场、描述、社交链接、横幅)、get_player_photo(球员照片 URL)、search_teams(跨运动模糊搜索球队)、search_players(跨运动模糊搜索球员)。
覆盖范围:球队(队徽、横幅、球场信息)涵盖足球(全球 100 多个联赛,如英超、西甲、德甲、意甲、MLS 等)、NFL、NBA、MLB、NHL、F1、板球(IPL、国际赛事);球员(照片、传记)涵盖上述所有团队运动,以及网球(ATP/WTA)和高尔夫(PGA/LPGA)。不覆盖 MMA/UFC、橄榄球、电竞、拳击。
【使用方式】 命令行示例: 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",非足球队需传入 "Basketball"、"American Football"、"Baseball"、"Ice Hockey"、"Motorsport" 或 "Cricket",否则会在任意运动中回退到近似名称匹配,若无接近结果则返回错误并列出 TheSportsDB 提供的选项;球员搜索只使用球员姓名(如 "Messi"、"LeBron James"、"Tiger Woods")。
【典型工作流】
- 丰富积分榜响应:先调用对应运动技能(如 football get_season_standings)获取积分榜,再对每支球队调用 get_team_logo 附加队徽 URL,最后带队徽渲染积分榜。
- 构建球队资料页:调用 get_team_info 获取球场、描述、成立年份、社交链接,同一响应已包含 badge 和 banner URL,无需二次调用。
- 消解歧义队名:先调用 search_teams 消歧,再用结果中的精确 name 字段进行后续 get_team_info 调用。
【不存在的命令】 get_stadium_info(球场信息包含在 get_team_info 中)、get_league_logo(仅支持球队徽章)、get_player_stats(本技能不含统计数据,请使用对应运动技能,如 football get_player_profile、nba get_player_stats)、search_leagues 均不存在。未列在命令表中的命令即不存在。
【限制与故障排查】
- 队徽返回错误球队:短名或歧义队名(如 "Lakers"、"Arsenal")可能先匹配到其他运动;应传入明确的 sport 参数并使用完整官方名称。
- 提示 "No team named ... found":TheSportsDB 免费搜索仅返回名称接近的球队;应使用完整官方名称,或用 search_teams --query=<partial> 查找。
- get_player_photo 返回 null/空:球员不在 TheSportsDB 中,或拼写不同(如 "Cristiano Ronaldo" 与 "Ronaldo");先用 search_players --query=<partial> 找到规范拼写再重试。
- 队徽 URL 可用但分辨率低:TheSportsDB 按贡献者提交原样返回,属上游限制,多数徽章为 200×200 或更大,无变通方法。
- 速率限制:免费 API key 每分钟允许 30 次请求,第 31 次返回 HTTP 429(status_code: 429),随后锁定约 2 分钟。客户端会自行限速(突发 5 次,之后约每 2.4 秒一次请求),出现该错误说明长批次超出限速或有其他进程共用该 key;应等待提示时间后重试。重复查询缓存 5 分钟,应复用先前结果而非循环重查。