{"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-02-05T17:19:58","modified_gmt":"2026-02-05T17:19:58","slug":"free-nfl-odds-api-guide","status":"publish","type":"post","link":"https:\/\/oddspapi.io\/blog\/free-nfl-odds-api-guide\/","title":{"rendered":"Free NFL Odds API Guide: Python Code for Real-Time Betting Data"},"content":{"rendered":"
\n
<\/div>\n<\/div>\n

Learn to fetch real-time NFL lines, spreads, and props with Python. The best free NFL Odds API featuring 300+ bookmakers, native American odds, and historical data.<\/p>\n

If you are building a sports betting model<\/a>, a real-time odds line tracker<\/a>, an arbitrage bot<\/a>, or a player props odds screener<\/a>, you have likely run into a wall. The data is either prohibitively expensive (Sportradar, Genius) or frustratingly limited (APIs that only cover 10 sportsbooks).<\/p>\n

You need coverage of the “Big 4” US books (DraftKings, FanDuel, BetMGM, Caesars) plus<\/em> the offshore sharps (Pinnacle, Circa) to find true market value. And you need it fast.<\/p>\n

In this guide, we’ll show you how to use OddsPapi<\/strong><\/a> to fetch real-time NFL data using Python.<\/p>\n

NFL Odds API Providers Compared (2025)<\/h2>\n

Before diving into code, here’s how the major NFL odds API providers stack up:<\/p>\n

\n\n\n\n\n\n\n\n\n
Provider<\/th>\nBookmakers<\/th>\nHistorical Data<\/th>\nFree Tier<\/th>\n<\/tr>\n<\/thead>\n
OddsPapi<\/strong><\/td>\n300+ (incl. Pinnacle, Circa)<\/td>\nYes (free)<\/td>\n200 requests\/month<\/td>\n<\/tr>\n
The Odds API<\/strong><\/td>\n~15 US books<\/td>\nNo (paid only)<\/td>\n500 requests\/month<\/td>\n<\/tr>\n
SportsDataIO<\/strong><\/td>\n~10 books<\/td>\nLimited<\/td>\nTrial only<\/td>\n<\/tr>\n
Sportradar<\/strong><\/td>\nEnterprise-level<\/td>\nYes<\/td>\nNone ($2k+\/mo)<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n

The key difference: OddsPapi includes sharp bookmakers<\/strong> like Pinnacle and Circa that set the true market price. Most “free” APIs only cover retail sportsbooks that copy lines from the sharps with worse juice.<\/p>\n

API Terminology: US Sports vs. Global Standards<\/h2>\n

OddsPapi is a global provider. To use it effectively for US Sports, you need to map a few terms:<\/p>\n

\n\n\n\n\n\n\n\n\n\n
US Concept<\/th>\nAPI Term<\/th>\nTechnical Note<\/th>\n<\/tr>\n<\/thead>\n
League<\/strong><\/td>\nTournament<\/code><\/td>\nThe NFL is a tournament within Sport ID 14 (American Football).<\/td>\n<\/tr>\n
Game<\/strong><\/td>\nFixture<\/code><\/td>\nYou need the fixtureId<\/code> to pull odds.<\/td>\n<\/tr>\n
Moneyline<\/strong><\/td>\nMarket ID 141<\/code><\/td>\nMarkets are returned by ID. 141 is the standard Match Winner.<\/td>\n<\/tr>\n
Spread<\/strong><\/td>\nAsian Handicap Markets<\/code><\/td>\nMultiple IDs based on spread line (see Market IDs section below).<\/td>\n<\/tr>\n
Totals<\/strong><\/td>\nMarket ID 148<\/code><\/td>\nOver\/Under on total points scored.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n

Step 1: Authentication & Sport IDs<\/h2>\n

First, get your free API key. Unlike some APIs that use headers, OddsPapi expects the apiKey<\/code> as a standard query parameter. This makes it easy to test right in your browser.<\/p>\n

Get your free OddsPapi API key here<\/a><\/div>\n

We also need to target the correct sport. In our system, American Football is Sport ID 14<\/strong>.<\/p>\n

import requests\r\nimport json\r\nfrom datetime import datetime, timedelta\r\n\r\nAPI_KEY = \"YOUR_API_KEY_HERE\"\r\nBASE_URL = \"https:\/\/api.oddspapi.io\/v4\"\r\n\r\ndef get_nfl_tournament_id():\r\n    # Pass the API Key as a 'param'.\r\n    # Sport ID 14 is American Football.\r\n    params = {\r\n        \"apiKey\": API_KEY,\r\n        \"sportId\": 14\r\n    }\r\n\r\n    response = requests.get(f\"{BASE_URL}\/tournaments\", params=params)\r\n\r\n    if response.status_code == 200:\r\n        tournaments = response.json()\r\n        # Find the NFL in the list (excluding Simulations)\r\n        nfl = next((t for t in tournaments if \"NFL\" in t.get('tournamentName', '') and \"Sim\" not in t.get('tournamentName', '')), None)\r\n\r\n        if nfl:\r\n            print(f\"Found NFL League ID: {nfl['tournamentId']}\")\r\n            return nfl['tournamentId']\r\n\r\n    print(\"NFL not found.\")\r\n    return None\r\n\r\nnfl_id = get_nfl_tournament_id()\r\n<\/code><\/pre>\n
Step 2: Get the Schedule (Fixtures)<\/h2>\n
The \/fixtures<\/code> endpoint returns a flat list of games. We need to filter this list to find games that actually have odds available (hasOdds: true<\/code>). This saves you from making useless calls on games that books haven’t posted lines for yet.<\/p>\n
def get_nfl_games(tournament_id):\r\n    # Get games for the next 7 days\r\n    today = datetime.now()\r\n    params = {\r\n        \"apiKey\": API_KEY,\r\n        \"tournamentId\": tournament_id,\r\n        \"from\": today.strftime(\"%Y-%m-%dT00:00:00Z\"),\r\n        \"to\": (today + timedelta(days=7)).strftime(\"%Y-%m-%dT23:59:59Z\")\r\n    }\r\n\r\n    response = requests.get(f\"{BASE_URL}\/fixtures\", params=params)\r\n\r\n    if response.status_code == 200:\r\n        fixtures = response.json()\r\n        # Filter for games that have odds\r\n        games_with_odds = [f for f in fixtures if f.get('hasOdds')]\r\n        return games_with_odds\r\n\r\n    return []\r\n\r\nupcoming_games = get_nfl_games(nfl_id)\r\nif upcoming_games:\r\n    print(f\"Found {len(upcoming_games)} games with odds.\")\r\n    print(f\"Next Game: {upcoming_games[0]['participant1Name']} vs {upcoming_games[0]['participant2Name']}\")\r\n<\/code><\/pre>\n
Step 3: Parsing the Nested Odds Structure<\/h2>\n
This is where most developers get stuck. To handle data from 300+ bookmakers without crashing your application, OddsPapi uses a highly optimized, nested JSON structure.<\/p>\n
The hierarchy is: Bookmaker -> Markets -> Outcomes -> Players -> Price<\/code>.<\/p>\n
We specifically look for Market ID 141<\/strong> (Moneyline) to get the “Win” odds for each team.<\/p>\n
def get_moneyline_odds(fixture_id):\r\n    params = {\r\n        \"apiKey\": API_KEY,\r\n        \"fixtureId\": fixture_id,\r\n        \"bookmaker\": \"draftkings,pinnacle,bet365\" # Compare US vs Offshore\r\n    }\r\n\r\n    response = requests.get(f\"{BASE_URL}\/odds\", params=params)\r\n    data = response.json()\r\n\r\n    print(f\"\\nOdds for Game ID: {fixture_id}\")\r\n\r\n    # Loop through Bookmakers\r\n    bookmakers = data.get('bookmakerOdds', {})\r\n\r\n    for bookie_name, bookie_data in bookmakers.items():\r\n        if not bookie_data.get('bookmakerIsActive'):\r\n            continue\r\n\r\n        # Market 141 is the Moneyline\r\n        markets = bookie_data.get('markets', {})\r\n        if '141' in markets:\r\n            outcomes = markets['141'].get('outcomes', {})\r\n\r\n            # Outcome 141 is Home Team, 142 is Away Team\r\n            # We dig deep into the 'players' object to find the 'price'\r\n            home_price = outcomes.get('141', {}).get('players', {}).get('0', {}).get('price')\r\n            away_price = outcomes.get('142', {}).get('players', {}).get('0', {}).get('price')\r\n\r\n            if home_price and away_price:\r\n                # Convert Decimal to American for display\r\n                print(f\"{bookie_name}: Home {decimal_to_american(home_price)} | Away {decimal_to_american(away_price)}\")\r\n\r\ndef decimal_to_american(decimal):\r\n    if decimal >= 2.0:\r\n        return f\"+{int((decimal - 1) * 100)}\"\r\n    else:\r\n        return f\"{int(-100 \/ (decimal - 1))}\"\r\n\r\n# Run it for the first game found\r\nif upcoming_games:\r\n    get_moneyline_odds(upcoming_games[0]['fixtureId'])\r\n<\/code><\/pre>\n
Output Example<\/h3>\n
When you run the script above, you get a clean comparison of lines. Notice how easy it is to spot arbitrage or value when you compare DraftKings odds directly against Pinnacle odds:<\/p>\n
Odds for Game ID: id1400003160574919\r\ndraftkings: Home -135 | Away +115\r\npinnacle:   Home -131 | Away +119\r\nbet365:     Home -133 | Away +110\r\n<\/code><\/pre>\n
Step 4: Fetching NFL Spreads (Asian Handicap)<\/h2>\n
NFL spreads are returned as Asian Handicap markets. Unlike moneylines which use a single Market ID, spreads use different Market IDs based on the handicap line<\/strong>.<\/p>\n
For a deep dive into Asian Handicap market structure, see our OddsPapi Singbet API and Asian Handicap guide<\/a>.<\/p>\n
Here are the key Market IDs for NFL spreads:<\/p>\n
\n\n\n\n\n\n\n\n\n
Market ID<\/th>\nHandicap Line<\/th>\nNFL Example<\/th>\n<\/tr>\n<\/thead>\n
1072<\/code><\/td>\n0 (Pick’em)<\/td>\nEven matchup<\/td>\n<\/tr>\n
1068<\/code><\/td>\n-0.5<\/td>\nPK (no push)<\/td>\n<\/tr>\n
1076<\/code><\/td>\n-3.5<\/td>\nStandard NFL spread<\/td>\n<\/tr>\n
1080<\/code><\/td>\n-7.5<\/td>\nOne-TD favorite<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n
def get_spread_odds(fixture_id):\r\n    \"\"\"Fetch NFL spread odds from multiple bookmakers.\"\"\"\r\n    params = {\r\n        \"apiKey\": API_KEY,\r\n        \"fixtureId\": fixture_id,\r\n        \"bookmaker\": \"pinnacle,draftkings,fanduel\"\r\n    }\r\n\r\n    response = requests.get(f\"{BASE_URL}\/odds\", params=params)\r\n    data = response.json()\r\n\r\n    # Common NFL spread market IDs\r\n    spread_markets = ['1076', '1080', '1068']  # -3.5, -7.5, -0.5\r\n\r\n    bookmakers = data.get('bookmakerOdds', {})\r\n\r\n    for bookie_name, bookie_data in bookmakers.items():\r\n        if not bookie_data.get('bookmakerIsActive'):\r\n            continue\r\n\r\n        markets = bookie_data.get('markets', {})\r\n\r\n        for market_id in spread_markets:\r\n            if market_id in markets:\r\n                outcomes = markets[market_id].get('outcomes', {})\r\n                print(f\"{bookie_name} - Market {market_id}:\")\r\n\r\n                for outcome_id, outcome_data in outcomes.items():\r\n                    price = outcome_data.get('players', {}).get('0', {}).get('price')\r\n                    handicap = outcome_data.get('players', {}).get('0', {}).get('handicap', 'N\/A')\r\n                    if price:\r\n                        print(f\"  Handicap {handicap}: {decimal_to_american(price)}\")\r\n<\/code><\/pre>\n
Step 5: Fetching Totals (Over\/Under)<\/h2>\n
For totals, use Market ID 148<\/strong>. This gives you the Over\/Under lines for total points scored.<\/p>\n
def get_totals_odds(fixture_id):\r\n    \"\"\"Fetch NFL Over\/Under odds.\"\"\"\r\n    params = {\r\n        \"apiKey\": API_KEY,\r\n        \"fixtureId\": fixture_id,\r\n        \"bookmaker\": \"pinnacle,draftkings\"\r\n    }\r\n\r\n    response = requests.get(f\"{BASE_URL}\/odds\", params=params)\r\n    data = response.json()\r\n\r\n    bookmakers = data.get('bookmakerOdds', {})\r\n\r\n    for bookie_name, bookie_data in bookmakers.items():\r\n        if not bookie_data.get('bookmakerIsActive'):\r\n            continue\r\n\r\n        markets = bookie_data.get('markets', {})\r\n\r\n        # Market 148 is Totals (Over\/Under)\r\n        if '148' in markets:\r\n            outcomes = markets['148'].get('outcomes', {})\r\n            print(f\"\\n{bookie_name} Totals:\")\r\n\r\n            for outcome_id, outcome_data in outcomes.items():\r\n                price = outcome_data.get('players', {}).get('0', {}).get('price')\r\n                total_line = outcome_data.get('players', {}).get('0', {}).get('handicap')\r\n                outcome_name = \"Over\" if outcome_id == '391' else \"Under\"\r\n\r\n                if price and total_line:\r\n                    print(f\"  {outcome_name} {total_line}: {decimal_to_american(price)}\")\r\n<\/code><\/pre>\n
Why Market IDs Matter<\/h2>\n
Other APIs use text labels like “h2h” or “spreads”. The problem? If a bookmaker changes “Spread” to “Handicap” in their feed, your bot breaks.<\/p>\n
OddsPapi uses stable Integer IDs. Here is your cheat sheet for the NFL:<\/p>\n