Football Match Tracker (足球比赛 · 赔率 · 战绩)

Overview

A self-contained Python tool that aggregates two Chinese football data sources and answers the three questions the user cares about:

Important upcoming matches + odds — from the 竞彩 (sports lottery) calculator on lottery.gov.cn (data served by webapi.sporttery.cn).
Search a team → its future fixtures with odds — filter the upcoming list by team name.
Search a team → its past finished matches, records vs each opponent, and win rate — from zhibo8.com score data (served by the qiumibao JSON backend).

The tool is pure Python standard library (no pip install needed) and runs offline-after-fetch: every command hits the live endpoints at runtime.

When to use

"查一下关注的球队未来的比赛和赔率"
"查询任意球队最近战绩和胜率"
"今天/本周有什么竞彩足球比赛"
"查某场比赛场赔率多少" / "某天有哪些足球比赛"
竞彩、足彩、赔率、胜平负、总进球、比分、球队胜率、历史战绩.

Data sources

| Need | Source | Endpoint | |------|--------|----------| | Upcoming matches + all odds | 竞彩计算器 (lottery.gov.cn) | webapi.sporttery.cn/gateway/uniform/football/getMatchCalculatorV1.qry?channel=c&poolCode=had,hhad,ttg,crs,hafu | | Past results / scores | zhibo8 比分 (qiumibao backend) | https://bifen4pc.qiumibao.com/json/YYYY-MM-DD/list.htm |

注意： The lottery page is JS-rendered, so do not scrape the HTML. Use the JSON API above (the poolCode parameter is mandatory — without it the API returns only config and no matches). See references/api_reference.md for field maps.

Commands

Run from the scripts/ directory:

# Future matches + full odds (win/draw/loss, handicap, total goals, score, half/full)
# --league 支持简称 (西甲/英超/意甲/德甲/法甲/葡超/欧冠/欧联/中超/日职...)
# 查不到时会打印当前在售场次实际包含的联赛名
python football_tracker.py upcoming [--days N] [--league 联赛名] [--hot]

# Future fixtures + odds for one team
python football_tracker.py search 球队名 [--exact] [--scan N]

# Past finished matches, record vs each opponent, win rate (回溯默认30天, 最多45)
python football_tracker.py history 球队名 [--days N] [--exact]

# ONE-PAGE view: future+odds AND past+win-rate combined  ← usually the best command
python football_tracker.py team 球队名 [--days N] [--exact] [--scan N]

# All matches on a given date
python football_tracker.py matches YYYY-MM-DD

# Odds for a single fixture by its 竞彩编号 (e.g. 周三001)
python football_tracker.py odds 场次编号

For the user's described workflow ("search a team → future matches+odds and past record+win rate"), prefer the team command — it returns both halves in one shot.

Team-name matching & disambiguation

Chinese club names are inconsistent across sources (e.g. 竞彩 uses 巴黎圣日尔曼, zhibo8 uses 巴黎圣日尔曼; short keywords like "巴黎" also match 巴黎FC / 巴黎13区竞技 / women's teams). The tool therefore:

Uses substring matching by default (so "曼城" finds "曼彻斯特城" if present, and "巴黎" finds all Paris clubs).
Detects when a keyword matches multiple distinct clubs and prints a ⚠️ disambiguation list with exact full names.

⚠️ Re-running with the same name does NOT disambiguate — substring matching will return the identical mix. The only way to isolate one club is --exact, which requires the team name to be identical to the keyword:

python football_tracker.py team 皇家马德里 --exact        # 13 场, 一线队
python football_tracker.py team 皇家马德里                # 27 场, 混入女足/卡斯蒂利亚/C队

Rule of thumb: when the disambiguation warning appears and the user asked about a specific first team, re-run with --exact before reporting any win-rate number. A mixed 66.7% and a clean 84.6% are very different answers.

Limitations

Odds cover the next 1-2 days only. The lottery API returns only currently-selling matches (typically one day's batch). A team with no match on sale is not the same as a team with no upcoming match — say so explicitly instead of "no fixtures found". --scan N sweeps qiumibao N days ahead for fixtures (no odds), but that source only ingests schedules a few days out, so it can also come back empty.
History window: qiumibao returns ~45 days of score data; --days is capped at 45. Long-season win rates require paging across multiple runs or a date range.
Odds are pre-match only. The lottery API only exposes currently-selling (future) matches, so "past odds" are not available — only past results/scores.
Win rate is on finished matches with a final score only; in-progress and unplayed games are excluded.
Endpoints can rate-limit or go down on match days; the CLI catches HTTP/parse errors and prints a friendly message rather than crashing.

Files

scripts/football_tracker.py — the tool (all logic + CLI).
references/api_reference.md — endpoint details, pool-code mapping, and the exact JSON field paths used for odds and scores (read this before patching the parser).