您需要在本周交付一个体育集成:列出支持的体育项目以供过滤菜单使用,按名称搜索球队/联赛,并在俱乐部和国家队旁边显示国旗。通过本文,您将了解如何使用 SofaScore - 实时 API 在 Zyla API Hub 上实现这一点,包括一个有效的 curl 调用、一个 Python 代码片段,以及通过 MCP 从 AI 代理使用相同 API 的说明。
此 API 的功能及使用时机
SofaScore - 实时 API 暴露了用于探索体育元数据和在 SofaScore 目录中搜索实体的端点。通过它,您可以:
- 获取可用体育项目的目录(例如,足球、网球、篮球),以支持过滤器、入职流程或数据集发现。
- 通过查询字符串搜索所有实体(球队等),将用户输入(如“皇家马德里”)解析为具有 ID 和图像路径的规范实体。
- 在需要渲染国旗时,获取国家国旗的原始图像字节,以便与俱乐部、国家队或球员资料一起显示。
典型应用:实时比分仪表板、博彩和幻想工具、内容和预览页面、用于按体育标记内容的管理后台,以及需要可靠解析体育实体名称的 AI 代理。
在 Zyla API Hub 上开始
所有调用都通过 Zyla API Hub 进行,使用一个 API 密钥和订阅 + 配额模型(不是按调用付费)。第一个 API 包括 7 天的试用或 50 次请求,以便您可以快速验证。要开始:
- 打开 SofaScore - 实时 API 页面并开始试用: 开始 SofaScore - 实时 API 的 7 天试用。
- 从仪表板复制您的 API 密钥。
- 向文档中记录的 Zyla Hub URL 发送请求,使用头部 Authorization: Bearer YOUR_API_KEY。
您可以在 zylalabs.com 上发现超过 10,000 个公共 API 并从一个帐户管理它们。如果您计划稍后添加更多体育功能,统一的密钥和订阅使其变得简单。
可用端点
以下是此 API 的文档端点。仅列出的方法、URL 和参数可用;请按所示方式实现。
1) 获取所有体育项目
- 方法:GET
- URL:https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports
- 参数:无文档
- 使用案例:填充下拉菜单和过滤器,验证体育 slug,预填充您的数据库与体育 ID/slug。
curl 示例(复制粘贴即可):
curl -s -X GET "https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports" \
-H "Authorization: Bearer YOUR_API_KEY"
官方示例 JSON 响应:
[
{
"id": 1,
"name": "足球",
"slug": "football"
},
{
"id": 5,
"name": "网球",
"slug": "tennis"
},
{
"id": 2,
"name": "篮球",
"slug": "basketball"
},
{
"id": 64,
"name": "棒球",
"slug": "baseball"
},
{
"id": 23,
"name": "排球",
"slug": "volleyball"
},
{
"id": 63,
"name": "美式足球",
"slug": "american-football"
},
{
"id": 6,
"name": "手球",
"slug": "handball"
},
{
"id": 20,
"name": "乒乓球",
"slug": "table-tennis"
},
{
"id": 4,
"name": "冰球",
"slug": "ice-hockey"
},
{
"id": 22,
"name": "飞镖",
"slug": "darts"
},
{
"id": 72,
"name": "电子竞技",
"slug": "esports"
},
{
"id": 11,
"name": "赛车",
"slug": "motorsport"
},
{
"id": 65,
"name": "骑行",
"slug": "cycling"
},
{
"id": 62,
"name": "板球",
"slug": "cricket"
},
{
"id": 76,
"name": "综合格斗",
"slug": "mma"
},
{
"id": 12,
"name": "橄榄球",
"slug": "rugby"
},
{
"id": 29,
"name": "五人制足球",
"slug": "futsal"
},
{
"id": 31,
"name": "羽毛球",
"slug": "badminton"
},
{
"id": 26,
"name": "水球",
"slug": "waterpolo"
},
{
"id": 19,
"name": "斯诺克",
"slug": "snooker"
},
{
"id": 13,
"name": "澳式足球",
"slug": "aussie-rules"
},
{
"id": 34,
"name": "沙滩排球",
"slug": "beach-volley"
},
{
"id": 109,
"name": "迷你足球",
"slug": "minifootball"
},
{
"id": 7,
"name": "地板球",
"slug": "floorball"
},
{
"id": 15,
"name": "班迪球",
"slug": "bandy"
},
{
"id": 110,
"name": "帕德尔",
"slug": "padel"
}
]
您实际使用的字段:
- id:体育项目的数字标识符。将其存储以便在您的系统中查找和连接。
- name:您可以在 UI 中显示的名称。
- slug:适合 URL 和过滤器的稳定标识符(例如,“football”、“basketball”)。
2) 搜索所有实体
- 方法:GET
- URL:https://zylalabs.com/api/12787/sofascore-live-api/25082/search-all-entities
- 参数:
- q(字符串,必填):搜索查询,例如 real madrid
- 功能:通过查询字符串搜索所有 SofaScore 实体。适用于类型提示、将用户输入解析为规范 ID,或将内容自动链接到球队。
带参数的示例请求 URL(需要授权头):
https://zylalabs.com/api/12787/sofascore-live-api/25082/search-all-entities?q=real+madrid
3) 获取国家国旗
- 方法:GET
- URL:https://zylalabs.com/api/12787/sofascore-live-api/31197/get-country-flag
- 参数:
- country_code(字符串,必填):一个 alpha-2 风格的代码,例如 EN
- 功能:返回国家国旗图像字节。根据需要嵌入或持久化以用于国旗徽章。
带参数的示例请求 URL(需要授权头):
https://zylalabs.com/api/12787/sofascore-live-api/31197/get-country-flag?country_code=EN
Python 示例:获取并使用体育目录
此 Python 代码片段调用获取所有体育项目,解析您通常需要的几个字段,并演示简单的缓存以避免在一天中重复获取。
import os
import time
import requests
API_KEY = os.getenv("ZYLALABS_API_KEY", "YOUR_API_KEY")
URL = "https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
# 非常简单的缓存:每 6 小时刷新一次
CACHE_FILE = "/tmp/sofascore_sports.json"
CACHE_TTL_SECONDS = 6 * 60 * 60
def should_refresh(path, ttl):
try:
mtime = os.path.getmtime(path)
except FileNotFoundError:
return True
return (time.time() - mtime) > ttl
def load_cached(path):
import json
with open(path, "r", encoding="utf-8") as f:
return json.load(f)
def save_cache(path, data):
import json
with open(path, "w", encoding="utf-8") as f:
json.dump(data, f)
def get_all_sports():
if not should_refresh(CACHE_FILE, CACHE_TTL_SECONDS):
return load_cached(CACHE_FILE)
resp = requests.get(URL, headers=HEADERS, timeout=15)
resp.raise_for_status()
data = resp.json() # 期望返回一个 {id, name, slug} 的列表
save_cache(CACHE_FILE, data)
return data
if __name__ == "__main__":
sports = get_all_sports()
# 构建查找:slug -> id
slug_to_id = {s["slug"]: s["id"] for s in sports}
# 保持一个有序的名称列表以供下拉菜单使用
sport_names = [s["name"] for s in sports]
print("体育 slug -> ids:", slug_to_id)
print("下拉菜单选项:", sport_names)
实际实施注意事项
- 身份验证:所有端点都需要头部 Authorization: Bearer YOUR_API_KEY。
- 响应格式:
- 获取所有体育项目返回带有 id、name、slug 的 JSON 数组项。
- 搜索所有实体返回与查询匹配的实体元数据的 JSON。使用此信息将用户输入映射到 ID 和图像路径。
- 获取国家国旗返回图像字节。在存储或提供时将主体视为二进制。重新提供时设置适当的图像内容类型。
- 缓存:
- 体育目录变化不频繁。缓存响应(例如,6–24 小时)以节省配额并减少启动时间。
- 搜索结果是用户驱动的并且变化;您可以记忆常见查询,例如俱乐部名称。
- 国家国旗是静态的;按国家代码存储一次。
- 错误处理:处理非 2xx 状态代码和超时。对于搜索,回退到显示建议或要求用户细化查询。
- 配额和试用:第一个 API 包括 7 天的试用或 50 次请求。有关当前访问选项和试用后的定价,请查看 API 页面。
您可以在本周交付的具体体育使用案例
1) 入职流程:选择您的体育项目
调用获取所有体育项目以填充初始兴趣选择或确定您应用程序的覆盖范围。持久化体育 ID 和 slug,以便下游功能(例如,信息流、比赛)可以保持在这些体育项目内。
2) 球队搜索和解析
使用搜索所有实体,q 等于用户的输入。例如,用户输入“皇家马德里”:调用搜索端点并呈现顶部结果。存储返回的 entity.id 和 entity.slug 以便路由或数据库关系。如果您需要在 UI 中显示徽章,请使用 entity.imagePath。
3) 列表和比赛标题中的国家国旗
在渲染球队列表或国际比赛时,通过获取国家国旗按 alpha 风格代码获取国旗。缓存图像字节(例如,S3 或您的 CDN),按代码键入,以便您不重复获取相同的资产。
4) 管理标记和内容管理
编辑团队可以使用体育目录按体育标记文章和视频。搜索所有实体可以为确保 CMS 中实体 ID 一致性提供类型提示,防止重复的球队记录。
5) 知道体育实体的 AI 助手
当 AI 代理接收到引用球队的用户请求时,调用搜索所有实体以解析歧义并获取规范 ID 和图像路径,然后再组成响应或在您的堆栈中获取更多详细信息。
端点详细信息和集成提示
获取所有体育项目
由于没有请求参数,您的集成非常简单:向带有授权头的 URL 发送 GET 请求并解析 JSON 数组。将 slug 规范化为小写以保持一致的键。如果您的应用程序仅支持部分体育项目,请在一次过滤数组并保持本地列表。
搜索所有实体
- 参数 q 是必需的,应进行 URL 编码。保持用户输入的修剪和规范化(例如,合并多个空格)。
- 响应包括实体元数据;存储返回的 ID 以将用户选择与您的内部记录链接。许多系统创建本地映射表:external_id(SofaScore) -> internal_id。
- 类型提示:在 UI 中防抖请求,以避免用户输入时过度获取;仅在查询长度 ≥ 2–3 时调用。
获取国家国旗
- 参数 country_code 是必需的。示例使用 EN。验证您计划请求的代码并优雅地处理缺失的代码。
- 由于响应是图像的字节,因此持久化原始字节或转换为 base64 以便于存储。在提供给浏览器时,根据您检测到的图像格式设置正确的 Content-Type(例如,image/png)。
- 为了性能,在第一次获取后将国旗存储在您的静态资产或 CDN 中,以保持 UI 延迟低。
通过 MCP 从 AI 代理调用 API
如果您使用与 MCP 兼容的客户端(Claude Code、Cursor、Windsurf 等),您可以通过 MCP 端点和您的 Zyla API 密钥路由调用。将您的工具指向 MCP,并使用 apikey=YOUR_API_KEY。然后,您的代理可以调用 SofaScore - 实时 API 的相同文档 Hub URL。这对于需要:
- 列出体育项目并向开发人员建议配置步骤。
- 在聊天会话中解析实体名称(通过搜索)。
- 获取国旗以嵌入生成的 UI 代码或文档。
在您工具的 HTTP 调用中保持相同的 Authorization 头。在开发过程中记录调用和响应,以便您可以调整提示逻辑或在搜索模糊时回退行为。
安全性、部署和测试清单
- 环境变量:将 YOUR_API_KEY 存储在您的秘密管理器或 CI/CD 变量中。
- 超时和重试:使用保守的超时(10–15 秒),并考虑对幂等的 GET 进行一次重试。
- 输入验证:在调用之前清理搜索的 q 并验证 country_code。
- 监控:记录状态代码和延迟;在 4xx/5xx 比率升高时发出警报。
- 缓存策略:
- 体育目录:每日刷新或在部署时刷新。
- 搜索:记忆常见查询或按会话缓存以减少更换。
- 国旗:持久缓存/CDN 存储;很少失效。
快速参考
- 获取所有体育项目:
- GET https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports
- 头部:Authorization: Bearer YOUR_API_KEY
- 参数:无
- 搜索所有实体:
- GET https://zylalabs.com/api/12787/sofascore-live-api/25082/search-all-entities
- 头部:Authorization: Bearer YOUR_API_KEY
- 参数:q(字符串,必填),例如,real madrid
- 获取国家国旗:
- GET https://zylalabs.com/api/12787/sofascore-live-api/31197/get-country-flag
- 头部:Authorization: Bearer YOUR_API_KEY
- 参数:country_code(字符串,必填),例如,EN
常见问题
我如何验证请求?
在每个请求中发送头部 Authorization: Bearer YOUR_API_KEY 到 Zyla Hub URL。
获取国家国旗返回什么?
响应主体是国旗图像字节。将其视为二进制数据。如果您代理或存储它,请在提供给客户端时设置适当的图像内容类型。
我可以缓存体育列表吗?
可以。列表不经常更改。将其缓存到您的应用程序中(例如,每日)以加快启动速度并节省配额。
我应该传递什么查询给搜索所有实体?
通过 q 参数(URL 编码)传递用户的搜索字符串,例如 q=real+madrid。使用返回的实体 ID 和 slug 作为您系统中的稳定引用。
是否有免费计划?
第一个 API 包括 7 天的试用或 50 次请求,以便您可以快速评估。有关试用后当前访问选项和定价,请查看 API 页面。
交付它
您现在拥有了支持体育过滤器、实体搜索和国家国旗所需的端点和代码。创建您的帐户并直接在列表上开始 7 天的试用: 开始 SofaScore - 实时 API 的 7 天试用。您可以在 zylalabs.com 上管理所有内容,并通过 MCP 从您的 AI 工具调用相同的端点。