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:

1. Important upcoming matches + odds — from the 竞彩 (sports lottery) calculator on lottery.gov.cn (data served by webapi.sporttery.cn).
2. Search a team → its future fixtures with odds — filter the upcoming list by team name.
3. 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)
python football_tracker.py upcoming [--days N] [--league 联赛名] [--hot]

# Future fixtures + odds for one team
python football_tracker.py search 球队名

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

# ONE-PAGE view: future+odds AND past+win-rate combined  ← usually the best command
python football_tracker.py team 球队名 [--days 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 (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, advising a re-query with the precise name for accurate stats.

When results look "mixed", re-run with the exact club name shown in the warning.

Limitations

• 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).