您需要在本周向用户展示一个干净的比赛列表(按运动和国家分类),并将其集成到您的应用中。在本指南结束时,您将调用一个生产端点,该端点返回比赛元数据(ID、名称、URL、标志,如 hasStandings 和 hasStats),解析它,并将其插入到您的 UI 或后端工作流中。
您将使用 365Scores API 构建的内容
365Scores API 在 Zyla API Hub 上返回结构化的体育数据,您的应用程序可以立即使用。为了发现比赛,您将使用一个端点,该端点获取给定运动和国家的比赛,包括您需要的标识符,以将用户路由到其他地方的排名、赛程或统计信息。
典型用法包括:
- 在入职流程中的国家和联赛选择器。
- 将比赛 ID 映射到内部内容模型的管理工具。
- 缓存预热器或 CRON 作业,以每天刷新活动比赛列表。
在 Zyla API Hub 上开始
打开 API 列表,订阅并获取您的密钥:
- 访问 Zyla API Hub 上的 365Scores API 页面,点击订阅或开始免费试用。
- 从仪表板复制您的 API 密钥。所有请求都使用 Authorization: Bearer YOUR_API_KEY。
- 对下面的比赛端点进行第一次调用。
Zyla API Hub 聚合了超过 10,000 个公共 API,使用一个帐户和一个密钥。使用按订阅计费,带有配额(不是按调用计费)。对于此 API,您可以从列表页面开始 7 天的试用: 在 365Scores API 上开始 7 天试用。
端点:获取比赛(按运动和国家)
此端点返回按运动和国家范围的比赛数据。您将在 UI 中使用这些 ID,并存储名称/标志以决定渲染内容(例如,联赛是否有排名或统计信息)。
- 方法:GET
- URL:https://zylalabs.com/api/13503/365scores-api/29728/get-competitions
- 所需查询参数:
- sportId
- countryId
- langId
- timezone
- 身份验证:Authorization: Bearer YOUR_API_KEY
您可以复制/粘贴的 cURL
curl -s -X GET "https://zylalabs.com/api/13503/365scores-api/29728/get-competitions?sportId=1&countryId=11&langId=1&timezone=Europe%2FBerlin" \
-H "Authorization: Bearer YOUR_API_KEY"
官方 JSON 响应
{
"sports": [
{
"id": 1,
"name": "Football",
"nameForURL": "football",
"drawSupport": true,
"imageVersion": 1
}
],
"countries": [
{
"id": 11,
"name": "Portugal",
"nameForURL": "portugal",
"sportTypes": [
2,
8,
1
],
"imageVersion": 1,
"isInternational": false
}
],
"competitions": [
{
"id": 73,
"countryId": 11,
"sportId": 1,
"name": "Liga Portugal",
"longName": "Portuguese Primeira Liga",
"hasStandings": true,
"hasBrackets": false,
"hasStats": true,
"hasTransfers": true,
"hasLiveStandings": false,
"hasStandingsGroups": false,
"hasBets": false,
"totalGames": 0,
"liveGames": 0,
"nameForURL": "liga-portugal",
"popularityRank": 10055229,
"tableName": "Standings",
"currentSeasonNum": 94,
"currentStageNum": 1,
"color": "#000925",
"competitorsType": 1,
"imageVersion": 7,
"hideOnCatalog": false,
"hideOnSearch": false,
"hasCurrentStageStandings": true,
"hasHistory": true,
"isActive": true
},
{
"id": 74,
"countryId": 11,
"sportId": 1,
"name": "Liga Portugal 2",
"shortName": "Liga Pro",
"hasStandings": true,
"hasBrackets": false,
"hasStats": true,
"hasTransfers": true,
"hasLiveStandings": false,
"hasStandingsGroups": false,
"hasBets": false,
"totalGames": 0,
"liveGames": 0,
"nameForURL": "liga-portugal-2",
"popularityRank": 650667,
"tableName": "Standings",
"currentSeasonNum": 38,
"currentStageNum": 1,
"color": "#186839",
"competitorsType": 1,
"imageVersion": 5,
"hideOnCatalog": false,
"hideOnSearch": false,
"hasCurrentStageStandings": true,
"hasHistory": true,
"isActive": true
},
{
"id": 75,
"countryId": 11,
"sportId"…
您将实际使用的字段
- competitions[].id:您将在系统中存储和传递的主键。
- competitions[].name 和 longName:用于 UI 标签的显示字符串。
- competitions[].hasStandings、hasStats、hasTransfers:有条件地控制 UI 功能。
- competitions[].currentSeasonNum 和 currentStageNum:季节感知视图的上下文。
- competitions[].nameForURL:用于美观的 URL 或 slug。
- sports[0] 和 countries[0]:确认您请求的范围(例如,葡萄牙的足球)。
关于时区的说明:请求包括 timezone=Europe/Berlin。保持在您的调用中一致,以便您从相关端点遇到的任何下游日期/时间字段保持对齐。上面的示例不包括时间戳,但在整个集成中使用稳定的时区字符串是一个好习惯。
Python 示例:获取和过滤活动比赛
下面的代码片段调用相同的端点,强制执行 Authorization 头,并在打印您可以交给前端的紧凑有效负载之前过滤掉不活动的比赛。
import os
import requests
API_KEY = os.getenv("ZYLALABS_API_KEY", "YOUR_API_KEY")
URL = "https://zylalabs.com/api/13503/365scores-api/29728/get-competitions"
params = {
"sportId": "1",
"countryId": "11",
"langId": "1",
"timezone": "Europe/Berlin"
}
headers = {
"Authorization": f"Bearer {API_KEY}"
}
resp = requests.get(URL, params=params, headers=headers, timeout=30)
resp.raise_for_status()
data = resp.json()
competitions = data.get("competitions", [])
active = [c for c in competitions if c.get("isActive")]
# Minimal shape for your UI
result = [
{
"id": c["id"],
"name": c.get("name") or c.get("longName"),
"slug": c.get("nameForURL"),
"hasStandings": c.get("hasStandings"),
"hasStats": c.get("hasStats"),
"season": c.get("currentSeasonNum"),
"stage": c.get("currentStageNum")
}
for c in active
]
print({
"sport": (data.get("sports") or [{}])[0].get("name"),
"country": (data.get("countries") or [{}])[0].get("name"),
"count": len(result),
"competitions": result[:5] # preview top 5
})
节省时间的实施说明
- IDs 是稳定的键:将 competitions[].id 存储为您的规范引用。名称可能在赛季之间更改;slug(nameForURL)很方便,但不是主键。
- 功能标志:hasStandings、hasStats、hasTransfers 让您在不探测其他端点的情况下隐藏或显示选项卡。
- 缓存:国家级比赛列表不会每分钟更改。缓存数小时,并在您部署或按日程安排时使其失效。
- 本地化:在客户端语言中一致使用 langId。如果您支持多个区域,请按(sportId、countryId、langId)缓存结果。
- 时区:在您的应用中保持时区一致,以避免在稍后添加其他端点时出现派生日期的细微差异。示例中使用的是 Europe/Berlin;选择一种策略并坚持下去。
逐步:将比赛详情集成到您的应用中
1)决定您的范围
选择 sportId 和 countryId 作为您的产品发布范围。在上面的示例中,sportId=1(足球)和 countryId=11(葡萄牙)。您可以通过根据需要更改这些 ID 来查询不同的国家或运动。
2)在服务器端调用端点
从安全的后端发送 Authorization: Bearer 头。避免在客户端代码中暴露 YOUR_API_KEY。响应包括 sports、countries 和 competitions 数组,您可以将其映射到您的页面模型。
3)规范化和存储
持久化比赛 id、名称、slug 和标志。大多数团队存储最小行以及用于调试的原始 JSON。
4)渲染您的 UI
显示一个从缓存中填充的国家和联赛选择器。使用标志有条件地渲染选项卡(例如,仅当 hasStandings 为 true 时显示“排名”选项卡)。
5)按计划刷新
以适合您用例的节奏重建缓存(例如,每天)。在元数据中跟踪最后更新时间,以便在联赛列表似乎过时时快速排查问题。
您可能接下来使用的相关端点
如果您的比赛视图还链接到以球员为中心的页面,这些端点返回球员详情、比赛和统计信息。它们与比赛发现分开,但通常在相同的产品区域中一起出现。
获取球员详情
- 方法:GET
- URL:https://zylalabs.com/api/13503/365scores-api/29748/get-player-details
- 参数:playerId、langId、timezone
{
"sports": [
{
"id": 1,
"name": "Football",
"nameForURL": "football",
"drawSupport": true,
"imageVersion": 1
}
],
"countries": [
{
"id": 11,
"name": "Portugal",
"nameForURL": "portugal",
"sportTypes": [
2,
8,
1
],
"imageVersion": 1,
"isInternational": false
}
],
"competitions": [
{
"id": 73,
"countryId": 11,
"sportId": 1,
"name": "Liga Portugal",
"longName": "Portuguese Primeira Liga",
"hasStandings": true,
"hasBrackets": false,
"hasStats": true,
"hasTransfers": true,
"hasLiveStandings": false,
"hasStandingsGroups": false,
"hasBets": false,
"totalGames": 0,
"liveGames": 0,
"nameForURL": "liga-portugal",
"popularityRank": 10055229,
"tableName": "Standings",
"currentSeasonNum": 94,
"currentStageNum": 1,
"color": "#000925",
"competitorsType": 1,
"imageVersion": 7,
"hideOnCatalog": false,
"hideOnSearch": false,
"hasCurrentStageStandings": true,
"hasHistory": true,
"isActive": true
},
{
"id": 74,
"countryId": 11,
"sportId": 1,
"name": "Liga Portugal 2",
"shortName": "Liga Pro",
"hasStandings": true,
"hasBrackets": false,
"hasStats": true,
"hasTransfers": true,
"hasLiveStandings": false,
"hasStandingsGroups": false,
"hasBets": false,
"totalGames": 0,
"liveGames": 0,
"nameForURL": "liga-portugal-2",
"popularityRank": 650667,
"tableName": "Standings",
"currentSeasonNum": 38,
"currentStageNum": 1,
"color": "#186839",
"competitorsType": 1,
"imageVersion": 5,
"hideOnCatalog": false,
"hideOnSearch": false,
"hasCurrentStageStandings": true,
"hasHistory": true,
"isActive": true
},
{
"id": 75,
"countryId": 11,
"sportId"…
获取球员比赛
- 方法:GET
- URL:https://zylalabs.com/api/13503/365scores-api/29749/get-player-matches
- 参数:playerId、langId、timezone
获取球员统计信息
- 方法:GET
- URL:https://zylalabs.com/api/13503/365scores-api/29750/get-player-stats
- 参数:playerId、langId、timezone
通过 MCP 从 AI 代理调用 API
Zyla 上的每个 API 都可以从兼容 MCP 的客户端(Claude Code、Cursor、Windsurf 等)调用。将您的代理指向 MCP 端点,并在配置工具主机时将您的密钥作为查询参数提供: https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
配置完成后,您的代理可以调用您上面看到的相同比赛端点,并提供所需的参数。有关 MCP 本身的文档,请参见: MCP。
常见问题和故障排除
- 401 错误:确保 Authorization 头完全是 Authorization: Bearer YOUR_API_KEY,没有额外的空格或方案。
- 空比赛数组:验证 sportId 和 countryId 是否有效。尝试不同的组合,如果您的初始组合没有返回联赛。
- 本地化不匹配:如果您的 UI 是特定语言,请在调用中保持 langId 一致。按语言缓存结果。
- 时区差异:在应用程序级别标准化时区,以避免在稍后添加其他端点时出现混合的 UTC/本地行为。
现实世界的集成模式
- 服务器渲染的菜单:在应用启动时,获取比赛并按国家渲染联赛下拉菜单。仅存储 id、名称、slug 和功能标志。
- 批量摄取:夜间作业迭代您支持的国家,并将比赛数据刷新到您的数据库或 KV 存储中。
- 功能限制页面:如果 API 标志显示联赛的资源不可用(hasStandings、hasStats),则不要链接到排名或统计信息。
- 深度链接:使用 nameForURL 构建人类可读的 slug,同时在后台通过数字 id 路由。
常见问题解答
我可以更改运动和国家吗?
可以。将适当的 sportId 和 countryId 传递到查询字符串中。示例使用的是葡萄牙的足球;更新 ID 以匹配您的范围。
我需要在每个请求中发送 API 密钥吗?
是的。在您服务器端代码的每个调用中包含 Authorization: Bearer YOUR_API_KEY。
我应该多久刷新一次比赛列表?
比赛列表不会每分钟更改。大多数团队缓存数小时或每天刷新。选择与您产品需求一致的节奏。
如果我需要从比赛视图链接的球员页面怎么办?
使用上面显示的球员端点(详情、比赛、统计信息)来填充特定于球员的页面或模态。它们是与比赛发现分开的调用。
是否有免费计划?
访问选项可能会更改。请查看 API 页面以获取当前访问选项和定价。您可以从市场列表开始 7 天的试用。
准备好发布比赛详情了吗?订阅并从 Zyla API Hub 上的 365Scores API 列表中获取您的密钥: 在 365Scores API 上开始 7 天试用。然后将 cURL 或 Python 示例放入您的后端,缓存结果,并点亮您的 UI。
官方 API 响应
{
"sports": [
{
"id": 1,
"name": "Football",
"nameForURL": "football",
"drawSupport": true,
"imageVersion": 1
}
],
"countries": [
{
"id": 11,
"name": "Portugal",
"nameForURL": "portugal",
"sportTypes": [
2,
8,
1
],
"imageVersion": 1,
"isInternational": false
}
],
"competitions": [
{
"id": 73,
"countryId": 11,
"sportId": 1,
"name": "Liga Portugal",
"longName": "Portuguese Primeira Liga",
"hasStandings": true,
"hasBrackets": false,
"hasStats": true,
"hasTransfers": true,
"hasLiveStandings": false,
"hasStandingsGroups": false,
"hasBets": false,
"totalGames": 0,
"liveGames": 0,
"nameForURL": "liga-portugal",
"popularityRank": 10055229,
"tableName": "Standings",
"currentSeasonNum": 94,
"currentStageNum": 1,
"color": "#000925",
"competitorsType": 1,
"imageVersion": 7,
"hideOnCatalog": false,
"hideOnSearch": false,
"hasCurrentStageStandings": true,
"hasHistory": true,
"isActive": true
},
{
"id": 74,
"countryId": 11,
"sportId": 1,
"name": "Liga Portugal 2",
"shortName": "Liga Pro",
"hasStandings": true,
"hasBrackets": false,
"hasStats": true,
"hasTransfers": true,
"hasLiveStandings": false,
"hasStandingsGroups": false,
"hasBets": false,
"totalGames": 0,
"liveGames": 0,
"nameForURL": "liga-portugal-2",
"popularityRank": 650667,
"tableName": "Standings",
"currentSeasonNum": 38,
"currentStageNum": 1,
"color": "#186839",
"competitorsType": 1,
"imageVersion": 5,
"hideOnCatalog": false,
"hideOnSearch": false,
"hasCurrentStageStandings": true,
"hasHistory": true,
"isActive": true
},
{
"id": 75,
"countryId": 11,
"sportId"…