Name: Sports Odds API: Live Bookmaker Odds for 14 Sports
Brand: odds-api.net
SKU: api-odds-api.net-sports-odds
Availability: InStock
Author: API Market

# Sports Odds API

## Overview

The Sports Odds API by odds-api.net delivers bookmaker odds for upcoming and live events across 14 sports, including soccer, basketball, American football, tennis, cricket, ice hockey, baseball, MMA and CS2. Start with the catalog endpoints to discover sports, leagues and bookmakers, search events by sport, league and start time, then pull a full odds snapshot for any event with every market, line and price from every bookmaker that covers it.

It is built for developers of odds comparison sites, betting tools, sports analytics dashboards and trading models who need normalised odds from many bookmakers in one JSON format. Each snapshot tells you when each bookmaker was last updated, so you can judge freshness before you use a price.

## Features

*   **5 endpoints**: Sports, leagues and bookmaker catalogs, event search, and per-event odds snapshots.
*   **14 sports**: Soccer, basketball, American football, tennis, cricket, ice hockey, baseball, handball, rugby, MMA, table tennis, Aussie rules and CS2.
*   **Hundreds of bookmakers**: Odds from bookmakers across many countries, filterable by country code.
*   **Every market**: Moneyline, spreads, totals, both teams to score and more, by period.
*   **Freshness timestamps**: Each snapshot includes the last update time per bookmaker.
*   **Event search and pagination**: Filter by sport, league and start-time window, and page with `cursor`.
*   **Live and pre-match**: Includes event states so you can separate scheduled and live games.

## Use Cases

*   **Odds comparison sites**: Show the best price for each outcome across bookmakers.
*   **Betting tools and bots**: Feed models and alerts with normalised odds.
*   **Sports analytics**: Track line movement and market consensus over time.
*   **Media and fantasy apps**: Display current odds next to fixtures and previews.
*   **Arbitrage and value detection**: Compare prices across bookmakers for the same market.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/odds-api.net/sports-odds
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. List Sports

Returns the sports currently covered, such as soccer, basketball, tennis, cricket, ice hockey, MMA and esports (CS2).

**Method:** `GET`

**Endpoint:** `/sports`

**Parameters:**

None.

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/odds-api.net/sports-odds/sports" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "items": [
    "american football",
    "aussie rules"
  ]
}
```

#### 2. List Leagues

Returns the leagues and competitions with odds coverage. Filter by `sport` to get the leagues of one sport.

**Method:** `GET`

**Endpoint:** `/leagues`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| sport | query | Sport filter. Use `/sports` to discover supported values. | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/odds-api.net/sports-odds/leagues?sport=basketball" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "items": [
    "Argentina La Liga",
    "BBL Pokal"
  ]
}
```

#### 3. List Bookmakers

Returns the bookmakers in the feed with the countries they operate in. Filter by `country_code` to get the bookmakers of one market.

**Method:** `GET`

