{"id":58,"date":"2025-11-25T18:27:17","date_gmt":"2025-11-25T18:27:17","guid":{"rendered":"https:\/\/oddspapi.io\/blog\/?p=58"},"modified":"2026-07-28T20:50:01","modified_gmt":"2026-07-28T20:50:01","slug":"free-nfl-odds-api-guide","status":"publish","type":"post","link":"https:\/\/oddspapi.io\/blog\/free-nfl-odds-api-guide\/","title":{"rendered":"NFL Odds API: Free Python Guide to Lines, Spreads & Totals (2026)"},"content":{"rendered":"

Fetch live NFL moneylines, spreads and totals in Python from 16 sportsbooks, including Pinnacle and SBOBet, on a free API key. Every code block and every number on this page ran against the live feed before it was published.<\/p>\n

If you are building a betting model, a line-movement tracker, an arbitrage calculator<\/a> or a props screener, you have hit the same wall everyone hits. NFL odds data is either priced for enterprise buyers (Sportradar, Genius) or capped at a dozen retail books that all copy the same opening number. Neither gives you what you need, which is the sharp price next to the soft price.<\/p>\n

This guide fixes that. It also fixes the mistake that breaks most NFL scripts on day one: hardcoded market IDs.<\/p>\n

What the NFL feed looks like right now<\/h2>\n

Numbers pulled live on 28 July 2026, six weeks before kickoff:<\/p>\n

\n\n\n\n\n\n\n\n
Window<\/th>\nFixtures with odds<\/th>\nDepth<\/th>\n<\/tr>\n<\/thead>\n
NFL Preseason, from 6 Aug<\/td>\n10<\/td>\nOpener carries 14 books including Pinnacle, SBOBet, Kalshi and Polymarket<\/td>\n<\/tr>\n
NFL Week 1, 10 to 13 Sep<\/td>\n14 (all of them)<\/td>\n16 books, 28 to 31 distinct markets per game<\/td>\n<\/tr>\n
NCAA, 5 to 14 Sep<\/td>\n51<\/td>\n14 books, SBOBet the only sharp so far<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n

Lines are already live and moving. You do not have to wait for September to build against real data.<\/p>\n

NFL odds API providers compared<\/h2>\n
\n\n\n\n\n\n\n\n\n
Provider<\/th>\nBookmakers<\/th>\nSharp books<\/th>\nHistorical odds<\/th>\nFree tier<\/th>\n<\/tr>\n<\/thead>\n
OddsPapi<\/strong><\/td>\n350+ (381 live)<\/td>\nPinnacle, SBOBet, Circa, exchanges<\/td>\nYes, free<\/td>\nYes<\/td>\n<\/tr>\n
The Odds API<\/td>\n~15 US books<\/td>\nPinnacle<\/td>\nPaid add-on<\/td>\nYes, capped<\/td>\n<\/tr>\n
SportsDataIO<\/td>\n~10 books<\/td>\nNo<\/td>\nLimited<\/td>\nTrial only<\/td>\n<\/tr>\n
Sportradar<\/td>\nEnterprise<\/td>\nYes<\/td>\nYes<\/td>\nNone<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n

The difference that matters for NFL: retail books shade their lines toward public money, so a feed made only of DraftKings, FanDuel and BetMGM shows you the same shaded number three times. Pinnacle priced our Week 1 test game at 3.18% vig against Bet365’s 4.40%. You need both sides of that to know what anything is worth.<\/p>\n

Terminology: US sports on a global feed<\/h2>\n
\n\n\n\n\n\n\n\n\n\n\n
US concept<\/th>\nAPI term<\/th>\nWhat to watch for<\/th>\n<\/tr>\n<\/thead>\n
League<\/td>\ntournament<\/code><\/td>\nNFL is tournamentId<\/code> 31 inside sport 14<\/td>\n<\/tr>\n
Game<\/td>\nfixture<\/code><\/td>\nEverything keys off fixtureId<\/code><\/td>\n<\/tr>\n
Team<\/td>\nparticipant<\/code><\/td>\nparticipant1Name<\/code> and participant2Name<\/code><\/td>\n<\/tr>\n
Moneyline<\/td>\nMarket 141<\/code><\/td>\nStable. Outcomes 141 and 142<\/td>\n<\/tr>\n
Spread<\/td>\nHandicap markets<\/td>\nOne market ID per line.<\/strong> -3.5 is a different ID from -4<\/td>\n<\/tr>\n
Total<\/td>\nTotal markets<\/td>\nOne market ID per line.<\/strong> 44.5 is a different ID from 45<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n

The last two rows are where scripts break. There is no single “spreads” endpoint or single totals market ID. Read on.<\/p>\n

Step 1: Authenticate and find the NFL<\/h2>\n

The API key goes in the query string, not a header. That means you can paste any of these URLs straight into a browser to check them.<\/p>\n

import time\nimport requests\n\nAPI_KEY = \"YOUR_API_KEY\"\nBASE_URL = \"https:\/\/api.oddspapi.io\/v4\"\nNFL_SPORT_ID = 14\n\n\ndef api(path, **params):\n    \"\"\"GET with the retry the free tier expects.\"\"\"\n    for _ in range(4):\n        r = requests.get(f\"{BASE_URL}\/{path}\",\n                         params={\"apiKey\": API_KEY, **params})\n        body = r.json()\n        if r.status_code == 200 and not (isinstance(body, dict) and body.get(\"error\")):\n            return body\n        wait = (body.get(\"error\") or {}).get(\"retryMs\", 2000) \/ 1000\n        time.sleep(wait + 0.3)\n    raise RuntimeError(f\"{path} kept rate-limiting\")\n\n\ndef find_tournament(name):\n    for t in api(\"tournaments\", sportId=NFL_SPORT_ID):\n        if t[\"tournamentName\"] == name:\n            return t\n\n\nnfl = find_tournament(\"NFL\")\nprint(nfl[\"tournamentId\"], nfl[\"futureFixtures\"])   # 31 105\n<\/code><\/pre>\n
Rate limits are per endpoint and return a real HTTP 429 with a retryMs<\/code> value in the body. Sleep about a second between calls to the same endpoint and honour retryMs<\/code> when you see it. Do not thread these calls. Firing twelve concurrent requests at \/odds<\/code> gets eleven of them rejected.<\/p>\n
Step 2: Pull the schedule<\/h2>\n
The from<\/code> and to<\/code> parameters accept a maximum ten-day span. Filter on hasOdds<\/code> so you never waste an odds call on a game nobody has priced.<\/p>\n
def nfl_games(start, end):\n    games = api(\"fixtures\", sportId=NFL_SPORT_ID, **{\"from\": start, \"to\": end})\n    return [g for g in games\n            if g.get(\"hasOdds\") and g.get(\"tournamentName\") == \"NFL\"]\n\n\ngames = nfl_games(\"2026-09-05\", \"2026-09-14\")\ng = games[0]\nprint(g[\"participant1Name\"], \"v\", g[\"participant2Name\"], g[\"fixtureId\"])\n# Seattle Seahawks v New England Patriots id1400003171515752\n<\/code><\/pre>\n
Filtering on tournamentName<\/code> matters in September, when the same sport ID also carries 551 NCAA fixtures and the CFL.<\/p>\n
Step 3: Parse the moneyline<\/h2>\n
The odds payload nests four levels deep: bookmaker, market, outcome, then a players<\/code> dict holding the price. On game lines the players key is always \"0\"<\/code>.<\/p>\n
def prices(odds, market_id):\n    \"\"\"{bookmaker: {outcome_id: price_object}} for one market.\"\"\"\n    out = {}\n    for slug, book in odds.get(\"bookmakerOdds\", {}).items():\n        market = book.get(\"markets\", {}).get(str(market_id))\n        if not market:\n            continue\n        row = {}\n        for outcome_id, outcome in market[\"outcomes\"].items():\n            p = outcome[\"players\"].get(\"0\")\n            if p and p.get(\"active\") is not False:\n                row[outcome_id] = p\n        if row:\n            out[slug] = row\n    return out\n\n\ndef american(dec):\n    return f\"+{round((dec - 1) * 100)}\" if dec >= 2 else f\"{round(-100 \/ (dec - 1))}\"\n\n\nodds = api(\"odds\", fixtureId=g[\"fixtureId\"])\nfor slug, row in sorted(prices(odds, 141).items(), key=lambda kv: kv[1][\"141\"][\"price\"]):\n    p1, p2 = row[\"141\"][\"price\"], row[\"142\"][\"price\"]\n    print(f\"{slug:18} {american(p1):>5} \/ {american(p2)}\")\n<\/code><\/pre>\n
Real output from Seahawks at Patriots, fifteen books deep:<\/p>\n
betparx              -233 \/ +185\nballybet             -233 \/ +185\nfourwinds            -233 \/ +185\nbetrivers            -233 \/ +180\nhardrockbet          -210 \/ +165\npinnacle             -206 \/ +179\nbet365               -200 \/ +165\nbetmgm               -200 \/ +165\nborgata              -200 \/ +165\ncaesars              -200 \/ +166\nwilliamhill          -200 \/ +166\npointsbet.com.au     -200 \/ +165\ndraftkings           -192 \/ +160\ncircasports          -190 \/ +165\nkalshi               -186 \/ +178\n<\/code><\/pre>\n
Two things to take from that list. Seattle ranges from -233 to -186 across fifteen books, so shopping the same side is worth roughly 7.6% on price. And those fifteen slugs are only nine independent opinions: betparx<\/code>, ballybet<\/code> and fourwinds<\/code> quote identical numbers, as do betmgm<\/code> and borgata<\/code>, and caesars<\/code> and williamhill<\/code>. Dedupe on the price tuple before you average anything or you will triple-weight one trading desk.<\/p>\n
The feed also ships priceAmerican<\/code> and priceFractional<\/code> on every outcome, so the converter above is optional. Write it once if you want the control, skip it if you do not.<\/p>\n
Step 4: Spreads, and why hardcoding market IDs fails<\/h2>\n
NFL spreads live in Handicap markets, and every line is a separate market ID. There is no fixed ID for “the spread”. A guide that tells you to fetch market 1076 for -3.5 is quoting soccer IDs and will hand you an empty dict on every NFL game.<\/p>\n
Build the index from \/markets<\/code> instead, then ask the fixture which lines are actually quoted:<\/p>\n
def market_index(sport_id):\n    catalog = api(\"markets\", sportId=sport_id)\n    by_id = {m[\"marketId\"]: (m[\"marketName\"], m.get(\"handicap\")) for m in catalog}\n    outcomes = {(m[\"marketId\"], o[\"outcomeId\"]): o[\"outcomeName\"]\n                for m in catalog for o in m.get(\"outcomes\", [])}\n    return by_id, outcomes\n\n\ndef find_market(odds, by_id, name):\n    \"\"\"Which lines are on the board, and how many books quote each.\"\"\"\n    hits = {}\n    for slug, book in odds.get(\"bookmakerOdds\", {}).items():\n        for mid in book.get(\"markets\", {}):\n            label, handicap = by_id.get(int(mid), (\"\", None))\n            if label == name:\n                hits.setdefault((int(mid), handicap), []).append(slug)\n    return dict(sorted(hits.items(), key=lambda kv: -len(kv[1])))\n\n\nby_id, outcome_names = market_index(NFL_SPORT_ID)\nfor (mid, line), books in find_market(odds, by_id, \"Handicap (incl. overtime)\").items():\n    print(f\"market {mid:<7} line {line:>6}  {len(books)} books\")\n<\/code><\/pre>\n
market 14272   line   -3.5  7 books\nmarket 14270   line     -4  3 books\nmarket 14302   line      4  3 books\nmarket 14300   line    3.5  2 books\nmarket 14268   line   -4.5  2 books\nmarket 14244   line  -10.5  1 books\nmarket 14266   line     -5  1 books\nmarket 14262   line     -6  1 books\nmarket 14274   line     -3  1 books\nmarket 14264   line   -5.5  1 books\n<\/code><\/pre>\n
The consensus line is -3.5 on seven books. Everything below it is Pinnacle alone, walking its alternate ladder out to -10.5. The book with the most lines on the board is the one that will take a bet on any of them, which tells you something before you have priced anything yourself.<\/p>\n
Sort by book count and take the top entry and you have the main line, without hardcoding a thing. That pattern survives a season of line moves.<\/p>\n
Step 5: Totals work the same way<\/h2>\n
for (mid, line), books in find_market(odds, by_id, \"Total (incl. overtime)\").items():\n    if len(books) >= 2:\n        print(f\"market {mid:<7} total {line:>6}  {len(books)} books\")\n\n# market 1464    total   44.5  12 books   <- main line\n# market 1466    total     45   5 books\n# market 1432    total   36.5   3 books\n# market 1460    total   43.5   3 books\n<\/code><\/pre>\n
Market 1464 carries Over as outcome 1464 and Under as 1465. Line shop it and the spread across books is real money:<\/p>\n
totals = prices(odds, 1464)\nfor side, label in ((\"1464\", \"Over 44.5\"), (\"1465\", \"Under 44.5\")):\n    quotes = sorted(((s, r[side][\"price\"]) for s, r in totals.items() if side in r),\n                    key=lambda x: -x[1])\n    print(f\"{label}: best {quotes[0][1]} @ {quotes[0][0]}, worst {quotes[-1][1]} @ {quotes[-1][0]}\")\n\n# Over 44.5:  best 2.02 @ pinnacle,  worst 1.9 @ draftkings\n# Under 44.5: best 1.91 @ betmgm,    worst 1.819 @ pinnacle\n<\/code><\/pre>\n
Pinnacle is the best price on the Over and the worst on the Under, which is what a low-margin book looks like when its number sits slightly off the retail consensus. Taking the best of each side across books beats any single book on both. For the full version of this across every market, see our guide to line shopping in Python<\/a>.<\/p>\n
Step 6: Measure the vig<\/h2>\n
Sum the inverse decimal prices on both sides. Anything above 1.0 is the book’s margin.<\/p>\n
ml = prices(odds, 141)\nfor slug in (\"pinnacle\", \"draftkings\", \"bet365\", \"caesars\"):\n    if slug in ml:\n        p1, p2 = ml[slug][\"141\"][\"price\"], ml[slug][\"142\"][\"price\"]\n        print(f\"{slug:12} vig {(1\/p1 + 1\/p2 - 1) * 100:.2f}%\")\n\n# pinnacle     vig 3.18%\n# draftkings   vig 4.25%\n# caesars      vig 4.26%\n# bet365       vig 4.40%\n<\/code><\/pre>\n
Strip that margin out and you get the market’s honest probability, which is the benchmark any model has to beat. Three ways to do it are in our no-vig odds guide<\/a>.<\/p>\n
Step 7: Check the limit before you trust the price<\/h2>\n
Pinnacle and the exchanges publish a limit<\/code> on every outcome, which is the maximum they will accept. It doubles as a confidence signal, and in July the NFL numbers are small:<\/p>\n
\n\n\n\n\n\n\n\n\n
Market<\/th>\nPrice<\/th>\nPinnacle limit<\/th>\n<\/tr>\n<\/thead>\n
Moneyline, Seattle<\/td>\n1.485<\/td>\n$1,546<\/td>\n<\/tr>\n
Moneyline, New England<\/td>\n2.79<\/td>\n$750<\/td>\n<\/tr>\n
Spread -3.5, Seattle<\/td>\n1.877<\/td>\n$1,710<\/td>\n<\/tr>\n
Spread -3.5, New England<\/td>\n1.99<\/td>\n$1,515<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n
Pinnacle will take more than twice as much on the spread as on the moneyline, and it caps a live MLB moneyline at eight thousand dollars while capping this one at fifteen hundred. Six weeks out, the sharpest book in the market is telling you it does not trust its own September number yet. Those limits climb as kickoff approaches. US retail books return null<\/code> here, because their maximum is set per account rather than per market, so null-check before you do arithmetic.<\/p>\n
Step 8: Historical odds and closing line value<\/h2>\n
Every price the feed has ever seen is retrievable through \/historical-odds<\/code>, on the free tier. Competitors charge for this or do not offer it.<\/p>\n
def price_history(fixture_id, book, market_id, outcome_id):\n    data = api(\"historical-odds\", fixtureId=fixture_id, bookmakers=book)\n    market = data[\"bookmakers\"][book][\"markets\"][str(market_id)]\n    snaps = market[\"outcomes\"][str(outcome_id)][\"players\"][\"0\"]\n    return [(s[\"createdAt\"][:16], s[\"price\"], s.get(\"limit\")) for s in snaps]\n<\/code><\/pre>\n
Note the shape change: the live endpoint keys on bookmakerOdds<\/code> and gives you one price, the historical endpoint keys on bookmakers<\/code> and gives you a list of snapshots. Mixing them up is the second most common NFL parsing bug after the market IDs. The endpoint takes a maximum of three bookmakers per call, so loop and merge for wider coverage. From there you have opening lines, closing lines, and everything between, which is all you need to grade your bets against the close or export a season to CSV<\/a> for backtesting.<\/p>\n
Player props: where things stand<\/h2>\n
The NFL prop markets exist in the catalog, including Player To Score TD (market 14388) and Player To Score First TD (14390). Pricing is a different question. Across six Week 1 games sampled in late July, DraftKings had an anytime touchdown market on two of them and no other book had posted a single prop.<\/p>\n
That is normal. Prop menus fill in as kickoff approaches, so a scan six weeks out reads empty and the same scan on game day returns a full board. When they do arrive, the parse changes: on prop markets the players<\/code> dict is keyed by player ID rather than \"0\"<\/code>, with a playerName<\/code> on each entry in “Last, First” format. Hardcode players[\"0\"]<\/code> and every prop market will look empty to you. Our player props API guide<\/a> has the full pattern.<\/p>\n
College football<\/h2>\n
Same sport ID, same code, different tournament. NCAA carried 51 priced fixtures for the 5 to 14 September window when we checked, across 14 books, with up to 90 markets on the bigger matchups. Pinnacle had not posted yet and SBOBet was the only sharp on the board, so treat early college numbers as retail consensus rather than a sharp reference. Swap the filter and everything else in this guide runs unchanged:<\/p>\n
ncaa = [g for g in api(\"fixtures\", sportId=14, **{\"from\": \"2026-09-05\", \"to\": \"2026-09-14\"})\n        if g.get(\"hasOdds\") and g[\"tournamentName\"].startswith(\"NCAA\")]\n<\/code><\/pre>\n
Frequently Asked Questions<\/h2>\n
What is the market ID for NFL spreads?<\/h3>\n
There is no single one. Each spread line is its own market ID, so -3.5 and -4 are different markets. On our Week 1 test game, -3.5 was market 14272 and -4 was 14270. Query \/markets?sportId=14<\/code>, match on the market name “Handicap (incl. overtime)”, and pick the line the most books are quoting rather than hardcoding an ID.<\/p>\n
Which bookmakers does the NFL odds API cover?<\/h3>\n
A Week 1 fixture returned 16 books: Pinnacle, SBOBet, DraftKings, BetMGM, Caesars, Bet365, BetRivers, William Hill, Circa Sports, HardRock Bet, PointsBet, Kalshi, plus several regional US skins. The wider catalogue runs to 381 bookmakers, though any single fixture carries a subset.<\/p>\n
Is NFL player prop data available?<\/h3>\n
The markets exist year round, but books post prop menus close to kickoff. In late July only DraftKings had posted an anytime touchdown market on Week 1 games. Expect a full board in the days before each game rather than weeks out.<\/p>\n
How do I get historical NFL odds for backtesting?<\/h3>\n
Call \/historical-odds<\/code> with a fixture ID and up to three bookmakers. It returns timestamped snapshots, including the limit at each timestamp, so you can reconstruct opening lines, closing lines and how the market moved. It is included in the free tier.<\/p>\n
Does the API include NFL scores or player stats?<\/h3>\n
No. The feed carries schedules, fixture status and odds. For results and box scores you will need a separate stats provider, which you can join on the IDs in the externalProviders<\/code> object on every fixture.<\/p>\n
Start building<\/h2>\n
You now have working code that finds the NFL, pulls the schedule, parses moneylines across fifteen books, discovers whichever spread and total lines are actually on the board, measures the vig, reads the sharp limits and reconstructs price history. None of it needs a sales call.<\/p>\n
Get your free API key<\/a> and have the preseason board on your screen before August.<\/p>\n