开发者

足球预测 API — 胜平负 / 大小球 2.5 / 双方进球 | Footalytics

免费足球预测 API：英超、西甲、德甲、意甲、法甲与欧冠的胜平负、大小球 2.5 与双方进球概率，附信心档。JSON 返回，5 次免费调用，支持 MCP 接入 AI 助手。

获取免费 API 密钥 →实时准确率账本 AI 助手 MCP 接入下载 Agent 技能包

面向开发者与 AI 助手的免费足球预测 API：JSON 返回胜平负、大小球 2.5、双方进球概率、信心档与球队评级，覆盖英超、西甲、德甲、意甲、法甲、欧冠等。所有预测均在公开准确率账本中赛后结算。四个端点覆盖完整流程——预测比赛、查赛程、查球队评级、查已结算结果。

每账号 5 次免费调用——无需绑卡。
JSON 进、概率出：胜平负、大小球 2.5、双方进球、最可能比分与信心档。
内置 MCP server——AI 助手直连。
每条预测公开结算，附 Brier 分数。

快速开始

在 API 密钥页创建免费密钥——新账号自带 5 次免费 API 调用。

携带密钥调用端点：

curl "https://footalytics.farvor.com/api/v1/predictions?home=Chelsea&away=Manchester%20United" \
  -H "Authorization: Bearer fxk_your_key"

读取预测结果：

{
  "provider": "Footalytics",
  "match": {
    "id": "ESPN-401879248", "home": "Chelsea", "away": "Manchester United",
    "league": "Premier League", "kickoff_utc": "2026-10-31T12:30:00Z", "status": "pending"
  },
  "prediction": {
    "outcome": { "home": 0.474, "draw": 0.267, "away": 0.259, "pick": "home" },
    "confidence": "medium",
    "xg": { "home": 1.61, "away": 1.13 },
    "top_scores": [{ "score": "1-1", "p": 0.127 }, { "score": "2-1", "p": 0.094 }],
    "over_2_5": 0.55, "btts": 0.52
  },
  "result": null,
  "links": {
    "match_page": "/match/401879248-chelsea-vs-manchester-united",
    "share": "https://footalytics.farvor.com/p/x4affkwufz2c",
    "accuracy": "https://footalytics.farvor.com/accuracy"
  }
}

认证

每次请求都以 Bearer 方式携带密钥。原始密钥仅在创建时展示一次——请妥善保存，不要提交进源码。可随时在 API 密钥页吊销重建。

Authorization: Bearer fxk_your_key

GET /api/v1/predictions（预测）

一次成功调用消耗 1 个单位。失败不扣。

参数	说明
`home` + `away`	推荐方式。写球队名即可，如 home=Chelsea&away=Manchester United（空格需 URL 编码为 %20）。通过实时 14 天赛程窗口解析；若匹配到多场，优先返回已发布预测的那一场。
`fixture`	已知 id 时的精确方式：401879248、ESPN-401879248 或 ESPN-eng.1-401879248 均可。已开球的比赛只能用这种方式查询。
`date`	可选，YYYY-MM-DD（UTC）——区分双循环再赛。

{
  "provider": "Footalytics",
  "match": {
    "id": "ESPN-401879248", "home": "Chelsea", "away": "Manchester United",
    "league": "Premier League", "kickoff_utc": "2026-10-31T12:30:00Z", "status": "pending"
  },
  "prediction": {
    "outcome": { "home": 0.474, "draw": 0.267, "away": 0.259, "pick": "home" },
    "confidence": "medium",
    "xg": { "home": 1.61, "away": 1.13 },
    "top_scores": [{ "score": "1-1", "p": 0.127 }, { "score": "2-1", "p": 0.094 }],
    "over_2_5": 0.55, "btts": 0.52
  },
  "result": null,
  "links": {
    "match_page": "/match/401879248-chelsea-vs-manchester-united",
    "share": "https://footalytics.farvor.com/p/x4affkwufz2c",
    "accuracy": "https://footalytics.farvor.com/accuracy"
  }
}

覆盖范围：官方预测在开球前 48 小时内发布。英超、西甲、德甲、意甲、法甲与欧冠全部比赛均覆盖，其他联赛取焦点对阵。球队名解析只覆盖实时赛程窗口内未开球的比赛——已开球的比赛请传 fixture id。

GET /api/v1/fixtures（赛程）

带 fixture id 的未来赛程——流程的“发现”半步：先在这里找比赛（has_prediction 标记是否已有官方预测），再调预测。计费与预测一致。

参数	说明
`team`	球队名子串，如 team=Arsenal——匹配主客任一侧。
`league`	ESPN key（eng.1）或联赛 slug（premier-league）。
`date`	可选，YYYY-MM-DD（UTC）。
`limit`	可选，默认 20，最大 50。

team 与 league 至少传一个。

curl "https://footalytics.farvor.com/api/v1/fixtures?league=eng.1&limit=3" \
  -H "Authorization: Bearer fxk_your_key"

{
  "provider": "Footalytics",
  "fixtures": [
    {
      "fixture": "ESPN-401879251", "home": "AFC Bournemouth", "away": "Leeds United",
      "competition": "Premier League", "kickoff_utc": "2026-10-31T15:00Z",
      "has_prediction": false,
      "links": { "match_page": "/match/401879251-afc-bournemouth-vs-leeds-united" }
    }
  ]
}

GET /api/v1/teams（球队）

来自评级表的球队档案：每条预测背后的 Elo 式评分。

参数	说明
`name`	球队名子串，至少 2 字符，如 name=arsenal。
`league`	可选过滤，ESPN key 或 slug。
`limit`	可选，默认 20，最大 50。