**Endpoint:** `/bookmakers`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| country_code | query | Comma-separated country code filter, for example `AU` or `AU,UK`. | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/odds-api.net/sports-odds/bookmakers?country_code=AU" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "items": [
    {
      "bookmaker": "123bet",
      "country_codes": [
        "AU"
      ],
      "source_bookmaker": "betplay_au"
    },
    {
      "bookmaker": "baggybet",
      "country_codes": [
        "AU"
      ],
      "source_bookmaker": "okebet"
    }
  ]
}
```

#### 4. Search Events

Searches upcoming and live events with their teams, league, start time and state. Filter by sport, league and start-time window, and page through results with `cursor`.

**Method:** `GET`

**Endpoint:** `/events`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| sport | query | Sport filter. Use `/sports` to discover supported values. | string | No | - | - |
| league | query | League filter. Use `/leagues?sport=...` to discover supported values. | string | No | - | - |
| start_from | query | Unix seconds lower bound for event start time. Use bounded windows in production polling. | string | No | - | - |
| start_to | query | Unix seconds upper bound for event start time. Keep windows narrow for hot sync jobs. | string | No | - | - |
| cursor | query | Pagination cursor from the previous `next_cursor`. Keep filters identical between pages. | string | No | - | - |
| limit | query | Maximum items to return. Respect the caps returned by `/limits`. | integer | No | `200` | 1000 |
| include_bookmaker_ids | query | When true, include bookmaker-to-odds-data IDs and preview ID maps on event responses. | string | No | - | - |
| include_source | query | When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept. | string | No | - | - |
| include_opportunity_counts | query | Include Opportunity Counts | string | No | - | - |
| not_started_only | query | Not Started Only | boolean | No | `false` | - |
| not_started_buffer_seconds | query | Not Started Buffer Seconds | integer | No | `120` | - |
| event_states | query | Lifecycle filter. Requesting in_play automatically applies the live lookback window. | string | No | - | - |
| live_candidates | query | Include already-started events that remain candidates for live play; this is not confirmation of current play. | boolean | No | `false` | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/odds-api.net/sports-odds/events?sport=soccer&limit=2&not_started_only=true" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "items": [
    {
      "event_id": "1751650183",
      "sport": "soccer",
      "league": "Japan J2 League",
      "start_time": 1791108000,
      "home_team": "Tegevajaro Miyazaki",
      "away_team": "Omiya Ardija",
      "event_state": "scheduled",
      "event_state_certainty": "inferred",
      "event_state_source": "schedule_start_time",
      "state_observed_at": 1791103557,
      "actual_started_at": null,
      "last_live_at": null,
      "finished_at": null,
      "live_candidate": false,
      "event_state_stale": false,
      "live_status": "upcoming",
      "has_available_bets": true,
      "last_capture": null,
      "bookmakers": {
        "betfred": "Japan J2 League:37058605:betfred",
        "betsson_dk": "Japan J2 League:f-up144QRMi0CWHH0xW88UgQ:betsson_dk",
        "toto": "Japan J. League 2:12675083:toto",
        "draftkings": "Japan - J-League 2:34738039:draftkings",
        "betnation": "Japan J-League Division 2:823050:betnation",
        "sportsbetio": "Japan - J.League 2:U3BvcnRzYmV0TmV3R3JhcGhxbEV2ZW50OjAwMTBjMzExMjMwMDAwMDAwMDAwMDAwMA==:sportsbetio",
        "winamax_de": "J2-League:72151204:winamax_de",
        "888sport": "Japanese J-League 2:8311537:888sport",
        "williamhill": "Japanese J-League 2:OB_EV41340876:williamhill",
        "pinnacle": "Japan - J2 League:1637424335:pinnacle",
        "stakeco": "J2 League:29749785:stakeco",
        "cloudbet": "Japan - J.League 2:36529104:cloudbet",
        "betsson": "Japan J2 League:f-up144QRMi0CWHH0xW88UgQ:betsson",
        "rivalo": "Japan J2 League:ee9afbad-ab77-47bb-84c7-bd779cea0e33:rivalo",
        "betgoodwin": "J2 League 2027:315591573530898432:betgoodwin",
        "caesars": "Japanese J-League 2:9638071d-120d-484e-8fe8-60476e2c5193:caesars",
        "pointsbet": "Japanese J2 League:2904908:pointsbet",
        "bet25": "Japan J.League 2:6718882:bet25",
        "betdaq": "J. League 2:15211303:betdaq",
        "mintbet": "Japan J. League 2:14067831:mintbet",
        "pokerstars": "Japan J2 League:36124534:pokerstars",
        "sportsbet": "Japanese J League 2:10987700:sportsbet",
        "fanduel": "Japanese J2 League:36124534:fanduel",
        "sportiumco": "Japón J2 League:13938918342:sportiumco",
        "betfair": "Japanese J League 2:36124534:betfair"
      },
      "league_image_url": null,
      "league_image_asset_slug": null,
      "home_team_logo_url": null,
      "away_team_logo_url": null,
      "team_logo_manifest_url": null,
      "exchange": null
    },
    {
      "event_id": "2898201156",
      "sport": "soccer",
      "league": "Liga Portugal 2",
      "start_time": 1791108000,
      "home_team": "Farense",
      "away_team": "Chaves",
      "event_state": "scheduled",
      "event_state_certainty": "inferred",
      "event_state_source": "schedule_start_time",
      "state_observed_at": 1791103546,
      "actual_started_at": null,
      "last_live_at": null,
      "finished_at": null,
      "live_candidate": false,
      "event_state_stale": false,
      "live_status": "upcoming",
      "has_available_bets": true,
      "last_capture": null,
      "bookmakers": {
        "nordicbet_se": "Portugal Liga 2:f-MOhPN6qYBEOF8L5EymDANA:nordicbet_se",
        "nordicbet_dk": "Portugal Liga 2:f-MOhPN6qYBEOF8L5EymDANA:nordicbet_dk",
        "toto": "Portugal Segunda Liga:12602662:toto",
        "betsson_dk": "Portugal Liga 2:f-MOhPN6qYBEOF8L5EymDANA:betsson_dk",
        "fanduel": "Portugal - Segunda Liga:36124393:fanduel",
        "draftkings": "Portugal - Segunda Liga:34737203:draftkings",
        "mryoker": "Portugal. Liga 2:68459797:mryoker",
        "winamax": "Liga Portugal 2:74352002:winamax",
        "betnation": "Portugal Segunda Liga:793137:betnation",
        "stakeco": "Segunda Liga:29748352:stakeco",
        "superbet": "Portugalia - Liga 2:15057397:superbet",
        "betano": "Portugal - Liga 2:92825316:betano",
        "betsson": "Portugal Liga 2:f-MOhPN6qYBEOF8L5EymDANA:betsson",
        "sportsbet": "Portuguese Liga 2:10987588:sportsbet",
        "pinnacle": "Portugal - Liga 2:1637137690:pinnacle",
        "winamax_de": "Liga Portugal 2:74352002:winamax_de",
        "yajuego": "Portugal Segunda Liga:13176112:yajuego",
        "rivalo": "Portugal Liga Portugal 2:64cd855c-89df-4469-bfd1-337a06d787a2:rivalo",
        "betfred": "Portugal Liga 2:37058563:betfred",
        "bovada": "Liga Portugal 2:30587391:bovada",
        "888sport": "Portuguese Liga 2:8311268:888sport",
        "danskespil": "Portugal Segunda Liga:10284421:danskespil",
        "merkur_bets": "Segunda Liga:3197391642:merkur_bets",
        "betfair": "Liga Portugal 2:36124393:betfair",
        "luckia": "Portugal Segunda Liga:12336409:luckia"
      },
      "league_image_url": null,
      "league_image_asset_slug": null,
      "home_team_logo_url": "https://wagerwisewebsiteimg.blob.core.windows.net/team-logos/bundesliga/sc-freiburg.png",
      "away_team_logo_url": null,
      "team_logo_manifest_url": null,
      "exchange": null
    }
  ],
  "next_cursor": "1791108000:2898201156",
  "count": 2,
  "hint": null
}
```

