> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apexiumbet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Market data and identifiers - OddsPapi v5 through Apexium

> How the OddsPapi v5 market data served by the Apexium API is organised: sports, tournaments, fixtures, markets, outcomes and odds identifiers, and how they become an order.

The market data of the Apexium API is **OddsPapi v5**: the same paths, parameters, responses and identifiers, under `/v1/{lang}` (see [Languages](https://docs.apexiumbet.com/api-reference/overview.md#languages)). The `fixtureId`, `outcomeId` and `playerId` you read in the odds are the ones you place orders on: there is no mapping between the data and the execution.

> [!NOTE]
>
> OddsPapi documents every field of this data in its own documentation, at [docs.oddspapi.io](https://docs.oddspapi.io). Moving a client that already uses OddsPapi? See [Coming from OddsPapi](https://docs.apexiumbet.com/guides/coming-from-oddspapi.md).

## Sports, tournaments, seasons

* **`sportId`.** Integer. Its two digits start several other identifiers. List them with [`GET /v1/{lang}/sports`](https://docs.apexiumbet.com/coverage).
* **`tournamentId`.** Integer. Belongs to one sport. List them with `GET /v1/{lang}/tournaments`.
* **`seasonId`.** Integer. Belongs to one tournament. List them with `GET /v1/{lang}/seasons`.

## Entity hierarchy

Everything hangs off one tree:

```
Sport
  └── Tournament (recurring competition)
        └── Season (time-bound instance)
              └── Fixture (single match)
                    ├── Participants (teams / competitors)
                    ├── Scores (per period)
                    └── Players (squad members)
```

A **tournament** is the recurring competition ("Premier League"); a **season** is one instance of it ("Premier League 25/26"); a **fixture** is one match in it:

```
Sport:       Soccer                  (sportId=10)
Tournament:  Premier League          (tournamentId=17)
Season:      Premier League 25/26    (seasonId=130281)
Fixture:     Arsenal vs Chelsea      (fixtureId=id1000001770366972)
  ├── participant1Id → Arsenal
  ├── participant2Id → Chelsea
  ├── Scores:  result 2-1, p1 1-0, p2 1-1   (per-period rows)
  └── Players: squads per participant        (player markets)
```

* **The fixture.** It carries the schedule and state: `startTime` (epoch seconds), `statusId`, `participant1Id` and `participant2Id`, `seasonId`, venue.
* **Scores.** They are per period, keyed `result`, `p1`, `p2`, and so on. The `result` row is the authoritative final or current score.
* **Odds.** They attach to a fixture through the [odds identifiers](#odds-identifiers).

## Markets and outcomes

> [!NOTE]
>
> Every selection follows a fixed hierarchy: `marketType → period → handicap → side`, all encoded in the `outcomeId`. The same bet therefore always has the same `marketId` and `outcomeId`, whatever the bookmaker. The player is the one part not in `outcomeId`: it is `playerId`.

### How markets decompose

Every `outcomeId` comes from one deterministic decomposition:

```
marketType → period → handicap (line value) → side (outcome)   [+ optional player]
```

| Level | Field | Meaning |
| - | - | - |
| 1 | `marketType` | The kind of market: `1x2`, `totals`, `spreads`, `spreads-european`, `bothteamsscore`, `drawnobet`, `oddeven`, … |
| 2 | `period` | The segment the market applies to: `fulltime`, `p1`, `p2` |
| 3 | `handicap` | The line value, for example `2.5` or `-0.25`. Each line value is its own `marketId`. `0.0` for markets without a line, such as `1x2` |
| 4 | `outcomeName` | The side: `Over` / `Under`, `1` / `X` / `2`, `Yes` / `No`, … |

Because every line value has its own `marketId`, "Over 2.5" and "Over 3.5" are different markets. Within one `marketId`, the outcomes are only the sides of that exact line.

> [accordion] Worked example: soccer (sportId 10)
>
> Each `marketId` equals its first `outcomeId`, and each line value is its own market:
>
> | marketId | marketName | marketType | period | handicap | outcomeId | outcomeName |
> | -: | - | - | - | -: | -: | - |
> | 101 | Full Time Result | `1x2` | fulltime | 0.0 | 101 | 1 |
> | 101 | Full Time Result | `1x2` | fulltime | 0.0 | 102 | X |
> | 101 | Full Time Result | `1x2` | fulltime | 0.0 | 103 | 2 |
> | 104 | Both Teams To Score | `bothteamsscore` | fulltime | 0.0 | 104 | Yes |
> | 104 | Both Teams To Score | `bothteamsscore` | fulltime | 0.0 | 105 | No |
> | 1010 | Over Under Full Time | `totals` | fulltime | 2.5 | 1010 | Over |
> | 1010 | Over Under Full Time | `totals` | fulltime | 2.5 | 1011 | Under |
> | 1068 | Asian Handicap | `spreads` | fulltime | -0.5 | 1068 | 1 |
> | 1068 | Asian Handicap | `spreads` | fulltime | -0.5 | 1069 | 2 |
> | 10208 | First Half Result | `1x2` | p1 | 0.0 | 10208 | 1 |
> | 10208 | First Half Result | `1x2` | p1 | 0.0 | 10209 | X |
> | 10208 | First Half Result | `1x2` | p1 | 0.0 | 10210 | 2 |
>
> The first row reads: `marketType=1x2`, `period=fulltime`, `handicap=0.0`, `outcomeName=1`, the home side of the full-time result.

The full map of a sport comes from `GET /v1/{lang}/markets?sportId=10`.

### `marketId` and `outcomeId`

* **Shared `marketId`.** All the outcomes of a market share its `marketId`.
* **First outcome.** The first `outcomeId` of a market equals its `marketId`, so you can group outcomes without extra metadata.
* **`marketLength`.** The number of outcomes under a `marketId`: the sides that together form the full probability space. `1x2` has 3.
* **Structure.** Both are integers built as `{sportId (2 digits)}{incrementing number}`: `11xxxx` is basketball, `14xxxx` American football.

All the outcomes of one `marketId` cover every result. Group odds by `marketId` for margin, overround and arbitrage calculations.

## Participants and players

* **`participantId`.** Integer, a team or competitor. List them with `GET /v1/{lang}/participants`.
* **`playerId`.** Integer, for player markets. `0` means a market that is not about a player. List them with `GET /v1/{lang}/players`.

## Fixture IDs

`fixtureId` is a string that encodes several pieces of information:

```
id1100013262926199
```

* `id`: namespace prefix; treat it as opaque
* `11`: `sportId` (2 digits)
* `000132`: `tournamentId` (6 digits)
* `62926199`: native fixture ID

From the `fixtureId` alone you can read the sport and the tournament.

## Odds identifiers

A price is identified by its `oddsId`:

```
{fixtureId}:{bookmaker}:{outcomeId}:{playerId}
```

For example `id1400003160574217:sharpbet:141:0`. Use it as the primary key of the prices you store.

Drop the bookmaker and you have the **selection**, `{fixtureId}:{outcomeId}:{playerId}`: the same bet at every bookmaker, which wins or loses the same way everywhere.

## From odds to an order

An order names a selection with the same three identifiers. To back the price above:

```json theme={null}
{
  "mode": "preview",
  "clientOrderId": "my-order-0003",
  "fixtureId": "id1400003160574217",
  "outcomeId": 141,
  "playerId": 0,
  "side": "back",
  "bookmakers": ["sharpbet"],
  "stake": { "amount": "100.00", "currency": "USD" },
  "minPrice": "1.90",
  "acceptBetterOdds": true,
  "acceptPartialStake": true
}
```

* **Price floor.** `minPrice` is the lowest price you accept: the price you read, or a little below to allow for movement.
* **Bookmakers.** Leave `bookmakers` out to let Apexium split the stake across every bookmaker of your account.
* **Betslip price.** [`GET /v1/betslip`](https://docs.apexiumbet.com/api-reference/overview#betslip) gives the price after your account's rules, which can differ from the market price. See [Feed odds and the betslip](https://docs.apexiumbet.com/guides/feed-odds-and-betslip.md).

See [Preview and place](https://docs.apexiumbet.com/guides/preview-and-place.md).

## Timestamps

The market data uses OddsPapi's two units:

* **Epoch seconds** for schedules: `startTime`, `startTimeFrom`, `startTimeTo`.
* **Epoch milliseconds** for odds updates: `changedAt`, `bookmakerChangedAt`, and the `since` filters.

The `/v1` endpoints of the account and its orders use ISO 8601 strings in UTC instead.

## Efficient polling

* **`since`.** On `fixtures/odds` and `fixtures/odds/main`, pass the last `changedAt` you saw to get only what changed since then.
* **Storage.** Store prices keyed by `oddsId`, so updates replace rows instead of adding them.
* **Limits.** Market data counts against your key's general budget; see [Limits](https://docs.apexiumbet.com/api-reference/limits.md).

## Historical odds and CLV

| Purpose | Endpoint |
| - | - |
| Full price timeline of an outcome | `GET /v1/{lang}/fixtures/odds/historical` |
| Opening and closing line (OLV / CLV) | `GET /v1/{lang}/fixtures/odds/clv` |

Both use the same `oddsId`, so you can join your fills to their history:

* **CLV.** Compare the price you were filled at with the closing line to measure your edge.
* **Fill auditing.** Compare your fill prices with the recorded timeline.
* **Backtesting.** Replay the timeline against your strategy.

## Reference

The market data endpoints are in the **API → Reference** sidebar, under **Reference data**, **Fixtures** and **Odds**. Their parameters and response schemas come from the OddsPapi v5 reference, limited to what Apexium forwards. For background on the data itself, see the [OddsPapi documentation](https://docs.oddspapi.io).

## Glossary

* **sportId**: numeric sport identifier; the first two digits of `marketId`, `outcomeId` and `fixtureId`.
* **fixtureId**: string key of a match, encoding sport, tournament and a native ID.
* **marketType**: the kind of market (`1x2`, `totals`, `spreads`, …).
* **period**: the segment a market applies to (`fulltime`, `p1`, `p2`).
* **handicap**: the line value of a market; each line value is its own `marketId`.
* **marketId**: integer grouping the outcomes of one market; equals its first `outcomeId`.
* **marketLength**: the number of outcomes under a `marketId`.
* **outcomeId**: integer identifying one selection: market type, period, line and side.
* **playerId**: ties an outcome to a player; `0` is a market not about a player.
* **participantId**: integer identifying a team or competitor.
* **oddsId**: price key, `{fixtureId}:{bookmaker}:{outcomeId}:{playerId}`.
* **OLV / CLV**: opening and closing line value, the first and last recorded prices of an outcome.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.