name 与 league 至少传一个。

curl "https://footalytics.farvor.com/api/v1/teams?name=arsenal" \
  -H "Authorization: Bearer fxk_your_key"

{
  "provider": "Footalytics",
  "teams": [
    {
      "id": "359", "name": "Arsenal", "league": "eng.1", "league_name": "Premier League",
      "rating": 1971, "games": 27, "ratings_updated_at": "2026-10-28T13:00:23Z"
    }
  ]
}

GET /api/v1/results（历史结果）

赛后结算记录：真实比分与模型预测并列，逐市场给出命中——与公开准确率账本同源。

参数	说明
`team`	球队名过滤，如 team=Chelsea。
`league`	ESPN key 或 slug。
`fixture`	单个 fixture id。
`limit`	可选，默认 10，最大 20。

team、league、fixture 至少传一个。

curl "https://footalytics.farvor.com/api/v1/results?team=Chelsea&limit=3" \
  -H "Authorization: Bearer fxk_your_key"

{
  "provider": "Footalytics",
  "results": [
    {
      "fixture": "ESPN-401878764", "home": "Sunderland", "away": "Leeds United",
      "competition": "Premier League", "kickoff_utc": "2026-10-25T16:30:00Z",
      "result": { "home_goals": 0, "away_goals": 0 },
      "our_prediction": {
        "outcome": { "home": 0.398, "draw": 0.277, "away": 0.326, "pick": "home" },
        "confidence": "low", "actual": "draw",
        "hit_1x2": false, "hit_over_2_5": false, "hit_btts": false, "brier": 0.787
      },
      "links": {
        "match_page": "/match/401878764-sunderland-vs-leeds-united",
        "share": "https://footalytics.farvor.com/p/vny7wa2tabh4"
      }
    }
  ]
}

积分与限流

API 有独立免费额度：任意端点共 5 次调用（预测、fixtures、teams、results），每账号一次性发放。用完后按次消耗积分（与站内充值积分同池）；失败不扣费。站内免费预测次数是独立桶，只能在站内对话使用。每个响应都带 x-credits-remaining 与 x-credits-used 头，便于调用方跟踪余额。

限流：每密钥每分钟 30 次。额度用尽时返回 402，并指向充值入口：

{
  "error": {
    "code": "E_INSUFFICIENT_CREDITS",
    "message": "You've used all 5 free API calls and your credits.",
    "get_more": [ { "method": "purchase", "url": "https://footalytics.farvor.com/pricing" } ]
  }
}

充值积分

错误码

HTTP	code	含义
401	`E_INVALID_API_KEY`	密钥不存在或已吊销。
402	`E_INSUFFICIENT_CREDITS`	免费额度与积分均已用尽——见 get_more。
403	`E_KEY_SCOPE`	密钥只能调用这四个 API 端点。
404	`E_PREDICTION_UNAVAILABLE`	该比赛暂无官方预测（见上方覆盖范围）。
404	`E_TEAM_NOT_FOUND`	没有匹配查询的已评级球队。
404	`E_RESULT_NOT_FOUND`	暂无匹配的已结算结果——官方预测在终场后才会结算。
422	`E_AMBIGUOUS_MATCH`	球队名匹配到多场比赛——请补 date 或 fixture 参数。
429	`E_RATE_LIMITED`	触发限流——按 Retry-After 稍候重试。

MCP——接入 AI 助手

AI 助手（Claude、ChatGPT、Cursor 等）可通过 Model Context Protocol 调用同样的预测。将任意 MCP 客户端指向：

https://footalytics.farvor.com/mcp

以 API 密钥作为 Bearer 连接，或走 OAuth 一键授权——客户端自动注册并在浏览器中请求授权。工具：get_match_prediction、list_fixtures、get_team、list_results（共用同一额度）与 get_account_credits（免费）。

Skill——Claude Code 与 agent

不想用连接器？安装兼容 Agent Skills 的技能，agent 自己调用同样四个端点——同一密钥、同一额度。直接从本站下载（无需 GitHub）：

mkdir -p ~/.claude/skills/footalytics && cd ~/.claude/skills/footalytics
for f in SKILL.md README.md README.zh-CN.md; do
  curl -fsSL "https://footalytics.farvor.com/skill/$f" -o "$f"
done

……或只取核心文件（agent 只需要 SKILL.md）：

curl -fsSL https://footalytics.farvor.com/skill/SKILL.md -o SKILL.md

一键下载（zip，同样的文件）：footalytics-skill.zip

让 AI 自动安装

复制下面的 prompt 发给你的 AI 助手——它会自动完成安装：

Install the "Footalytics" skill for me.

1. Download these three files from https://footalytics.farvor.com/skill/ and save them in
   ~/.claude/skills/footalytics/ (create the folder if needed):
   - SKILL.md
   - README.md
   - README.zh-CN.md
   Use curl or any fetch tool, e.g.:
   curl -fsSL https://footalytics.farvor.com/skill/SKILL.md -o SKILL.md
2. Read the installed SKILL.md and follow its Setup section: check whether the
   FOOTALYTICS_API_KEY environment variable is set. If it is not, ask me to create
   a free key at https://footalytics.farvor.com/api-keys and help me set it
   (e.g. export FOOTALYTICS_API_KEY="fxk_...").
3. When done, confirm what you installed and ask me for a football match to
   predict as a test. Do NOT invent match probabilities yourself - always use
   the Footalytics API per the skill.

这段 prompt 只会让助手从本站拉取技能文件、放到正确目录并向你要 API key——不会执行其他操作。

署名

对外展示或引用结果时，请保留 “Predictions by Footalytics” 及站点链接。预测是统计概率，并非确定结果。