{"id":4383,"date":"2026-10-01T10:00:00","date_gmt":"2026-10-01T10:00:00","guid":{"rendered":"https:\/\/oddspapi.io\/blog\/?p=4383"},"modified":"2026-09-22T13:47:07","modified_gmt":"2026-09-22T13:47:07","slug":"football-data-api-betting-predictions","status":"publish","type":"post","link":"https:\/\/oddspapi.io\/blog\/football-data-api-betting-predictions\/","title":{"rendered":"Football Data API: Grade Your Model on 250 Labelled Fixtures"},"content":{"rendered":"

A football model needs two things: prices to learn from and results to learn against. Most free feeds hand you one half. The stats feeds carry results and refresh their odds once a day. The odds feeds carry prices and drop the fixture at the final whistle.<\/p>\n

OddsPapi carries both on the free tier. \/v4\/historical-odds<\/code> replays every price snapshot a bookmaker posted, and \/v4\/scores<\/code> returns the finished score that labels it. This study runs them together over 250 finished fixtures from the top five European tournaments, played between 1 August and 21 September 2026 and measured on 22 September.<\/p>\n

The headline: all 250 fixtures returned a full-time score<\/strong>, and the de-vigged Pinnacle closing line named the winner on 52.2% of the 249 with a complete closing three-way<\/strong>. Its Brier score of 0.5778 is the number your model has to beat. If you have never run a backtest against price history, start with the walkthrough<\/a> and come back when your pipeline runs.<\/p>\n

Why “free football data API” usually means half a dataset<\/h2>\n

Search that phrase and you meet two kinds of product. One sells fixtures, lineups and results, then bolts on a pre-match odds field that updates daily. The other sells live prices from a handful of books and forgets the fixture once it finishes. Train on the first and your features are stale. Train on the second and you have nothing to train against.<\/p>\n

The label is the expensive half. You can approximate a price from a competitor. You cannot approximate whether Arsenal won.<\/p>\n

\n\n\n\n\n\n\n\n\n\n\n
What a model needs<\/th>\nWhere it comes from<\/th>\nMeasured on this sample<\/th>\n<\/tr>\n<\/thead>\n
Full-time result label<\/td>\n\/v4\/scores<\/code>, periods.result<\/code><\/td>\n250 of 250 fixtures<\/td>\n<\/tr>\n
Half-time result label<\/td>\n\/v4\/scores<\/code>, periods.p1<\/code><\/td>\n250 of 250 fixtures<\/td>\n<\/tr>\n
Price feature<\/td>\n\/v4\/historical-odds<\/code>, market 101<\/td>\n249 complete closing three-ways<\/td>\n<\/tr>\n
Closing price<\/td>\nLast active snapshot before kick-off<\/td>\nMedian 32 seconds before kick-off<\/td>\n<\/tr>\n
Margin to strip<\/td>\nSum of the implied probabilities<\/td>\nMedian 2.89% on Pinnacle<\/td>\n<\/tr>\n
Stake size behind the price<\/td>\nlimit<\/code> on each snapshot<\/td>\nMedian 10,000 at the close<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n

Step 1: pull the finished fixtures<\/h2>\n

Filter \/v4\/fixtures<\/code> on tournamentId<\/code>. The filter is undocumented, it works, and it lifts the ten-day range cap that sportId<\/code> alone runs into. Premier League is 17, LaLiga 8, Serie A 23, Bundesliga 35 and Ligue 1 34. Resolve those IDs on name plus category if you build the list yourself, because 35 tournaments in the catalogue are called “Premier League”.<\/p>\n

import os, time, requests\n\nAPI_KEY = os.environ[\"ODDSPAPI_API_KEY\"]\nBASE = \"https:\/\/api.oddspapi.io\/v4\"\n\nTOURNAMENTS = {17: \"Premier League\", 8: \"LaLiga\", 23: \"Serie A\",\n               35: \"Bundesliga\", 34: \"Ligue 1\"}\n\ndef get(path, **params):\n    \"\"\"One call, with the 429 backoff the API asks for.\"\"\"\n    params[\"apiKey\"] = API_KEY\n    for attempt in range(5):\n        r = requests.get(f\"{BASE}\/{path}\", params=params, timeout=180)\n        if r.status_code == 429:\n            time.sleep(float(r.json()[\"error\"].get(\"retryMs\", 3000)) \/ 1000 + 1)\n            continue\n        r.raise_for_status()\n        return r.json()\n    raise RuntimeError(f\"rate limited on \/{path}\")\n\ndef finished_fixtures(tournament_id, start, end):\n    rows = get(\"fixtures\", sportId=10, tournamentId=tournament_id,\n               **{\"from\": start, \"to\": end})\n    return [f for f in rows if f[\"statusName\"] == \"Finished\"]\n\nfixtures = []\nfor tid, name in TOURNAMENTS.items():\n    rows = finished_fixtures(tid, \"2026-08-01\", \"2026-09-22\")\n    print(f\"{name}: {len(rows)} finished\")\n    fixtures += rows\n    time.sleep(1.3)\n<\/code><\/pre>\n
Premier League: 50 finished\nLaLiga: 69 finished\nSerie A: 50 finished\nBundesliga: 36 finished\nLigue 1: 45 finished\n<\/code><\/pre>\n
Set to<\/code> to the day after the last day you want. It is a midnight-UTC instant, so a same-day query returns only the fixtures that start at 00:00Z. Finished fixtures come back with hasOdds: false<\/code>, because the live board is gone. Their price history stays queryable, which is the reason this study runs on a free key at all. For the live side of the same endpoint, see the soccer fixtures guide<\/a>.<\/p>\n
The get<\/code> helper earns its place on the first run. A 1.1-second gap between \/fixtures<\/code> calls still drew a 429 on the second tournament, and the error body carries a retryMs<\/code> that tells you exactly how long to wait.<\/p>\n
Step 2: label every fixture from \/v4\/scores<\/h2>\n
The scores endpoint nests under scores.periods<\/code>, not a top-level periods<\/code> key. Soccer returns three keys: p1<\/code> holds the half-time score, fulltime<\/code> the ninety-minute score, and result<\/code> the final score. On league football the last two agree. On a tie that goes to extra time they diverge, so read result<\/code> for the settled outcome and fulltime<\/code> for the ninety-minute one.<\/p>\n
def label(fixture_id):\n    periods = get(\"scores\", fixtureId=fixture_id)[\"scores\"][\"periods\"]\n    full = periods[\"result\"]\n    home, away = full[\"participant1Score\"], full[\"participant2Score\"]\n    half = periods[\"p1\"]\n    return {\n        \"full\": \"H\" if home > away else (\"A\" if away > home else \"D\"),\n        \"half\": \"H\" if half[\"participant1Score\"] > half[\"participant2Score\"]\n                else (\"A\" if half[\"participant2Score\"] > half[\"participant1Score\"] else \"D\"),\n        \"score\": (home, away),\n    }\n\nprint(label(fixtures[0][\"fixtureId\"]))\n<\/code><\/pre>\n
{'full': 'H', 'half': 'H', 'score': (3, 0)}\n<\/code><\/pre>\n
All 250 fixtures returned a score, with no retries and no errors. The outcome split came out 43.2% home, 24.8% draw, 32.0% away<\/strong>. That split is your first baseline. A model that predicts the season base rate every week scores a Brier of 0.6486, and anything worse than that carries no information.<\/p>\n
\n\n\n\n\n\n\n\n\n\n
Tournament<\/th>\nFixtures<\/th>\nHome<\/th>\nDraw<\/th>\nAway<\/th>\n<\/tr>\n<\/thead>\n
Premier League<\/td>\n50<\/td>\n36.0%<\/td>\n32.0%<\/td>\n32.0%<\/td>\n<\/tr>\n
LaLiga<\/td>\n69<\/td>\n44.9%<\/td>\n24.6%<\/td>\n30.4%<\/td>\n<\/tr>\n
Serie A<\/td>\n50<\/td>\n44.0%<\/td>\n18.0%<\/td>\n38.0%<\/td>\n<\/tr>\n
Bundesliga<\/td>\n36<\/td>\n52.8%<\/td>\n19.4%<\/td>\n27.8%<\/td>\n<\/tr>\n
Ligue 1<\/td>\n45<\/td>\n40.0%<\/td>\n28.9%<\/td>\n31.1%<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n
Six weeks is a small window, and the spread across tournaments shows it. Bundesliga home sides won 52.8% and Premier League home sides won 36.0%. Pull a full season before you treat any of those five rows as a prior.<\/p>\n
The half-time key earns its place too. Someone led at the break in 149 of the 250 fixtures, and that side failed to win 40 of them, 26.8%<\/strong>. Train a half-time model on p1<\/code> and grade it on result<\/code>, and the same two calls give you a second dataset.<\/p>\n
Step 3: pull the closing price as your feature<\/h2>\n
\/v4\/historical-odds<\/code> takes three bookmaker slugs per call and returns every snapshot each one posted. This study reads Pinnacle alone, because Pinnacle is the sharpest anchor in the top tier and its closing line is the standard benchmark. A wider consensus shifts the number: a 3-book closing line sits 0.67 percentage points from a 176-book one, measured in the book-count study<\/a>.<\/p>\n
Two traps live in this call. The historical endpoint’s top-level key is bookmakers<\/code>, where the live endpoint uses bookmakerOdds<\/code>. And players[\"0\"]<\/code> holds a list of snapshots here, where the live endpoint makes it a dict.<\/p>\n
LEGS = {\"101\": \"H\", \"102\": \"D\", \"103\": \"A\"}   # market 101 = Full Time Result\n\ndef closing_1x2(fixture_id, start_time, book=\"pinnacle\"):\n    data = get(\"historical-odds\", fixtureId=fixture_id, bookmakers=book)\n    market = data[\"bookmakers\"][book][\"markets\"].get(\"101\")\n    if not market:\n        return None\n    prices = {}\n    for outcome_id, leg in LEGS.items():\n        snaps = market[\"outcomes\"][outcome_id][\"players\"][\"0\"]\n        pre = [s for s in snaps if s[\"createdAt\"] < start_time and s[\"active\"]]\n        if not pre:\n            return None\n        prices[leg] = max(pre, key=lambda s: s[\"createdAt\"])[\"price\"]\n    return prices\n\nf = fixtures[0]\nprint(f[\"participant1Name\"], \"v\", f[\"participant2Name\"], f[\"startTime\"])\nprint(closing_1x2(f[\"fixtureId\"], f[\"startTime\"]))\n<\/code><\/pre>\n
Arsenal FC v Coventry City 2026-08-21T19:00:00.000Z\n{'H': 1.21, 'D': 7.15, 'A': 16.0}\n<\/code><\/pre>\n
Both filters matter. Snapshots keep arriving after kick-off, and a suspended price sits in the list with its last number and an active<\/code> flag of false. Skip the filters and you grade your model against an in-play price. Across the 249 fixtures with a complete closing three-way, the last active snapshot landed a median 32 seconds before kick-off<\/strong>, with the tenth percentile at 7 seconds and the ninetieth at 195.<\/p>\n
One fixture of the 250 returned 404 from \/historical-odds<\/code>. Catch the error and move on rather than letting it kill the loop.<\/p>\n
Step 4: strip the margin<\/h2>\n
The three closing prices imply more than 100% probability. The excess is the bookmaker’s margin, and it has to come out before the number means anything. Proportional de-vig divides each implied probability by the total. The power method raises each one to a common exponent, which takes more weight off the longshot.<\/p>\n
def fair_proportional(prices):\n    implied = {leg: 1 \/ price for leg, price in prices.items()}\n    total = sum(implied.values())\n    return {leg: p \/ total for leg, p in implied.items()}, total - 1\n\ndef brier(probs, actual):\n    return sum((probs[leg] - (1 if actual == leg else 0)) ** 2 for leg in \"HDA\")\n\nprices = closing_1x2(f[\"fixtureId\"], f[\"startTime\"])\nfair, overround = fair_proportional(prices)\nprint({k: round(v, 4) for k, v in fair.items()}, f\"overround {overround:.2%}\")\n<\/code><\/pre>\n
{'H': 0.8033, 'D': 0.1359, 'A': 0.0608} overround 2.88%\n<\/code><\/pre>\n
Pinnacle’s median closing overround across the sample was 2.89%<\/strong>, inside a range of 2.26% to 5.14%. Pinnacle also publishes a stake limit<\/code> on every snapshot, and the median closing limit was 10,000. Most books leave that field null, so check it before you do arithmetic on it.<\/p>\n
What the closing line scores<\/h2>\n
Run the loop over all 249 fixtures and grade the de-vigged closing probabilities against the labels. Lower is better on both scores.<\/p>\n
\n\n\n\n\n\n\n\n\n
Predictor<\/th>\nBrier score<\/th>\nLog loss<\/th>\nFavourite correct<\/th>\n<\/tr>\n<\/thead>\n
Season base rate (43.2 \/ 24.8 \/ 32.0)<\/td>\n0.6486<\/td>\n1.0717<\/td>\n43.4%<\/td>\n<\/tr>\n
Pinnacle opening line<\/td>\n0.5875<\/td>\n0.9867<\/td>\n50.2%<\/td>\n<\/tr>\n
Pinnacle closing line<\/strong><\/td>\n0.5778<\/strong><\/td>\n0.9710<\/strong><\/td>\n52.2%<\/strong><\/td>\n<\/tr>\n
Closing line, power de-vig<\/td>\n0.5776<\/td>\n0.9701<\/td>\n52.2%<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n
The closing line beat the opening line by 1.7% on Brier and 1.6% on log loss<\/strong>, and it converted five more favourites over the same 249 fixtures. Weeks of money moved the price that far. The gap between the base rate and the close is larger: 10.9% on Brier<\/strong>. That gap is the whole value of knowing anything about the fixture, and your model has to clear it before it clears the margin.<\/p>\n
The two de-vig methods finished within 0.0002 of each other on Brier. Pick either one and stay consistent. The choice matters more on three-way markets with a wide margin, where the tie leg moves by more than a point between methods.<\/p>\n
The closing line is well calibrated<\/h3>\n
Bucket every de-vigged probability and compare it against how often that outcome happened. Each fixture contributes three legs, so 249 fixtures give 747 rows.<\/p>\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Predicted band<\/th>\nLegs<\/th>\nMean predicted<\/th>\nRealised<\/th>\n<\/tr>\n<\/thead>\n
0.0 to 0.1<\/td>\n28<\/td>\n6.5%<\/td>\n0.0%<\/td>\n<\/tr>\n
0.1 to 0.2<\/td>\n106<\/td>\n15.6%<\/td>\n17.9%<\/td>\n<\/tr>\n
0.2 to 0.3<\/td>\n271<\/td>\n25.7%<\/td>\n26.9%<\/td>\n<\/tr>\n
0.3 to 0.4<\/td>\n136<\/td>\n33.8%<\/td>\n30.1%<\/td>\n<\/tr>\n
0.4 to 0.5<\/td>\n85<\/td>\n44.7%<\/td>\n48.2%<\/td>\n<\/tr>\n
0.5 to 0.6<\/td>\n59<\/td>\n54.6%<\/td>\n44.1%<\/td>\n<\/tr>\n
0.6 to 0.7<\/td>\n29<\/td>\n65.1%<\/td>\n69.0%<\/td>\n<\/tr>\n
0.7 to 0.8<\/td>\n20<\/td>\n74.9%<\/td>\n80.0%<\/td>\n<\/tr>\n
0.8 to 0.9<\/td>\n11<\/td>\n82.7%<\/td>\n100.0%<\/td>\n<\/tr>\n
0.9 to 1.0<\/td>\n2<\/td>\n91.6%<\/td>\n100.0%<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n
The three fullest bands track their predictions within 1.3 percentage points. The 0.5 to 0.6 band came in ten points light on 59 legs, which is the size of gap six weeks of football produces by chance. Run the same table over a full season before you read a bias into any single row.<\/p>\n
The full loop<\/h2>\n
Two calls per fixture, one sleep each, and the whole study fits on a free key.<\/p>\n
import json\n\nrows = []\nfor f in fixtures:\n    fid, start = f[\"fixtureId\"], f[\"startTime\"]\n    try:\n        prices = closing_1x2(fid, start)\n        time.sleep(4.6)              # \/historical-odds needs the wider gap\n        if not prices:\n            continue\n        y = label(fid)\n        time.sleep(1.3)\n    except (requests.HTTPError, RuntimeError):\n        continue\n    fair, overround = fair_proportional(prices)\n    rows.append({\"fixtureId\": fid, \"tournament\": f[\"tournamentName\"],\n                 \"closing\": prices, \"fair\": fair, \"overround\": overround,\n                 \"result\": y[\"full\"], \"half\": y[\"half\"], \"score\": y[\"score\"]})\n\njson.dump(rows, open(\"labelled.json\", \"w\"), indent=1)\nprint(len(rows), \"labelled fixtures\")\nprint(\"closing-line Brier:\",\n      round(sum(brier(r[\"fair\"], r[\"result\"]) for r in rows) \/ len(rows), 4))\n<\/code><\/pre>\n
Sleep 4.6 seconds after a successful \/historical-odds<\/code> call and about 1.3 seconds elsewhere. Concurrency gets almost everything rate limited, whatever the worker count. Retry a failed batch once, one slug at a time. The 250-fixture run above took 25 minutes and returned 249 usable rows.<\/p>\n
Where to take it next<\/h2>\n
You now hold features and labels in one file, which used to need two vendors. Three directions from here:<\/p>\n
    \n
  • Beat the close.<\/strong> Grade your own probabilities against 0.5778. Anything above that is worse than reading the market.<\/li>\n
  • Add books.<\/strong> Pinnacle is one opinion out of 350+ in the catalogue. Walk it three slugs at a time, deduplicate on the price tuple, and check your team ratings<\/a> against the consensus.<\/li>\n
  • Add markets.<\/strong> Market 101 is the three-way. The same call carries totals, Asian handicaps and correct score, which is how you reconstruct the score distribution<\/a>.<\/li>\n<\/ul>\n
    When you want to run the model forward instead of backward, the WebSocket feed pushes the live board under the same market IDs. For the live pre-match board on these five tournaments, see the football odds API guide<\/a>.<\/p>\n
    FAQ<\/h2>\n
    Does the OddsPapi free tier include match results?<\/h3>\n
    Yes. \/v4\/scores<\/code> returns p1<\/code>, fulltime<\/code> and result<\/code> for a finished fixture. All 250 top-five-league fixtures tested on 22 September 2026 returned a full-time score.<\/p>\n
    How far back does the free price history go?<\/h3>\n
    About eight months on Premier League fixtures. A January 2026 fixture still replays, and earlier ones return 404. Retention reaches deeper than one season on the tournaments tested.<\/p>\n
    Which market ID is the 1X2 in soccer?<\/h3>\n
    Market 101<\/code>, Full Time Result, with outcomes 101 home, 102 draw and 103 away. Resolve names from \/v4\/markets<\/code> rather than hardcoding a set, because the same bet ships under more than one ID in several sports.<\/p>\n
    How accurate is a bookmaker closing line at predicting football results?<\/h3>\n
    Across 249 top-five-league fixtures played between 1 August and 21 September 2026, the de-vigged Pinnacle closing line scored a Brier of 0.5778 and named the winner 52.2% of the time. The season base rate scored 0.6486 and 43.4%.<\/p>\n
    Can one API supply both features and labels?<\/h3>\n
    Yes. \/v4\/historical-odds<\/code> supplies the price features and \/v4\/scores<\/code> supplies the labels, on the same fixture ID and the same free key. Two calls per fixture.<\/p>\n
    What is the difference between the fulltime and result period keys?<\/h3>\n
    On soccer, fulltime<\/code> holds the ninety-minute score and result<\/code> holds the settled final score. They agree on league football and diverge on a tie decided in extra time, so grade ninety-minute markets on fulltime<\/code>.<\/p>\n
    Get the data<\/h2>\n
    The free key covers 69 sports, 350+ bookmakers in the catalogue and the full price history used above. Get a free API key<\/a> and run the loop on your own tournament list. If you want the wider board instead of one sharp book, the free odds API guide<\/a> covers catalogue discovery.<\/p>\n