{"id":2973,"date":"2026-06-16T10:00:00","date_gmt":"2026-06-16T10:00:00","guid":{"rendered":"https:\/\/oddspapi.io\/blog\/?p=2973"},"modified":"2026-06-05T14:56:09","modified_gmt":"2026-06-05T14:56:09","slug":"json-odds-feed-format-parsing","status":"publish","type":"post","link":"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/","title":{"rendered":"JSON Odds Feed: Format, Schema &#038; Parsing in Python (Free API)"},"content":{"rendered":"<p>You made one call to <code>\/v4\/odds<\/code> and got back a wall of nested JSON. Five levels deep, integer keys everywhere, prices in three different formats, and an <code>exchangeMeta<\/code> object that&#8217;s <code>null<\/code> on some books and a full order-book ladder on others. Where exactly is the price? What&#8217;s safe to assume? This is the field-by-field map of the OddsPapi JSON odds feed &mdash; the exact schema, the gotchas, and copy-paste Python that parses it without guessing.<\/p>\n<p>Every payload, field name, and number below was pulled live from the API on a real MLB fixture (Cubs vs Giants, 14 bookmakers) on the day this was written. Nothing here is invented.<\/p>\n<h2>Why &#8220;just parse the JSON&#8221; goes wrong<\/h2>\n<p>Most odds feeds fail you in one of two ways. Either they&#8217;re <strong>flat and undocumented<\/strong> &mdash; a generic API hands you <code>{\"home\": 1.95, \"away\": 2.05}<\/code> for 20 soft books and you have no idea what market or what timestamp that even is &mdash; or they&#8217;re <strong>deeply nested with no schema docs<\/strong>, so you end up writing brittle code that breaks the first time a key you assumed was always present comes back <code>null<\/code>.<\/p>\n<p>OddsPapi&#8217;s feed is the second kind: deeply nested, but <em>consistent<\/em>. Once you know the shape, parsing 350+ bookmakers across every sport is the same five-line walk every time. The nesting exists for a reason &mdash; one fixture can carry hundreds of markets, each with multiple outcomes, each with a current price <em>and<\/em> (for exchanges) a depth-of-book ladder. The structure is the price you pay for that much data in one response. This guide is the map.<\/p>\n<figure class=\"wp-block-table\">\n<table>\n<thead>\n<tr>\n<th>The naive assumption<\/th>\n<th>What the feed actually does<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>Top-level key is <code>odds<\/code> or <code>data<\/code><\/td>\n<td>It&#8217;s <code>bookmakerOdds<\/code> on the live endpoint, <code>bookmakers<\/code> on historical<\/td>\n<\/tr>\n<tr>\n<td>Markets\/outcomes are arrays<\/td>\n<td>They&#8217;re <strong>dicts keyed by stringified integer IDs<\/strong><\/td>\n<\/tr>\n<tr>\n<td>The price is on the outcome<\/td>\n<td>It&#8217;s one more level down, under <code>players[\"0\"]<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>players[\"0\"]<\/code> is always a dict<\/td>\n<td>Dict on <code>\/odds<\/code> (one current price), <strong>list<\/strong> on <code>\/historical-odds<\/code> (full history)<\/td>\n<\/tr>\n<tr>\n<td><code>exchangeMeta<\/code> is always <code>{}<\/code><\/td>\n<td><code>null<\/code> on sportsbooks; a <code>back<\/code>\/<code>lay<\/code> ladder on exchanges<\/td>\n<\/tr>\n<tr>\n<td>Every outcome has a live price<\/td>\n<td>Some are <code>active: false<\/code> or ship <code>price: 0<\/code> &mdash; filter them<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n<h2>Step 1: Authenticate and pull a payload<\/h2>\n<p>The API key is a <strong>query parameter<\/strong>, never a header. Every call needs it.<\/p>\n<pre class=\"wp-block-code\"><code>import requests\n\nAPI_KEY = \"YOUR_API_KEY\"   # get a free key at oddspapi.io\nBASE = \"https:\/\/api.oddspapi.io\/v4\"\n\ndef api(path, **params):\n    params[\"apiKey\"] = API_KEY\n    return requests.get(f\"{BASE}\/{path}\", params=params).json()\n\n# One fixture, all books that price it:\nodds = api(\"odds\", fixtureId=\"id1300010963302659\")\nprint(list(odds.keys()))\n# ['fixtureId', 'participant1Id', 'participant2Id', 'sportId', 'tournamentId',\n#  'seasonId', 'statusId', 'hasOdds', 'startTime', 'trueStartTime',\n#  'trueEndTime', 'updatedAt', 'bookmakerOdds']\n<\/code><\/pre>\n<p>Two things to know before you go further:<\/p>\n<ul>\n<li>Only fixtures with <code>hasOdds: true<\/code> (from <code>\/fixtures<\/code>) return a <code>bookmakerOdds<\/code> payload. Everything else returns fixture metadata only &mdash; or, occasionally, <code>{\"error\": ...}<\/code>. Always check the key exists before indexing it.<\/li>\n<li>You can narrow the response with <code>bookmakers=\"pinnacle,bet365,polymarket\"<\/code> (comma list). Omit it to get every book that prices the fixture.<\/li>\n<\/ul>\n<h2>Step 2: The envelope &rarr; bookmaker &rarr; market &rarr; outcome &rarr; price<\/h2>\n<p>Here&#8217;s the full path, top to bottom. Memorize this one diagram and the rest is mechanical:<\/p>\n<pre class=\"wp-block-code\"><code>bookmakerOdds                      # dict, keyed by bookmaker slug (\"pinnacle\", \"bet365\")\n  &rarr; [slug]\n      bookmakerIsActive            # bool\n      bookmakerFixtureId           # the book's own ID for this fixture\n      fixturePath                  # deep link path on the book\n      suspended                    # bool \u2014 book-level suspension\n      markets                      # dict, keyed by stringified marketId (\"131\")\n        &rarr; [market_id_str]\n            bookmakerMarketId\n            marketActive\n            outcomes               # dict, keyed by stringified outcomeId (\"131\")\n              &rarr; [outcome_id_str]\n                  players          # dict, keyed by \"0\" (and player IDs for props)\n                    &rarr; [\"0\"]      # a DICT on \/odds \u2014 the current price object\n<\/code><\/pre>\n<p>Note what is <strong>not<\/strong> in this payload: human-readable market and outcome <em>names<\/em>. The feed gives you integer IDs (<code>131<\/code>, <code>1010<\/code>) to keep responses small. You resolve names from the <code>\/markets<\/code> catalog &mdash; covered in Step 5.<\/p>\n<p>The canonical way to reach a single current price:<\/p>\n<pre class=\"wp-block-code\"><code>slug = \"pinnacle\"\nmarket_id = \"131\"        # Moneyline \/ Winner (stringified)\noutcome_id = \"131\"       # Home \/ \"1\"\n\nprice = (odds[\"bookmakerOdds\"][slug][\"markets\"][market_id]\n             [\"outcomes\"][outcome_id][\"players\"][\"0\"][\"price\"])\n<\/code><\/pre>\n<h2>Step 3: The outcome object, field by field<\/h2>\n<p>This is the leaf of the tree &mdash; <code>players[\"0\"]<\/code> on the live <code>\/odds<\/code> endpoint &mdash; and it&#8217;s where most people under-read the data. A real Pinnacle outcome, captured live:<\/p>\n<pre class=\"wp-block-code\"><code>{\n  \"active\": true,                       # is this price live? FILTER on this\n  \"betslip\": null,                      # deep-link to the book's betslip (exchanges\/US books often set it)\n  \"bookmakerOutcomeId\": \"-1.0\/away\",    # the book's own outcome handle\n  \"bookmakerChangedAt\": \"2026-06-05T14:42:07.980Z\",  # when the BOOK last moved it (can be null)\n  \"changedAt\": \"2026-06-05T14:42:08.558Z\",           # when OddsPapi last saw a change\n  \"limit\": 3546.0,                      # max stake the book will accept (null if unknown)\n  \"playerName\": null,                   # set on player-prop outcomes\n  \"price\": 1.793,                       # DECIMAL odds \u2014 the number you want\n  \"priceAmerican\": \"-126\",              # same price, American format (string)\n  \"priceFractional\": \"23\/29\",           # same price, fractional format (string)\n  \"mainLine\": false,                    # is this the book's headline line for the market?\n  \"exchangeMeta\": null                  # null on sportsbooks; ladder object on exchanges (Step 6)\n}\n<\/code><\/pre>\n<p>Three fields people miss and shouldn&#8217;t:<\/p>\n<ul>\n<li><strong><code>priceAmerican<\/code> \/ <code>priceFractional<\/code><\/strong> &mdash; the feed pre-converts every price into all three formats. You never have to write a decimal&harr;American converter; just read the field. They ship as strings.<\/li>\n<li><strong><code>changedAt<\/code><\/strong> &mdash; the freshness timestamp. This is what powers <a href=\"https:\/\/oddspapi.io\/blog\/steam-move-detector-python\/\">steam-move detectors<\/a>: compare a sharp book&#8217;s <code>changedAt<\/code> against a soft book&#8217;s to flag a stale line.<\/li>\n<li><strong><code>limit<\/code><\/strong> &mdash; the book&#8217;s max accepted stake. Sharp books (Pinnacle) expose real numbers; most soft books send <code>null<\/code>.<\/li>\n<\/ul>\n<p>A note for anyone migrating older code: sportsbook <code>exchangeMeta<\/code> is now <code>null<\/code>, not the empty <code>{}<\/code> you may have seen before. Treat &#8220;falsy&#8221; (<code>null<\/code> or <code>{}<\/code>) as &#8220;no exchange data&#8221; and you&#8217;re covered both ways.<\/p>\n<h2>Step 4: Defensive parsing &mdash; the four rules<\/h2>\n<p>Never assume a price is usable just because the outcome exists. These four guards prevent ~every parsing bug we&#8217;ve hit across 350+ books:<\/p>\n<pre class=\"wp-block-code\"><code>def usable_price(outcome):\n    # Return a clean decimal price, or None if this outcome isn't tradeable.\n    p = outcome.get(\"players\", {}).get(\"0\")\n    if not isinstance(p, dict):          # rule 1: \/odds is a dict; \/historical-odds is a list\n        return None\n    if not p.get(\"active\"):              # rule 2: skip suspended \/ inactive prices\n        return None\n    price = p.get(\"price\")\n    if not price or price <= 0:          # rule 3: some books ship price=0 with active=true\n        return None\n    return price\n\ndef book_prices(odds, slug, market_id):\n    # All usable outcome prices for one book + market, keyed by outcomeId.\n    book = odds.get(\"bookmakerOdds\", {}).get(slug)\n    if not book or book.get(\"suspended\"):   # rule 4: respect book-level suspension\n        return {}\n    market = book.get(\"markets\", {}).get(str(market_id))\n    if not market:\n        return {}\n    out = {}\n    for oid, outcome in market[\"outcomes\"].items():\n        price = usable_price(outcome)\n        if price:\n            out[oid] = price\n    return out\n\nprint(book_prices(odds, \"pinnacle\", 131))\n# {'131': 1.598, '132': 2.53}    # Home \/ Away moneyline\n<\/code><\/pre>\n<p>The single most common mistake is <strong>mixing the live and historical shapes<\/strong>: <code>players[\"0\"]<\/code> is a dict (one price) on <code>\/odds<\/code> but a <em>list<\/em> of snapshots on <code>\/historical-odds<\/code>. Rule 1 above catches it explicitly. More on historical in Step 7.<\/p>\n<h2>Step 5: Turning integer IDs into names<\/h2>\n<p>The odds feed is all integers. Human-readable names live in the <code>\/markets<\/code> catalog, one call per sport. Build two lookup dicts and you're done:<\/p>\n<pre class=\"wp-block-code\"><code>catalog = api(\"markets\", sportId=13)   # 13 = baseball\n# Each entry: {marketId, marketName, handicap, period, marketType, playerProp, outcomes}\n\nmarket_names = {m[\"marketId\"]: m[\"marketName\"] for m in catalog}\noutcome_names = {\n    (m[\"marketId\"], o[\"outcomeId\"]): o[\"outcomeName\"]\n    for m in catalog for o in m.get(\"outcomes\", [])\n}\n\nprint(market_names[131])               # 'Winner (incl. extra innings)'\nprint(outcome_names[(131, 131)],\n      outcome_names[(131, 132)])        # '1' '2'  (home \/ away)\n<\/code><\/pre>\n<p>Don't hardcode the whole catalog &mdash; soccer alone has <strong>32,814 market IDs<\/strong> once you count every handicap and total line variant. Look up the few you display, cache the dict, and move on. The same <code>marketName<\/code> (\"Asian Handicap\", \"Over Under\") repeats with different <code>handicap<\/code> and <code>period<\/code> values, each carrying its own <code>marketId<\/code> &mdash; which is exactly why the feed keys on IDs, not names.<\/p>\n<h2>Step 6: exchangeMeta &mdash; the order-book ladder<\/h2>\n<p>This is the field that breaks naive parsers. On a sportsbook it's <code>null<\/code>. On an <strong>exchange<\/strong> &mdash; Polymarket, Kalshi, Betfair Exchange &mdash; it carries the depth-of-book ladder. Here's a real Polymarket outcome's <code>exchangeMeta<\/code>:<\/p>\n<pre class=\"wp-block-code\"><code>\"exchangeMeta\": {\n  \"back\": [\n    {\"cents\": 0.72, \"price\": 1.389, \"size\": 315.0,  \"limit\": 226.8},\n    {\"cents\": 0.73, \"price\": 1.37,  \"size\": 631.0,  \"limit\": 460.63},\n    {\"cents\": 0.74, \"price\": 1.351, \"size\": 1520.13,\"limit\": 1124.9}\n  ],\n  \"lay\": [\n    {\"cents\": 0.29, \"price\": 3.448, \"size\": 500.0,  \"limit\": 145.0},\n    {\"cents\": 0.30, \"price\": 3.333, \"size\": 599.0,  \"limit\": 179.7},\n    {\"cents\": 0.31, \"price\": 3.226, \"size\": 948.13, \"limit\": 293.92}\n  ],\n  \"bookmakerLayOutcomeId\": \"84316830488204559480713842070874685117114632260770762655793842995494422951947\"\n}\n<\/code><\/pre>\n<p>What you're looking at:<\/p>\n<ul>\n<li><strong><code>back<\/code><\/strong> is a list of price levels you can bet <em>at<\/em>, best first &mdash; the top entry's <code>price<\/code> equals the outcome's main <code>price<\/code>. <strong><code>lay<\/code><\/strong> is the opposite side (laying \/ selling).<\/li>\n<li>Each level has <code>price<\/code> (decimal odds), <code>size<\/code> (liquidity available), and <code>cents<\/code> (the native 0&ndash;1 share price &mdash; relevant on prediction markets like Polymarket and Kalshi).<\/li>\n<li><code>bookmakerLayOutcomeId<\/code> is the opposite side's token\/handle (Polymarket ships it; Kalshi doesn't). Drop it straight into the venue's order-book endpoint if you need raw depth.<\/li>\n<\/ul>\n<p>The key parsing lesson: <strong>read the top of the <code>back<\/code> ladder, not a flat scalar.<\/strong> Older exchange payloads used different shapes &mdash; a flat <code>lay<\/code> number, or <code>availableToBack\/availableToLay<\/code> on Betfair. Parse defensively:<\/p>\n<pre class=\"wp-block-code\"><code>def best_back(outcome):\n    p = outcome[\"players\"][\"0\"]\n    meta = p.get(\"exchangeMeta\")\n    if not meta:                       # sportsbook: null or {}\n        return p.get(\"price\")\n    back = meta.get(\"back\")\n    if isinstance(back, list) and back:\n        return back[0].get(\"price\")    # best back = top of ladder\n    if isinstance(back, (int, float)): # legacy flat shape\n        return back\n    return p.get(\"price\")              # fall back to the main price\n<\/code><\/pre>\n<p>For the full Polymarket \/ Kalshi structure &mdash; condition IDs, token IDs, and the Gamma-vs-CLOB split &mdash; see the <a href=\"https:\/\/oddspapi.io\/blog\/polymarket-api-gamma-clob-json-format\/\">Polymarket API deep dive<\/a>.<\/p>\n<h2>Step 7: The historical feed has a different shape<\/h2>\n<p>The <code>\/historical-odds<\/code> endpoint looks similar but differs in two ways that will bite you if you reuse your live parser verbatim:<\/p>\n<ol>\n<li>The top-level key is <code>bookmakers<\/code>, <strong>not<\/strong> <code>bookmakerOdds<\/code>.<\/li>\n<li><code>players[\"0\"]<\/code> is a <strong>list of snapshots<\/strong> (full price history), not a single dict.<\/li>\n<\/ol>\n<pre class=\"wp-block-code\"><code>hist = api(\"historical-odds\", fixtureId=\"id1300010963302659\",\n           bookmakers=\"pinnacle,bet365,draftkings\")   # max 3 books per call\n\nsnaps = (hist[\"bookmakers\"][\"pinnacle\"][\"markets\"][\"131\"]\n             [\"outcomes\"][\"131\"][\"players\"][\"0\"])      # a LIST\n\nprint(len(snaps), \"snapshots\")          # 47 snapshots\nprint(snaps[0])\n# {'createdAt': '2026-06-05T09:57:12.731Z', 'price': 1.613,\n#  'limit': 3058, 'active': true, 'exchangeMeta': null}\n\nfor s in snaps:\n    print(s[\"createdAt\"], s[\"price\"])   # full line-movement history\n<\/code><\/pre>\n<p>Historical data is capped at <strong>3 bookmakers per call<\/strong> &mdash; loop with different combos and merge if you need more. And unlike most providers who paywall it, OddsPapi's historical feed is on the <strong>free tier<\/strong>, which makes it the cheapest way to <a href=\"https:\/\/oddspapi.io\/blog\/historical-odds-csv-excel-backtesting\/\">backtest a model<\/a> or compute closing-line value.<\/p>\n<h2>Putting it together: parse, name, compare<\/h2>\n<p>A complete, runnable example &mdash; pull the moneyline across every book, label it, de-vig the sharp line, and find the best available price. All numbers are the live Cubs vs Giants pull:<\/p>\n<pre class=\"wp-block-code\"><code>odds = api(\"odds\", fixtureId=\"id1300010963302659\")\nnames = {(m[\"marketId\"], o[\"outcomeId\"]): o[\"outcomeName\"]\n         for m in api(\"markets\", sportId=13) for o in m.get(\"outcomes\", [])}\n\nMONEYLINE = 131\nboard = {}   # slug -> {outcomeId: price}\nfor slug in odds.get(\"bookmakerOdds\", {}):\n    prices = book_prices(odds, slug, MONEYLINE)\n    if len(prices) == 2:                 # both sides priced\n        board[slug] = prices\n\n# Best price per side across the whole board\nfor oid in (\"131\", \"132\"):\n    best = max(board.items(), key=lambda kv: kv[1][oid])\n    label = names.get((MONEYLINE, int(oid)), oid)\n    print(f\"Best '{label}': {best[1][oid]} @ {best[0]}\")\n# Best '1': 1.613 @ kalshi\n# Best '2': 2.564 @ kalshi\n\n# De-vig Pinnacle for a fair-probability benchmark\nh, a = board[\"pinnacle\"][\"131\"], board[\"pinnacle\"][\"132\"]\nih, ia = 1\/h, 1\/a\noverround = ih + ia\nprint(f\"Pinnacle vig: {(overround-1)*100:.2f}%\")        # 2.10%\nprint(f\"Fair: home {ih\/overround*100:.1f}% \/ away {ia\/overround*100:.1f}%\")\n# Fair: home 61.3% \/ away 38.7%\n<\/code><\/pre>\n<p>What the live data showed: 10 of the 14 books priced the moneyline. US sportsbooks (DraftKings, FanDuel, BetMGM, Caesars) ran <strong>4.0&ndash;4.7% vig<\/strong>, Pinnacle <strong>2.10%<\/strong>, and the prediction markets &mdash; Kalshi and Polymarket &mdash; landed at <strong>1.00%<\/strong>, the tightest in the field and right on Pinnacle's no-vig fair line. Those are the <em>best available prices<\/em>, captured at one moment; early lines tighten by game time, so treat them as a snapshot, not a standing edge. For a reusable scanner, see <a href=\"https:\/\/oddspapi.io\/blog\/line-shopping-python-best-odds\/\">line shopping in Python<\/a>.<\/p>\n<h2>Where to go from here<\/h2>\n<p>You now have the whole map: the envelope, the five-level path, the outcome fields, the exchange ladder, and the historical shape. The same parser works across 350+ bookmakers and every sport &mdash; from a single MLB moneyline to an Asian Handicap board to a Polymarket order book. If you'd rather not poll at all, the <a href=\"https:\/\/oddspapi.io\/blog\/websocket-odds-api-real-time-betting-data\/\">WebSocket feed<\/a> pushes the same JSON shape in real time, and the <a href=\"https:\/\/oddspapi.io\/blog\/odds-feed-api-real-time-bookmaker-data\/\">odds feed overview<\/a> covers the product side. To go straight from this JSON into analysis, the <a href=\"https:\/\/oddspapi.io\/blog\/pandas-odds-api-dataframe-tutorial\/\">pandas tutorial<\/a> flattens it into a DataFrame in ten lines.<\/p>\n<p><strong>Stop reverse-engineering undocumented feeds. <a href=\"https:\/\/oddspapi.io\/\">Get your free API key<\/a> and parse a real one.<\/strong><\/p>\n<h2>Frequently Asked Questions<\/h2>\n<h3>Where is the actual price in the OddsPapi odds JSON?<\/h3>\n<p>Five levels deep: <code>bookmakerOdds[slug][\"markets\"][marketId][\"outcomes\"][outcomeId][\"players\"][\"0\"][\"price\"]<\/code>. The market and outcome IDs are stringified integers, and on the live <code>\/odds<\/code> endpoint <code>players[\"0\"]<\/code> is a dict holding one current price.<\/p>\n<h3>Why are markets and outcomes dicts instead of arrays?<\/h3>\n<p>They're keyed by integer ID (as strings) so you can look up a specific market or outcome in O(1) without scanning a list. A single fixture can carry hundreds of markets, so ID-keyed dicts keep both the payload and your lookups fast.<\/p>\n<h3>What's the difference between the live and historical JSON?<\/h3>\n<p>The live <code>\/odds<\/code> feed uses the top-level key <code>bookmakerOdds<\/code> and <code>players[\"0\"]<\/code> is a single dict. The <code>\/historical-odds<\/code> feed uses the key <code>bookmakers<\/code> and <code>players[\"0\"]<\/code> is a list of price snapshots over time. Historical is capped at 3 bookmakers per call and is free.<\/p>\n<h3>What is the exchangeMeta field?<\/h3>\n<p>On sportsbooks it's <code>null<\/code>. On exchanges (Polymarket, Kalshi, Betfair Exchange) it carries the order-book depth as <code>back<\/code> and <code>lay<\/code> ladders &mdash; lists of price levels with <code>price<\/code>, <code>size<\/code>, and native <code>cents<\/code> share prices. Read the top of the <code>back<\/code> ladder for the best price.<\/p>\n<h3>How do I get human-readable market and outcome names?<\/h3>\n<p>The odds feed only ships integer IDs. Call <code>\/markets?sportId=X<\/code> once, build <code>{marketId: marketName}<\/code> and <code>{(marketId, outcomeId): outcomeName}<\/code> lookup dicts, and cache them. Don't hardcode the catalog &mdash; soccer alone has over 32,000 market IDs.<\/p>\n<h3>Do I need to convert decimal odds to American myself?<\/h3>\n<p>No. Every outcome ships <code>price<\/code> (decimal), <code>priceAmerican<\/code>, and <code>priceFractional<\/code> together, so you just read the format you want. The American and fractional fields are strings.<\/p>\n<p><script type=\"application\/ld+json\">\n{\n  \"@context\": \"https:\/\/schema.org\",\n  \"@type\": \"FAQPage\",\n  \"mainEntity\": [\n    {\"@type\":\"Question\",\"name\":\"Where is the actual price in the OddsPapi odds JSON?\",\"acceptedAnswer\":{\"@type\":\"Answer\",\"text\":\"Five levels deep: bookmakerOdds[slug][markets][marketId][outcomes][outcomeId][players][0][price]. Market and outcome IDs are stringified integers, and on the live \/odds endpoint players[0] is a dict holding one current price.\"}},\n    {\"@type\":\"Question\",\"name\":\"Why are markets and outcomes dicts instead of arrays?\",\"acceptedAnswer\":{\"@type\":\"Answer\",\"text\":\"They are keyed by integer ID (as strings) so you can look up a specific market or outcome in constant time without scanning a list. A single fixture can carry hundreds of markets, so ID-keyed dicts keep the payload and lookups fast.\"}},\n    {\"@type\":\"Question\",\"name\":\"What is the difference between the live and historical odds JSON?\",\"acceptedAnswer\":{\"@type\":\"Answer\",\"text\":\"The live \/odds feed uses the top-level key bookmakerOdds and players[0] is a single dict. The \/historical-odds feed uses the key bookmakers and players[0] is a list of price snapshots over time. Historical is capped at 3 bookmakers per call and is free.\"}},\n    {\"@type\":\"Question\",\"name\":\"What is the exchangeMeta field?\",\"acceptedAnswer\":{\"@type\":\"Answer\",\"text\":\"On sportsbooks it is null. On exchanges like Polymarket, Kalshi and Betfair Exchange it carries order-book depth as back and lay ladders, lists of price levels with price, size and native cents share prices. Read the top of the back ladder for the best price.\"}},\n    {\"@type\":\"Question\",\"name\":\"How do I get human-readable market and outcome names?\",\"acceptedAnswer\":{\"@type\":\"Answer\",\"text\":\"The odds feed only ships integer IDs. Call \/markets?sportId=X once, build {marketId: marketName} and {(marketId, outcomeId): outcomeName} lookup dicts, and cache them. Soccer alone has over 32,000 market IDs, so do not hardcode the catalog.\"}},\n    {\"@type\":\"Question\",\"name\":\"Do I need to convert decimal odds to American myself?\",\"acceptedAnswer\":{\"@type\":\"Answer\",\"text\":\"No. Every outcome ships price (decimal), priceAmerican and priceFractional together, so you read the format you want. The American and fractional fields are strings.\"}}\n  ]\n}\n<\/script><\/p>\n<p><!--\nFocus Keyphrase: json odds feed\nSEO Title: JSON Odds Feed: Format, Schema & Parsing in Python (Free API)\nMeta Description: The OddsPapi JSON odds feed schema explained field-by-field, with defensive Python parsing for 350+ bookmakers. Stop guessing at nested odds JSON.\nSlug: json-odds-feed-format-parsing\n--><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Stop guessing at nested odds JSON. The OddsPapi feed schema explained field-by-field with defensive Python parsing for 350+ bookmakers. Free tier.<\/p>\n","protected":false},"author":2,"featured_media":2974,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[7],"tags":[12,8,9,11,10],"class_list":["post-2973","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-how-to-guides","tag-betting-data","tag-free-api","tag-odds-api","tag-python","tag-sports-betting-api"],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v26.4 - https:\/\/yoast.com\/wordpress\/plugins\/seo\/ -->\n<title>JSON Odds Feed: Format, Schema &amp; Parsing in Python (Free API) | OddsPapi Blog<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"JSON Odds Feed: Format, Schema &amp; Parsing in Python (Free API) | OddsPapi Blog\" \/>\n<meta property=\"og:description\" content=\"Stop guessing at nested odds JSON. The OddsPapi feed schema explained field-by-field with defensive Python parsing for 350+ bookmakers. Free tier.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/\" \/>\n<meta property=\"og:site_name\" content=\"OddsPapi Blog\" \/>\n<meta property=\"article:published_time\" content=\"2026-06-16T10:00:00+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/oddspapi.io\/blog\/wp-content\/uploads\/2026\/06\/json-odds-feed-format-parsing-scaled.webp\" \/>\n\t<meta property=\"og:image:width\" content=\"2560\" \/>\n\t<meta property=\"og:image:height\" content=\"1429\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/webp\" \/>\n<meta name=\"author\" content=\"Odds API Writer\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:image\" content=\"https:\/\/oddspapi.io\/logo-v2.webp\" \/>\n<meta name=\"twitter:creator\" content=\"@oddspapiapi\" \/>\n<meta name=\"twitter:site\" content=\"@oddspapiapi\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"Odds API Writer\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"8 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/#article\",\"isPartOf\":{\"@id\":\"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/\"},\"author\":{\"name\":\"Odds API Writer\",\"@id\":\"https:\/\/oddspapi.io\/blog\/#\/schema\/person\/b6f21e649c4f556f0a95c23a0f1efa13\"},\"headline\":\"JSON Odds Feed: Format, Schema &#038; Parsing in Python (Free API)\",\"datePublished\":\"2026-06-16T10:00:00+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/\"},\"wordCount\":1526,\"commentCount\":0,\"publisher\":{\"@id\":\"https:\/\/oddspapi.io\/blog\/#organization\"},\"image\":{\"@id\":\"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/#primaryimage\"},\"thumbnailUrl\":\"https:\/\/oddspapi.io\/blog\/wp-content\/uploads\/2026\/06\/json-odds-feed-format-parsing-scaled.webp\",\"keywords\":[\"Betting Data\",\"Free API\",\"Odds API\",\"Python\",\"Sports Betting API\"],\"articleSection\":[\"How To Guides\"],\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"CommentAction\",\"name\":\"Comment\",\"target\":[\"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/#respond\"]}]},{\"@type\":\"WebPage\",\"@id\":\"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/\",\"url\":\"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/\",\"name\":\"JSON Odds Feed: Format, Schema & Parsing in Python (Free API) | OddsPapi Blog\",\"isPartOf\":{\"@id\":\"https:\/\/oddspapi.io\/blog\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/#primaryimage\"},\"image\":{\"@id\":\"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/#primaryimage\"},\"thumbnailUrl\":\"https:\/\/oddspapi.io\/blog\/wp-content\/uploads\/2026\/06\/json-odds-feed-format-parsing-scaled.webp\",\"datePublished\":\"2026-06-16T10:00:00+00:00\",\"breadcrumb\":{\"@id\":\"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/#primaryimage\",\"url\":\"https:\/\/oddspapi.io\/blog\/wp-content\/uploads\/2026\/06\/json-odds-feed-format-parsing-scaled.webp\",\"contentUrl\":\"https:\/\/oddspapi.io\/blog\/wp-content\/uploads\/2026\/06\/json-odds-feed-format-parsing-scaled.webp\",\"width\":2560,\"height\":1429,\"caption\":\"JSON Odds Feed - OddsPapi API Blog\"},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/oddspapi.io\/blog\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"JSON Odds Feed: Format, Schema &#038; Parsing in Python (Free API)\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/oddspapi.io\/blog\/#website\",\"url\":\"https:\/\/oddspapi.io\/blog\/\",\"name\":\"OddsPapi\",\"description\":\"Sports Odds API Tutorials &amp; Guides\",\"publisher\":{\"@id\":\"https:\/\/oddspapi.io\/blog\/#organization\"},\"alternateName\":\"Odds Papi\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/oddspapi.io\/blog\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"},{\"@type\":\"Organization\",\"@id\":\"https:\/\/oddspapi.io\/blog\/#organization\",\"name\":\"OddsPapi\",\"url\":\"https:\/\/oddspapi.io\/blog\/\",\"logo\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/oddspapi.io\/blog\/#\/schema\/logo\/image\/\",\"url\":\"https:\/\/oddspapi.io\/blog\/wp-content\/uploads\/2025\/11\/oddspapi.png\",\"contentUrl\":\"https:\/\/oddspapi.io\/blog\/wp-content\/uploads\/2025\/11\/oddspapi.png\",\"width\":135,\"height\":135,\"caption\":\"OddsPapi\"},\"image\":{\"@id\":\"https:\/\/oddspapi.io\/blog\/#\/schema\/logo\/image\/\"},\"sameAs\":[\"https:\/\/x.com\/oddspapiapi\"]},{\"@type\":\"Person\",\"@id\":\"https:\/\/oddspapi.io\/blog\/#\/schema\/person\/b6f21e649c4f556f0a95c23a0f1efa13\",\"name\":\"Odds API Writer\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/oddspapi.io\/blog\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/33b204f24af3d02e35b25ae730c0536121ca6a783fdb196e7611c9e49fcd13eb?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/33b204f24af3d02e35b25ae730c0536121ca6a783fdb196e7611c9e49fcd13eb?s=96&d=mm&r=g\",\"caption\":\"Odds API Writer\"},\"url\":\"https:\/\/oddspapi.io\/blog\/author\/andy-lavelle\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"JSON Odds Feed: Format, Schema & Parsing in Python (Free API) | OddsPapi Blog","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/","og_locale":"en_US","og_type":"article","og_title":"JSON Odds Feed: Format, Schema & Parsing in Python (Free API) | OddsPapi Blog","og_description":"Stop guessing at nested odds JSON. The OddsPapi feed schema explained field-by-field with defensive Python parsing for 350+ bookmakers. Free tier.","og_url":"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/","og_site_name":"OddsPapi Blog","article_published_time":"2026-06-16T10:00:00+00:00","og_image":[{"width":2560,"height":1429,"url":"https:\/\/oddspapi.io\/blog\/wp-content\/uploads\/2026\/06\/json-odds-feed-format-parsing-scaled.webp","type":"image\/webp"}],"author":"Odds API Writer","twitter_card":"summary_large_image","twitter_image":"https:\/\/oddspapi.io\/logo-v2.webp","twitter_creator":"@oddspapiapi","twitter_site":"@oddspapiapi","twitter_misc":{"Written by":"Odds API Writer","Est. reading time":"8 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/#article","isPartOf":{"@id":"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/"},"author":{"name":"Odds API Writer","@id":"https:\/\/oddspapi.io\/blog\/#\/schema\/person\/b6f21e649c4f556f0a95c23a0f1efa13"},"headline":"JSON Odds Feed: Format, Schema &#038; Parsing in Python (Free API)","datePublished":"2026-06-16T10:00:00+00:00","mainEntityOfPage":{"@id":"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/"},"wordCount":1526,"commentCount":0,"publisher":{"@id":"https:\/\/oddspapi.io\/blog\/#organization"},"image":{"@id":"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/#primaryimage"},"thumbnailUrl":"https:\/\/oddspapi.io\/blog\/wp-content\/uploads\/2026\/06\/json-odds-feed-format-parsing-scaled.webp","keywords":["Betting Data","Free API","Odds API","Python","Sports Betting API"],"articleSection":["How To Guides"],"inLanguage":"en-US","potentialAction":[{"@type":"CommentAction","name":"Comment","target":["https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/#respond"]}]},{"@type":"WebPage","@id":"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/","url":"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/","name":"JSON Odds Feed: Format, Schema & Parsing in Python (Free API) | OddsPapi Blog","isPartOf":{"@id":"https:\/\/oddspapi.io\/blog\/#website"},"primaryImageOfPage":{"@id":"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/#primaryimage"},"image":{"@id":"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/#primaryimage"},"thumbnailUrl":"https:\/\/oddspapi.io\/blog\/wp-content\/uploads\/2026\/06\/json-odds-feed-format-parsing-scaled.webp","datePublished":"2026-06-16T10:00:00+00:00","breadcrumb":{"@id":"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/"]}]},{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/#primaryimage","url":"https:\/\/oddspapi.io\/blog\/wp-content\/uploads\/2026\/06\/json-odds-feed-format-parsing-scaled.webp","contentUrl":"https:\/\/oddspapi.io\/blog\/wp-content\/uploads\/2026\/06\/json-odds-feed-format-parsing-scaled.webp","width":2560,"height":1429,"caption":"JSON Odds Feed - OddsPapi API Blog"},{"@type":"BreadcrumbList","@id":"https:\/\/oddspapi.io\/blog\/json-odds-feed-format-parsing\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/oddspapi.io\/blog\/"},{"@type":"ListItem","position":2,"name":"JSON Odds Feed: Format, Schema &#038; Parsing in Python (Free API)"}]},{"@type":"WebSite","@id":"https:\/\/oddspapi.io\/blog\/#website","url":"https:\/\/oddspapi.io\/blog\/","name":"OddsPapi","description":"Sports Odds API Tutorials &amp; Guides","publisher":{"@id":"https:\/\/oddspapi.io\/blog\/#organization"},"alternateName":"Odds Papi","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/oddspapi.io\/blog\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"},{"@type":"Organization","@id":"https:\/\/oddspapi.io\/blog\/#organization","name":"OddsPapi","url":"https:\/\/oddspapi.io\/blog\/","logo":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/oddspapi.io\/blog\/#\/schema\/logo\/image\/","url":"https:\/\/oddspapi.io\/blog\/wp-content\/uploads\/2025\/11\/oddspapi.png","contentUrl":"https:\/\/oddspapi.io\/blog\/wp-content\/uploads\/2025\/11\/oddspapi.png","width":135,"height":135,"caption":"OddsPapi"},"image":{"@id":"https:\/\/oddspapi.io\/blog\/#\/schema\/logo\/image\/"},"sameAs":["https:\/\/x.com\/oddspapiapi"]},{"@type":"Person","@id":"https:\/\/oddspapi.io\/blog\/#\/schema\/person\/b6f21e649c4f556f0a95c23a0f1efa13","name":"Odds API Writer","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/oddspapi.io\/blog\/#\/schema\/person\/image\/","url":"https:\/\/secure.gravatar.com\/avatar\/33b204f24af3d02e35b25ae730c0536121ca6a783fdb196e7611c9e49fcd13eb?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/33b204f24af3d02e35b25ae730c0536121ca6a783fdb196e7611c9e49fcd13eb?s=96&d=mm&r=g","caption":"Odds API Writer"},"url":"https:\/\/oddspapi.io\/blog\/author\/andy-lavelle\/"}]}},"_links":{"self":[{"href":"https:\/\/oddspapi.io\/blog\/wp-json\/wp\/v2\/posts\/2973","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/oddspapi.io\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/oddspapi.io\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/oddspapi.io\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/oddspapi.io\/blog\/wp-json\/wp\/v2\/comments?post=2973"}],"version-history":[{"count":1,"href":"https:\/\/oddspapi.io\/blog\/wp-json\/wp\/v2\/posts\/2973\/revisions"}],"predecessor-version":[{"id":2975,"href":"https:\/\/oddspapi.io\/blog\/wp-json\/wp\/v2\/posts\/2973\/revisions\/2975"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/oddspapi.io\/blog\/wp-json\/wp\/v2\/media\/2974"}],"wp:attachment":[{"href":"https:\/\/oddspapi.io\/blog\/wp-json\/wp\/v2\/media?parent=2973"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/oddspapi.io\/blog\/wp-json\/wp\/v2\/categories?post=2973"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/oddspapi.io\/blog\/wp-json\/wp\/v2\/tags?post=2973"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}