您需要交付一个体育集成，它可以：列出所有支持的体育项目，通过名称搜索团队/联赛/球员，并在不寻找图像资产的情况下呈现国家旗帜。在本指南结束时，您将通过 Zyla API Hub 调用 SofaScore - 实时 API 来做到这一点，使用可以直接复制粘贴到生产中的请求。
此 API 的功能及使用时机
Zyla API Hub 上的 SofaScore - 实时 API 提供三项核心功能，您可以将其连接到记分板、发现流程和 UI 组件：
- 获取所有体育项目：列举支持的体育项目（id、名称、slug），用于应用程序引导和过滤。
- 搜索所有实体：通过自由文本查询 SofaScore 实体（例如，团队）以支持搜索框和自动完成。
- 获取国家旗帜：获取国家旗帜的原始图像字节，在显示团队或球员国籍时非常有用。
它通过单个 Zyla 订阅和密钥提供，所有端点都有一致的授权头。Zyla 在一个帐户和一个 API 密钥后面托管超过 10,000 个公共 API，因此您可以稍后添加更多体育和游戏数据，而无需重新处理身份验证流程。请在 zylalabs.com 探索目录。
在 Zyla API Hub 上开始
打开 Zyla API Hub 上的 SofaScore - 实时 API 页面并订阅。您帐户上的第一个 API 包括 7 天试用或 50 次请求，计费使用订阅 + 配额模型（而不是按调用计费）。有关当前访问选项和定价，请直接查看 API 页面。订阅后，您将收到一个 API 密钥。
以下所有请求均包含此头：
- Authorization: Bearer YOUR_API_KEY
您今天可以连接的端点
1) 获取所有体育项目
使用此端点填充静态体育列表以进行导航、过滤或入门。它返回一个包含 id、名称和 slug 的体育数组。
- 方法：GET
- URL： https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports
- 参数：无文档
- 授权：Authorization: Bearer YOUR_API_KEY
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 友好的标识符（用于路由或规范键）。
Python 示例（请求）：
import requests
API_KEY = "YOUR_API_KEY"
url = "https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports"
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = requests.get(url, headers=headers, timeout=10)
resp.raise_for_status()
sports = resp.json()
# 构建映射并打印排序菜单
slug_by_id = {s["id"]: s["slug"] for s in sports}
menu = [f'{s["id"]}: {s["name"]} ({s["slug"]})' for s in sports]
print("\n".join(sorted(menu, key=lambda x: x.lower())))
# 示例：选择足球运动 id
football_id = next((s["id"] for s in sports if s["slug"] == "football"), None)
print("football_id =", football_id)2) 搜索所有实体
使用此功能通过自由文本查询字符串（例如，团队名称）搜索 SofaScore 实体。这对于自动完成和“跳转到团队”功能非常理想。
- 方法：GET
- URL： https://zylalabs.com/api/12787/sofascore-live-api/25082/search-all-entities
- 参数：
- q（字符串，必填）：搜索词。例如：皇家马德里
- 授权：Authorization: Bearer YOUR_API_KEY
cURL：
示例响应（摘录自中心）：
[{"entity":{"id":2829,"name":"Real Madrid","slug":"real-madrid","imagePath":"https:\/\/img.sofascore.com\/api\/v1\/team\/2829\/image","proxyImagePath":"https:\/\/betting.asdasddsgdfgfdsgfj.website\/sofascore\/image-proxy?imagePath=https:\/\/img.sofascore.com\/api\/v1\/team\/2829\/image","fullName":null,"shortName":null,"nameCode":"RMA","gender":"M","country":{"name":"Spain","slug":"spain","alpha2":"ES","alpha3":null,"imagePath":"https:\/\/img.sofascore.com\/api\/v1\/country\/ES\/flag","proxyImagePath":"https:\/\/betting.asdasddsgdfgfdsgfj.website\/sofascore\/image-proxy?imagePath=https:\/\/img.sofascore.com\/api\/v1\/country\/ES\/flag"},"foundationDateTimestamp":null,"manager":[],"ranking":null,"national":false,"venue":[],"sport":{"id":1,"name":"Football","slug":"football"}},"score":4293164.5,"type":"team"},{"entity":{"id":2816,"name":"皇家贝蒂斯","slug":"real-betis","imagePath":"https:\/\/img.sofascore.com\/api\/v1\/team\/2816\/image","proxyImagePath":"https:\/\/betting.asdasddsgdfgfdsgfj.website\/sofascore\/image-proxy?imagePath=https:\/\/img.sofascore.com\/api\/v1\/team\/2816\/image","fullName":null,"shortName":null,"nameCode":"BET","gender":"M","country":{"name":"西班牙","slug":"spain","alpha2":…实施者注意事项：
- 读取 entity.id、entity.name、entity.slug 和 type 以对结果进行分类（例如，团队与其他类型）。
- 响应包括您可以代理的图像 URL；根据您的 UI 按原样使用。
- 对于快速 UI，防抖查询并缓存最近的结果，以 q 为键。
3) 获取国家旗帜
获取国家旗帜图像字节。用于在不维护您自己的资产存储的情况下显示球员或团队的国家旗帜。
- 方法：GET
- URL： https://zylalabs.com/api/12787/sofascore-live-api/31197/get-country-flag
- 参数：
- country_code（字符串，必填）：EN
- 授权：Authorization: Bearer YOUR_API_KEY
cURL：
示例响应（图像字节摘录）：
iVBORw0KGgoAAAANSUhEUgAAAJYAAACWCAMAAAAL34HQAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAJcEhZcwAACxMAAAsTAQCanBgAAAELUExURUdwTN/f37QVJd7e3t3d3d/f39/f39/f397e3t7e3t3d3d3d3d3d3d/f397e3t/f39/f39zc3N7e3rQUJN/f37MUJLUTJd/f39/f3+Hh4d3d3bMUJLUVJbQUJLUVJbUUJLcQKOHh4d3d3bQVJLQUJN/f397e3rQVJbIWI7ITI7QUJLcYKM4RJP///97e3rQUJPv7++Li4v39/ebm5uDg4Orq6vDw8OTk5Pf397sTJPn5+bsUJPPz8/Ly8u7u7rcUJMcSJOzs7PHx8cQSJO/v77gUJLgTJOjo6MoSJMETJL8TJLUUJL4TJOvr680RJMsSJMsRJMQTJL0TJO3t7cwRJLYUJM0SJLwUJL4UJDN2488AAAAsdFJOUwB/38+AMBAg79+fcJBAv3CfYKC/YICfj79vr0AwcGCvIF+Pz8+vsKBQULAgUCRTtgAABilJREFUeNrtnGdX40YUhoWrhA1uGFj6tmQ34VrFKl6vzdqYDrtJNvX//5JMkSU3YWk0kiYn3A/CB3zMc+776s54NHMlKV6cfThp756+zeVUErlcq7XbPj48kjKLYqOel9WAkLf3GsXUkcqVA7mDIwiL/FE+qKSItrWndKZBIR6vrz+TuL6excKhbG6lwyR3/ND/eZiM7r6dz8bdaHL/tzPzJmUz4ZyVKtvePzMtu2fAeUCA0bNvde/N+UaCUBteorp2H0gEYpHo210/ZeVkXL7pMxkwjeexUGgDjywBMA/KufKZwmARMj0ZME++bg/mIwwWip7lgm1wBHtFocyxBsCGhVLmgim8zF+md585r15ULB8szyVhrn6WBhAPywfb4JWqJU8xYSEwan6lzMNV5iUAHywAelfKlTg34B5NlQb8sKZKvikxC5hfkyomLJQwM46QRTJPcDTgjeU6TGEawF+TXP8OwB8L4Ip8OIPBNoiAA0gGCy5NpkpBqPQ+JIXlCrnBQqVBclgsXITKMSBJLDCciFyEqhuGKg5WVC5C9RUgaSyArxG4XhEFIQ0sIDPX16GqaGhfccCiOoaoq2Vc2/WwVHGxwNBDjUMlJWRl4IRF60R+3biN5wxmeKr4WNDH…实施提示：
- 响应是图像数据；根据需要将其存储或流式传输到您的前端。
- 在您的 CDN 或对象存储中缓存旗帜，以避免重复下载。
整合在一起：常见的集成模式
- 引导过滤器：在应用程序初始化期间调用获取所有体育项目，存储 id/name/slug，并在下拉列表中公开该列表。
- 搜索框：在用户输入时，调用搜索所有实体并传入 q。防抖 250–400 毫秒，按查询缓存以减少调用。
- 国家旗帜：在显示团队或球员卡时，每个代码调用一次获取国家旗帜并缓存结果；在页面之间重用缓存。
身份验证和请求卫生
- 在每个请求中发送 Authorization: Bearer YOUR_API_KEY。
- 将体育列表视为相对静态；偶尔在后台刷新并本地存储。
- 构建基本错误处理路径：网络超时、非 200 状态和搜索的空数组。
通过 MCP 从 AI 代理调用此 API
如果您使用 AI 编码代理（例如，兼容 MCP 的 IDE 和工具），您可以通过 Zyla MCP 桥调用相同的端点。将您的客户端指向 MCP 端点，并在查询字符串中提供您的 Zyla API 密钥。有关详细信息，请参见 MCP。代理可以使用中心 URL 和授权头发出与上面显示的相同的 GET 请求。
节省时间的操作说明
- 幂等性：文档中的端点是 GET；在瞬态故障时可以安全重试。
- 客户端缓存：在内存中缓存获取所有体育项目并持久化到轻量级数据存储；在应用程序启动时刷新。
- 二进制数据处理：旗帜端点返回图像字节。在代理到浏览器时，设置适合您环境的头，以便客户端可以按预期呈现或下载。
- 使用计划：Zyla API 使用订阅 + 配额。您帐户上的第一个 API 包括 7 天试用或 50 次请求；在负载测试之前，请在 API 页面上验证您当前的配额。
深入示例
搜索：为建议列表塑造结果
在调用搜索端点后，为每个结果提取轻量级投影：
- id：数字实体 id
- label：entity.name
- type：类型（例如，团队）以标记结果
- sport：entity.sport.slug 用于范围
- country：entity.country.alpha2（如果存在）；如果您需要一个旗帜，请调用获取国家旗帜并传入所需的 country_code 参数
此投影紧凑并保持您的 UI 快速。
旗帜：提供给浏览器
当您的后端从获取国家旗帜接收图像字节时，您可以：
- 将字节作为 PNG 存储在对象存储中，并通过标准化键（例如，flag-EN.png）进行 CDN 缓存。
- 如果您希望零往返渲染，则返回数据 URI 到您的前端；请注意 HTML 负载的大小影响。
完整参考
获取所有体育项目
- 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
- 参数：
- q（字符串，必填）：搜索查询
- 授权：Authorization: Bearer YOUR_API_KEY
获取国家旗帜
- GET https://zylalabs.com/api/12787/sofascore-live-api/31197/get-country-flag
- 参数：
- country_code（字符串，必填）：EN
- 授权：Authorization: Bearer YOUR_API_KEY
常见问题解答
我如何验证请求？
在每次调用中心 URL 时包含头：Authorization: Bearer YOUR_API_KEY。
是否有免费计划？
该模型为订阅 + 配额。对于您在 Zyla 上的第一个 API，您将获得 7 天试用或 50 次请求。请查看 API 页面以获取当前访问选项和定价。
我可以对搜索结果进行分页吗？
分页详细信息未在此处记录。使用提供的搜索端点并按原样处理返回的数组。
旗帜端点返回什么格式？
它返回图像字节。示例显示类似 PNG 的字节流。根据您的应用程序适当存储或提供。
我应该从体育列表中持久化哪些字段？
持久化 id、name 和 slug。id 是一个良好的稳定键；name 和 slug 用于 UI 和路由。
准备将其连接到您的应用程序了吗？在 Zyla 上创建一个免费帐户，获取您的密钥，并开始使用 SofaScore - 实时 API 构建。从这里开始： 开始 7 天试用 SofaScore - 实时 API。您可以随时在 zylalabs.com 探索更多体育和游戏 API。
