\nSelection (Home, Away, Over)<\/td>\n Outcome<\/td>\n Home (1)<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\nKeep this table handy. The rest of the tutorial uses OddsPapi terminology.<\/p>\n
Step 1: Authentication & Your First API Call<\/h2>\n OddsPapi uses a query parameter for authentication \u2014 not a header. This is the most common mistake beginners make, so let’s get it right from the start:<\/p>\n
import requests\n\nAPI_KEY = \"YOUR_API_KEY\"\nBASE_URL = \"https:\/\/api.oddspapi.io\/v4\"\n\n# Fetch all available sports\nresponse = requests.get(\n f\"{BASE_URL}\/sports\",\n params={\"apiKey\": API_KEY}\n)\n\nsports = response.json()\n\nprint(f\"Found {len(sports)} sports:\\n\")\nfor sport in sports[:10]:\n print(f\" {sport['sportName']} (ID: {sport['sportId']}, slug: {sport['slug']})\")<\/code><\/pre>\nThe response is a list of objects, each with three fields:<\/p>\n
\nsportId<\/code> \u2014 the numeric ID you’ll use in other API calls<\/li>\nslug<\/code> \u2014 a URL-friendly name (e.g., soccer<\/code>, basketball<\/code>)<\/li>\nsportName<\/code> \u2014 the human-readable name<\/li>\n<\/ul>\nFound 69 sports:\n\n Soccer (ID: 10, slug: soccer)\n Basketball (ID: 11, slug: basketball)\n Tennis (ID: 12, slug: tennis)\n Baseball (ID: 13, slug: baseball)\n American Football (ID: 14, slug: american-football)\n Ice Hockey (ID: 15, slug: ice-hockey)\n ESport Dota (ID: 16, slug: esport-dota)\n ESport Counter-Strike (ID: 17, slug: esport-counter-strike)\n ESport League of Legends (ID: 18, slug: esport-league-of-legends)\n MMA (ID: 20, slug: mma)<\/code><\/pre>\nImportant:<\/strong> The apiKey<\/code> goes in the query string (params=<\/code>), not in the headers. If you put it in an Authorization<\/code> header, you’ll get a 401 error.<\/p>\nStep 2: Find Upcoming Fixtures<\/h2>\n Now let’s fetch some actual matches. The \/fixtures<\/code> endpoint requires a sport ID and a date range:<\/p>\nfrom datetime import datetime, timedelta, timezone\n\n# Fetch soccer fixtures for the next 3 days\nnow = datetime.now(timezone.utc)\ndate_from = now.strftime(\"%Y-%m-%dT00:00:00Z\")\ndate_to = (now + timedelta(days=3)).strftime(\"%Y-%m-%dT23:59:59Z\")\n\nresponse = requests.get(\n f\"{BASE_URL}\/fixtures\",\n params={\n \"apiKey\": API_KEY,\n \"sportId\": 10, # Soccer\n \"from\": date_from,\n \"to\": date_to\n }\n)\n\nfixtures = response.json()\nprint(f\"Total fixtures: {len(fixtures)}\")\n\n# Filter to only fixtures that have odds available\nfixtures_with_odds = [f for f in fixtures if f.get(\"hasOdds\")]\nprint(f\"Fixtures with odds: {len(fixtures_with_odds)}\\n\")\n\n# Display the first 10\nfor i, fix in enumerate(fixtures_with_odds[:10], 1):\n home = fix[\"participant1Name\"]\n away = fix[\"participant2Name\"]\n tournament = fix[\"tournamentName\"]\n start = fix[\"startTime\"][:16].replace(\"T\", \" \")\n print(f\" {i}. {home} vs {away}\")\n print(f\" {tournament} \u2014 {start} UTC\")<\/code><\/pre>\nA few things to note:<\/p>\n
\nThe from<\/code> and to<\/code> parameters use ISO 8601 format. The maximum range is 10 days.<\/li>\nhasOdds: true<\/code> means at least one bookmaker is pricing this fixture. Always filter on this \u2014 fixtures without odds won’t return useful data from the odds endpoint.<\/li>\nEach fixture has a fixtureId<\/code> (like id1000001761301147<\/code>) that you’ll use to fetch odds.<\/li>\nTeams are called participant1Name<\/code> (home) and participant2Name<\/code> (away).<\/li>\n<\/ul>\nStep 3: Fetch Live Odds<\/h2>\n This is where it gets interesting. The \/odds<\/code> endpoint returns live prices from the bookmakers you specify:<\/p>\nimport time\n\n# Pick a fixture (use the fixtureId from Step 2)\nfixture_id = fixtures_with_odds[0][\"fixtureId\"]\nhome_team = fixtures_with_odds[0][\"participant1Name\"]\naway_team = fixtures_with_odds[0][\"participant2Name\"]\n\ntime.sleep(0.2) # Respect the rate limit\n\nresponse = requests.get(\n f\"{BASE_URL}\/odds\",\n params={\n \"apiKey\": API_KEY,\n \"fixtureId\": fixture_id,\n \"bookmakers\": \"pinnacle,bet365,draftkings\"\n }\n)\n\nodds_data = response.json()<\/code><\/pre>\nThe response JSON is deeply nested<\/strong>. This is where most beginners get stuck, so let’s walk through it layer by layer:<\/p>\n# The path to a single price:\n# odds_data[\"bookmakerOdds\"][bookmaker_slug][\"markets\"][market_id][\"outcomes\"][outcome_id][\"players\"][\"0\"][\"price\"]\n\n# Let's trace it step by step:\n\n# 1. Get the bookmaker odds container\nbookmaker_odds = odds_data[\"bookmakerOdds\"]\nprint(f\"Bookmakers: {list(bookmaker_odds.keys())}\")\n# \u2192 ['bet365', 'pinnacle', 'draftkings']\n\n# 2. Pick a bookmaker\npinnacle = bookmaker_odds[\"pinnacle\"]\n\n# 3. Get the markets dict (keys are market IDs as strings)\nmarkets = pinnacle[\"markets\"]\nprint(f\"Market IDs available: {list(markets.keys())[:5]}...\")\n# \u2192 ['101', '104', '106', '108', '1010'...]\n\n# 4. Pick market 101 (Full Time Result \/ 1X2)\nmarket_101 = markets[\"101\"]\n\n# 5. Get outcomes (keys are outcome IDs as strings)\noutcomes = market_101[\"outcomes\"]\nprint(f\"Outcome IDs: {list(outcomes.keys())}\")\n# \u2192 ['101', '102', '103']\n\n# 6. Get the price for outcome 101 (Home win)\nhome_odds = outcomes[\"101\"][\"players\"][\"0\"][\"price\"]\nprint(f\"Pinnacle Home price: {home_odds}\")\n# \u2192 3.79<\/code><\/pre>\nWhy players[\"0\"]<\/code>? For standard markets, \"0\"<\/code> represents the current price. Player prop markets use player IDs as keys instead \u2014 but for this tutorial, \"0\"<\/code> is all you need.<\/p>\nWhat Do the Market and Outcome IDs Mean?<\/h3>\n Market ID 101<\/code> and outcome ID 101<\/code> are just numbers \u2014 you need to look them up. The \/markets<\/code> endpoint gives you human-readable names:<\/p>\ntime.sleep(0.2)\n\n# Fetch the market catalog for soccer\nresponse = requests.get(\n f\"{BASE_URL}\/markets\",\n params={\"apiKey\": API_KEY, \"sportId\": 10}\n)\ncatalog = response.json()\n\n# Build lookup dicts\nmarket_names = {m[\"marketId\"]: m[\"marketName\"] for m in catalog}\noutcome_names = {\n (m[\"marketId\"], o[\"outcomeId\"]): o[\"outcomeName\"]\n for m in catalog\n for o in m.get(\"outcomes\", [])\n}\n\n# Now you can translate IDs to names\nprint(market_names[101]) # \u2192 \"Full Time Result\"\nprint(outcome_names[(101, 101)]) # \u2192 \"1\" (Home)\nprint(outcome_names[(101, 102)]) # \u2192 \"X\" (Draw)\nprint(outcome_names[(101, 103)]) # \u2192 \"2\" (Away)<\/code><\/pre>\nFor the Full Time Result market, the outcome names are shorthand: 1<\/code> = Home win, X<\/code> = Draw, 2<\/code> = Away win. This is standard 1X2 notation used across the industry.<\/p>\nStep 4: Build the Comparison Table<\/h2>\n Now let’s pull it all together and compare prices across bookmakers:<\/p>\n
def compare_odds(odds_data, market_id, market_name, outcome_ids, outcome_labels):\n \"\"\"Compare prices across bookmakers for a given market.\"\"\"\n bookmaker_odds = odds_data.get(\"bookmakerOdds\", {})\n slugs = list(bookmaker_odds.keys())\n\n if not slugs:\n print(\"No bookmaker odds available for this fixture.\")\n return\n\n # Header\n print(f\"\\n{market_name}\")\n header = f\"{'Outcome':<10}\"\n for slug in slugs:\n header += f\" {slug:<12}\"\n header += \" Best\"\n print(header)\n print(\"-\" * len(header))\n\n # Each outcome row\n for oid, label in zip(outcome_ids, outcome_labels):\n row = f\"{label:<10}\"\n best_price = 0\n best_book = \"\"\n\n for slug in slugs:\n try:\n price = bookmaker_odds[slug][\"markets\"][str(market_id)][\"outcomes\"][str(oid)][\"players\"][\"0\"][\"price\"]\n row += f\" {price:<12.3f}\"\n if price > best_price:\n best_price = price\n best_book = slug\n except KeyError:\n row += f\" {'\u2014':<12}\"\n\n row += f\" {best_book} @ {best_price:.3f}\"\n print(row)\n\n# Use it\ncompare_odds(\n odds_data,\n market_id=101,\n market_name=\"Full Time Result (1X2)\",\n outcome_ids=[101, 102, 103],\n outcome_labels=[\"Home\", \"Draw\", \"Away\"]\n)<\/code><\/pre>\nOutput:<\/p>\n
Full Time Result (1X2)\nOutcome bet365 pinnacle draftkings Best\n---------------------------------------------------------------\nHome 3.600 3.790 3.600 pinnacle @ 3.790\nDraw 3.900 3.030 3.000 bet365 @ 3.900\nAway 1.900 2.150 2.200 draftkings @ 2.200<\/code><\/pre>\nThe \"Best\" column shows which bookmaker offers the highest price for each outcome. This is called line shopping<\/strong> \u2014 finding the best available price before placing a bet. Even small differences (like 3.79 vs 3.60 for a home win) add up over hundreds of bets.<\/p>\nStep 5: The Complete Script<\/h2>\n Here's the full working script that ties everything together into an interactive tool:<\/p>\n
\"\"\"\nOdds Comparison Tool \u2014 Built with OddsPapi API\nCompare live prices across bookmakers for any sport and fixture.\n\"\"\"\nimport requests\nimport time\nfrom datetime import datetime, timedelta, timezone\n\nAPI_KEY = \"YOUR_API_KEY\"\nBASE_URL = \"https:\/\/api.oddspapi.io\/v4\"\nBOOKMAKERS = \"pinnacle,bet365,draftkings\"\n\n\ndef api_get(endpoint, **params):\n \"\"\"Make an authenticated GET request to the OddsPapi API.\"\"\"\n params[\"apiKey\"] = API_KEY\n response = requests.get(f\"{BASE_URL}{endpoint}\", params=params)\n response.raise_for_status()\n time.sleep(0.2) # Respect rate limits\n return response.json()\n\n\ndef pick_sport():\n \"\"\"Display sports and let the user choose one.\"\"\"\n sports = api_get(\"\/sports\")\n print(\"\\nAvailable Sports:\")\n for i, sport in enumerate(sports, 1):\n print(f\" {i}. {sport['sportName']} (ID: {sport['sportId']})\")\n choice = int(input(\"\\nPick a sport number: \")) - 1\n return sports[choice]\n\n\ndef pick_fixture(sport_id):\n \"\"\"Fetch fixtures and let the user choose one.\"\"\"\n now = datetime.now(timezone.utc)\n fixtures = api_get(\n \"\/fixtures\",\n sportId=sport_id,\n **{\"from\": now.strftime(\"%Y-%m-%dT00:00:00Z\")},\n to=(now + timedelta(days=3)).strftime(\"%Y-%m-%dT23:59:59Z\")\n )\n\n with_odds = [f for f in fixtures if f.get(\"hasOdds\")]\n if not with_odds:\n print(\"No fixtures with odds found. Try a different sport.\")\n return None\n\n print(f\"\\nUpcoming Fixtures ({len(with_odds)} with odds):\")\n for i, fix in enumerate(with_odds[:15], 1):\n start = fix[\"startTime\"][:16].replace(\"T\", \" \")\n print(f\" {i}. {fix['participant1Name']} vs {fix['participant2Name']}\")\n print(f\" {fix['tournamentName']} \u2014 {start} UTC\")\n\n choice = int(input(\"\\nPick a fixture number: \")) - 1\n return with_odds[choice]\n\n\ndef get_market_names(sport_id):\n \"\"\"Build lookup dicts for market and outcome names.\"\"\"\n catalog = api_get(\"\/markets\", sportId=sport_id)\n market_names = {m[\"marketId\"]: m[\"marketName\"] for m in catalog}\n outcome_names = {\n (m[\"marketId\"], o[\"outcomeId\"]): o[\"outcomeName\"]\n for m in catalog\n for o in m.get(\"outcomes\", [])\n }\n return market_names, outcome_names\n\n\ndef display_comparison(odds_data, market_id, outcome_ids, market_names, outcome_names):\n \"\"\"Print a comparison table for one market across all bookmakers.\"\"\"\n bookmaker_odds = odds_data.get(\"bookmakerOdds\", {})\n slugs = list(bookmaker_odds.keys())\n if not slugs:\n print(\"No bookmaker odds available.\")\n return\n\n mkt_name = market_names.get(market_id, f\"Market {market_id}\")\n print(f\"\\n{mkt_name}\")\n\n header = f\" {'Outcome':<10}\"\n for slug in slugs:\n header += f\" {slug:<12}\"\n header += \" Best Price\"\n print(header)\n print(\" \" + \"-\" * (len(header) - 2))\n\n for oid in outcome_ids:\n label = outcome_names.get((market_id, oid), str(oid))\n row = f\" {label:<10}\"\n best_price = 0\n best_book = \"\"\n\n for slug in slugs:\n try:\n price = (bookmaker_odds[slug][\"markets\"][str(market_id)]\n [\"outcomes\"][str(oid)][\"players\"][\"0\"][\"price\"])\n row += f\" {price:<12.3f}\"\n if price > best_price:\n best_price = price\n best_book = slug\n except KeyError:\n row += f\" {'\u2014':<12}\"\n\n row += f\" {best_book} @ {best_price:.2f}\"\n print(row)\n\n\ndef main():\n print(\"=\" * 50)\n print(\" OddsPapi Odds Comparison Tool\")\n print(\"=\" * 50)\n\n # Step 1: Pick a sport\n sport = pick_sport()\n sport_id = sport[\"sportId\"]\n print(f\"\\nSelected: {sport['sportName']}\")\n\n # Step 2: Pick a fixture\n fixture = pick_fixture(sport_id)\n if not fixture:\n return\n\n fixture_id = fixture[\"fixtureId\"]\n home = fixture[\"participant1Name\"]\n away = fixture[\"participant2Name\"]\n print(f\"\\nSelected: {home} vs {away}\")\n\n # Step 3: Fetch odds and market names\n print(\"\\nFetching odds...\")\n odds_data = api_get(\"\/odds\", fixtureId=fixture_id, bookmakers=BOOKMAKERS)\n market_names, outcome_names = get_market_names(sport_id)\n\n if \"bookmakerOdds\" not in odds_data:\n print(\"No odds available for this fixture yet.\")\n return\n\n print(f\"\\nOdds Comparison: {home} vs {away}\")\n\n # Step 4: Display Full Time Result (market 101)\n display_comparison(odds_data, 101, [101, 102, 103], market_names, outcome_names)\n\n # Also show Over\/Under 2.5 if available (market 1010)\n first_slug = list(odds_data[\"bookmakerOdds\"].keys())[0]\n if \"1010\" in odds_data[\"bookmakerOdds\"][first_slug].get(\"markets\", {}):\n display_comparison(odds_data, 1010, [1010, 1011], market_names, outcome_names)\n\n\nif __name__ == \"__main__\":\n main()<\/code><\/pre>\nBonus: Turn It Into a Web App with Streamlit<\/h2>\n Want to share this tool with someone who doesn't use a terminal? Streamlit turns the same logic into a browser-based app with about 30 lines of extra code.<\/p>\n
Install it:<\/p>\n
pip install streamlit<\/code><\/pre>\nThen create odds_app.py<\/code>:<\/p>\n\"\"\"\nOdds Comparison Web App \u2014 Built with OddsPapi + Streamlit\nRun with: streamlit run odds_app.py\n\"\"\"\nimport streamlit as st\nimport requests\nimport time\nimport pandas as pd\nfrom datetime import datetime, timedelta, timezone\n\nAPI_KEY = \"YOUR_API_KEY\"\nBASE_URL = \"https:\/\/api.oddspapi.io\/v4\"\nBOOKMAKERS = \"pinnacle,bet365,draftkings\"\n\n\ndef api_get(endpoint, **params):\n params[\"apiKey\"] = API_KEY\n r = requests.get(f\"{BASE_URL}{endpoint}\", params=params)\n r.raise_for_status()\n time.sleep(0.2)\n return r.json()\n\n\nst.title(\"Odds Comparison Tool\")\n\n# Sport selector\nsports = api_get(\"\/sports\")\nsport_names = {s[\"sportName\"]: s[\"sportId\"] for s in sports}\nselected_sport = st.selectbox(\"Sport\", list(sport_names.keys()))\nsport_id = sport_names[selected_sport]\n\n# Fetch fixtures\nnow = datetime.now(timezone.utc)\nfixtures = api_get(\n \"\/fixtures\", sportId=sport_id,\n **{\"from\": now.strftime(\"%Y-%m-%dT00:00:00Z\")},\n to=(now + timedelta(days=3)).strftime(\"%Y-%m-%dT23:59:59Z\")\n)\nwith_odds = [f for f in fixtures if f.get(\"hasOdds\")]\n\nif not with_odds:\n st.warning(\"No fixtures with odds available.\")\n st.stop()\n\n# Fixture selector\nfixture_labels = {\n f\"{f['participant1Name']} vs {f['participant2Name']} ({f['tournamentName']})\": f\n for f in with_odds[:20]\n}\nselected_fix = st.selectbox(\"Fixture\", list(fixture_labels.keys()))\nfixture = fixture_labels[selected_fix]\n\n# Fetch and display odds\nodds_data = api_get(\"\/odds\", fixtureId=fixture[\"fixtureId\"], bookmakers=BOOKMAKERS)\n\nif \"bookmakerOdds\" not in odds_data:\n st.info(\"No odds available for this fixture yet.\")\n st.stop()\n\n# Build comparison table for Full Time Result (market 101)\nrows = []\nlabels = {101: \"Home\", 102: \"Draw\", 103: \"Away\"}\nbookmaker_odds = odds_data[\"bookmakerOdds\"]\n\nfor oid, label in labels.items():\n row = {\"Outcome\": label}\n for slug in bookmaker_odds:\n try:\n price = (bookmaker_odds[slug][\"markets\"][\"101\"]\n [\"outcomes\"][str(oid)][\"players\"][\"0\"][\"price\"])\n row[slug] = price\n except KeyError:\n row[slug] = None\n rows.append(row)\n\ndf = pd.DataFrame(rows).set_index(\"Outcome\")\nst.subheader(\"Full Time Result (1X2)\")\nst.dataframe(df.style.highlight_max(axis=1), use_container_width=True)<\/code><\/pre>\nRun it with streamlit run odds_app.py<\/code> and you'll have a live odds comparison dashboard in your browser. For a more advanced version with auto-refresh and multiple markets, check out our full Streamlit dashboard tutorial<\/a>.<\/p>\nUnderstanding the Numbers<\/h2>\n The API returns decimal odds<\/strong> (the standard in Europe and Asia). Here's what you need to know:<\/p>\n\n\n\n\nConcept<\/th>\n Formula<\/th>\n Example (odds = 3.79)<\/th>\n<\/tr>\n<\/thead>\n \n\nImplied Probability<\/td>\n 1 \/ odds<\/code><\/td>\n1 \/ 3.79 = 26.4%<\/td>\n<\/tr>\n \nPotential Payout<\/td>\n stake × odds<\/code><\/td>\n$10 × 3.79 = $37.90<\/td>\n<\/tr>\n \nProfit<\/td>\n stake × (odds - 1)<\/code><\/td>\n$10 × 2.79 = $27.90<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\nWhy \"best price\" matters:<\/strong> If Pinnacle offers 3.79 and Bet365 offers 3.60 for the same outcome, Pinnacle is giving you better value. On a $100 bet, that's $379 vs $360 in potential payout \u2014 a $19 difference from the same bet. Across hundreds of bets, line shopping for the best price is one of the simplest edges you can find.<\/p>\n# Quick odds conversion helpers\ndef to_probability(decimal_odds):\n \"\"\"Convert decimal odds to implied probability.\"\"\"\n return 1 \/ decimal_odds\n\ndef to_american(decimal_odds):\n \"\"\"Convert decimal odds to American format.\"\"\"\n if decimal_odds >= 2.0:\n return f\"+{int((decimal_odds - 1) * 100)}\"\n else:\n return f\"-{int(100 \/ (decimal_odds - 1))}\"\n\n# Examples\nprint(to_probability(3.79)) # 0.2638 \u2192 26.4%\nprint(to_american(3.79)) # +279\nprint(to_american(1.50)) # -200<\/code><\/pre>\nWhere to Go Next<\/h2>\n You now know how to authenticate, fetch fixtures, parse nested odds JSON, and compare prices. That's the foundation for everything else. Here's what to build next, in order of complexity:<\/p>\n\n\n\n\nProject<\/th>\n What You'll Learn<\/th>\n Tutorial<\/th>\n<\/tr>\n<\/thead>\n \n\nLive Odds Dashboard<\/strong><\/td>\nAuto-refreshing Streamlit app with multiple markets<\/td>\n Build a Dashboard<\/a><\/td>\n<\/tr>\n\nArbitrage Bot<\/strong><\/td>\nFind guaranteed-profit opportunities across bookmakers<\/td>\n Build an Arb Bot<\/a><\/td>\n<\/tr>\n\nValue Betting Scanner<\/strong><\/td>\nIdentify bets where the bookmaker's price is too high<\/td>\n Value Scanner<\/a><\/td>\n<\/tr>\n\nBacktest a Model<\/strong><\/td>\nUse free historical odds to test strategies on past data<\/td>\n Backtest Tutorial<\/a><\/td>\n<\/tr>\n\nPlayer Props<\/strong><\/td>\nParse player-level prop markets (NFL, NBA, MLB)<\/td>\n Player Props Guide<\/a><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\nOddsPapi also gives you free historical odds data<\/strong> on the free tier \u2014 most competitors charge extra for this. If you want to backtest a strategy before risking real money, the historical endpoint is where you start.<\/p>\nFAQ<\/h2>\nIs the OddsPapi API free?<\/h3>\n Yes. The free tier gives you 250 API requests and access to all 350+ bookmakers, including historical odds. No credit card required to sign up.<\/p>\n
What programming language do I need?<\/h3>\n This tutorial uses Python, but the API is just HTTP + JSON. Any language that can make web requests works \u2014 JavaScript, Go, Java, C#, whatever you prefer.<\/p>\n
Do I need to know about sports betting?<\/h3>\n No. This tutorial explains the core concepts as you go. By the end, you'll understand fixtures, markets, outcomes, and odds well enough to build real tools.<\/p>\n
How many bookmakers can I compare?<\/h3>\n Over 350, including sharp bookmakers (Pinnacle, SBOBET, Singbet), major sportsbooks (Bet365, DraftKings, FanDuel), crypto books (1xBet, Stake), and prediction markets (Polymarket). You can request any combination in a single API call.<\/p>\n
What's the rate limit on the free tier?<\/h3>\n Approximately 0.88 seconds between calls to the same endpoint. Adding time.sleep(0.2)<\/code> in your code (as shown in the tutorial) keeps you comfortably within limits.<\/p>\nCan I get historical odds too?<\/h3>\n Yes \u2014 for free. The \/historical-odds<\/code> endpoint returns full price history for any fixture. Check our backtesting tutorial<\/a> for a complete walkthrough.<\/p>\n