#### 5. Get Event Odds Snapshot

Returns the latest odds for one event from every covered bookmaker: each market, outcome, line and price, with the time each bookmaker last updated. Narrow the result with `bookmakers`, `types`, `market_keys` and `periods`.

**Method:** `GET`

**Endpoint:** `/events/{event_id}/odds/snapshot`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| event_id | path | Canonical event or race identifier from an event list response. | string | Yes | - | - |
| limit | query | Soft item target when `bookmakers` is omitted. Pages contain whole bookmakers and may exceed this target. With an explicit bookmaker filter, all matching lines are returned up to the 25,000-item safety cap. | integer | No | `2000` | 25000 |
| cursor | query | Opaque bookmaker-page cursor from the previous `next_cursor`. Use only when `bookmakers` is omitted and keep all filters identical between pages. | string | No | - | - |
| bookmakers | query | Comma-separated bookmaker allow-list. Explicitly requested bookmakers are returned complete in one response, up to the 25,000-item safety cap. Use `/bookmakers` to discover supported keys. | string | No | - | - |
| types | query | Comma-separated market type allow-list for odds filters. | string | No | - | - |
| market_keys | query | Comma-separated market key allow-list for odds filters. | string | No | - | - |
| periods | query | Comma-separated period allow-list for odds filters. | string | No | - | - |
| price_fields | query | `odds`, `odds,novig`, `odds,fair`, or `all`. Compact clients default to `odds`; existing clients default to current full pricing fields. | string | No | - | - |
| include_source | query | When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept. | string | No | - | - |
| include_debug_ids | query | When true, include internal/subgroup/opposing IDs useful for reconciliation. | string | No | - | - |
| include_unavailable | query | When true, include unavailable or suspended rows where the endpoint supports them. | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/odds-api.net/sports-odds/events/1751650183/odds/snapshot?limit=4" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "event_id": "1751650183",
  "as_of_ts_ms": 1791104267145,
  "snapshot_capture_ts_ms": 1791104267098,
  "bookmaker_as_of_ts_ms": {
    "888sport": 1791103410000
  },
  "oldest_bookmaker_as_of_ts_ms": 1791103410000,
  "target_refresh_interval_seconds": 608,
  "ttl_seconds": 25333,
  "items": [
    {
      "id": "888sport::both teams to score/no (1st half)::both teams to score::1::no::::",
      "event_id": "1751650183",
      "bookmaker": "888sport",
      "bookmaker_name": "888sport",
      "source_type": null,
      "exchange": null,
      "exchange_market_id": null,
      "exchange_selection_id": null,
      "selection_key": "f246736546b13974f2c6ca1047aa1f98e1213c5d",
      "market_group_id": "2451cc91b638a8a6bde38b4c4b9bcde1cd8dce3e",
      "market_key": "both teams to score/no (1st half)",
      "type": "both teams to score",
      "bet_type": "both teams to score",
      "period": 1,
      "period_str": "1st half",
      "metric": "goals",
      "line": "no",
      "side": null,
      "player_name": null,
      "selection_name": "No",
      "source_navigation": {
        "bookmaker": "888sport",
        "parser_bookmaker": "888sport",
        "path": [
          {
            "id": "8311537",
            "id_source": "source_event_id",
            "kind": "event",
            "name": "Tegevajaro Miyazaki vs Omiya Ardija",
            "name_source": "source_event_name"
          },
          {
            "id": "44",
            "id_source": "source_market_id",
            "kind": "market",
            "name": "1st Half - Both Teams to Score",
            "name_source": "source_market_name"
          }
        ],
        "schema_version": "source-navigation.v1"
      },
      "number_of_outcomes": 2,
      "odds": 1.222,
      "odds_no_vig": 1.313,
      "odds_no_vig_multiplicative_method": 1.313
    },
    {
      "id": "888sport::both teams to score/no (2nd half)::both teams to score::2::no::::",
      "event_id": "1751650183",
      "bookmaker": "888sport",
      "bookmaker_name": "888sport",
      "source_type": null,
      "exchange": null,
      "exchange_market_id": null,
      "exchange_selection_id": null,
      "selection_key": "c581f6e12a4f4a885e3f819c9428a54ca3627f65",
      "market_group_id": "efdbaaf66de9ec67a8037beab92d9c46b766826e",
      "market_key": "both teams to score/no (2nd half)",
      "type": "both teams to score",
      "bet_type": "both teams to score",
      "period": 2,
      "period_str": "2nd half",
      "metric": "goals",
      "line": "no",
      "side": null,
      "player_name": null,
      "selection_name": "No",
      "source_navigation": {
        "bookmaker": "888sport",
        "parser_bookmaker": "888sport",
        "path": [
          {
            "id": "8311537",
            "id_source": "source_event_id",
            "kind": "event",
            "name": "Tegevajaro Miyazaki vs Omiya Ardija",
            "name_source": "source_event_name"
          },
          {
            "id": "1388791",
            "id_source": "source_market_id",
            "kind": "market",
            "name": "Second Half Both Team To Score",
            "name_source": "source_market_name"
          }
        ],
        "schema_version": "source-navigation.v1"
      },
      "number_of_outcomes": 2,
      "odds": 1.364,
      "odds_no_vig": 1.47,
      "odds_no_vig_multiplicative_method": 1.47
    }
  ],
  "next_cursor": "bm1.eyJhZnRlcl9ib29rbWFrZXIiOiI4ODhzcG9ydCIsImZpbHRlciI6ImI5N2NkZGQyY2YzYTIwMmYyMzZmNTY3NiIsInYiOjF9",
  "complete": false,
  "bookmakers_included": [
    "888sport"
  ],
  "bookmaker_counts": {
    "888sport": 172
  },
  "resume": "1791104267165-0"
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the response contains the requested data. |
| 400 | Bad Request | A parameter is invalid, for example a malformed time window or limit. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is invalid. |
| 403 | Forbidden | Your API.market subscription does not include this endpoint. |
| 404 | Not Found | The requested resource does not exist. |
| 429 | Too Many Requests | You exceeded 1 request per second or your plan's monthly quota. |
| 500 | Internal Server Error | An unexpected error occurred on the server. Retry after a short wait. |
| 503 | Service Unavailable | The odds service is temporarily unavailable. Retry with backoff. |

## Rate Limits

Each successful request uses 1 API unit. The Free plan includes 1,000 units as a 7-day trial, and the Start plan ($40/month) includes 50,000 units. Both plans allow 1 request per second.

If you exceed the limit you receive a `429 Too Many Requests` response. Throttle your requests, back off before retrying, and honour the `Retry-After` header when it is present.

## FAQ

*   **How do I get the odds for a match?**

    Call `/events` with a `sport` (and optionally `league`) to find the event, then call `/events/{event_id}/odds/snapshot` with its `event_id`.

*   **How fresh are the odds?**

    Each snapshot returns `bookmaker_as_of_ts_ms` with the last update time of every bookmaker, plus the snapshot capture time.

*   **Can I limit the snapshot to some bookmakers or markets?**

    Yes. Use `bookmakers`, `types`, `market_keys` and `periods` to narrow the snapshot.

*   **Are live events included?**

    Yes. Events carry an `event_state`, and `/events` accepts `event_states` and `live_candidates` filters.

*   **What does the snapshot cost?**

    One API unit per successful request, like every other endpoint.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Get upcoming events plus pre-match and live odds from hundreds of bookmakers for soccer, NBA, NFL, tennis and more in one simple JSON sports odds API.

Sports Odds API: Live Bookmaker Odds for 14 Sports