Skip to main content
This page explains the core concepts used throughout the Odds API: how IDs are constructed, how entities relate to each other, how timestamps are used, and how to design reliable client-side storage.

​
Language prefix

All endpoints are prefixed with a language code:
  • /en/...
  • /de/...
  • /fr/...
Translated fields (for example names) follow the prefix language when available. Identifiers (sportId, fixtureId, etc.) are language-independent.

​
Sports, tournaments, seasons

​
sportId

  • Integer.
  • The first two digits embedded into several downstream IDs.
  • Discover via /sports.

​
tournamentId

  • Integer.
  • Belongs to exactly one sport.
  • Discover via /tournaments.

​
seasonId

  • Integer.
  • Belongs to exactly one tournament.
  • Discover via /seasons.

​
Markets and outcomes

​
Relationship between marketId and outcomeId

Markets and outcomes are tightly coupled by design:
  • A market represents a complete betting market (for example moneyline, 1x2, totals).
  • A market contains multiple outcomes.
  • All outcomes that belong to the same market share the same marketId.
  • The first outcomeId of a market is always equal to the marketId.
This makes it possible to determine which outcomes belong to which market without additional metadata.

​
ID structure

Both marketId and outcomeId are integers constructed as: 
{sportId (2 digits)} + {incrementing number}
Examples:
  • 11xxxx → basketball market or outcome
  • 14xxxx → American football market or outcome
This design provides:
  • Unlimited markets and outcomes per sport
  • Fast grouping by sport
  • Immediate visibility of market relationships

​
Why marketId matters (arbitrage & modeling)

All outcomes under a single marketId together represent a complete probability space. This makes marketId especially useful for:
  • Arbitrage detection
  • Overround / margin calculations
  • Probability normalization
  • Market completeness checks
Recommendation: If you perform arbitrage or pricing logic, always group odds by marketId.

​
Participants and players

​
participantId

  • Integer.
  • Represents teams or competitors in fixtures.
  • Discover via /participants.

​
playerId

  • Integer.
  • Used for player proposition markets.
  • playerId = 0 typically represents a non-player market.
  • Discover via /players.

​
Fixture IDs

​
fixtureId structure

fixtureId is a string that encodes multiple pieces of information: 
{providerSlug}{sportId}{tournamentId}{providerFixtureId}
Conceptual example: 
id1100013262926199
Where:
  • id → provider identifier / short slug
  • 11 → sportId (2 digits)
  • 000132 → tournamentId (6 digits)
  • 62926199 → provider’s native fixture ID

​
Why this matters

From the fixtureId alone, you can infer:
  • The sport
  • The tournament
  • The upstream provider
  • Global uniqueness
This makes logging, debugging, analytics, and cross-system correlation simpler and more reliable.

​
Future IDs

​
futureId structure

futureId follows a similar principle: 
{providerSlug}{sportId}{seasonId}{marketId}
This encodes:
  • Provider
  • Sport
  • Season
  • Market
Like fixtureId, this makes futures:
  • Globally unique
  • Self-describing
  • Easy to debug and trace

​
Odds identifiers

​
Fixture odds keys

For fixtures, a single price is uniquely identified by: 
{fixtureId}:{bookmaker}:{outcomeId}:{playerId}
Example: 
id1400003160574217:bet365:141:0
This combination uniquely defines one price.

​
Future odds IDs

For futures, odds are uniquely identified by: 
{futureId}:{bookmaker}:{outcomeId}:{participantId}:{playerId}
This fully specifies:
  • The future
  • The bookmaker
  • The outcome
  • The participant (when applicable)
  • The player (for props)

​
Storage recommendation (important)

We strongly recommend using these identifiers as primary keys in your storage: Fixture odds: 
{fixtureId}:{bookmaker}:{outcomeId}:{playerId}
Future odds: 
{futureId}:{bookmaker}:{outcomeId}:{participantId}:{playerId}
This guarantees:
  • No duplicates
  • Simple updates
  • Efficient time-series storage
  • Easy reconciliation across snapshots and backfills

​
Timestamps (seconds vs milliseconds)

This API intentionally uses both epoch seconds and epoch milliseconds, depending on context.

​
Epoch seconds (UTC)

Used for scheduled or coarse-grained time values:
  • startTime
  • startTimeFrom
  • startTimeTo

​
Epoch milliseconds (UTC)

Used for high-frequency price updates:
  • changedAt
  • Odds since filters for fixtures
  • Futures odds createdAt

​
Recommendation

  • Store timestamps as integers.
  • Do not assume milliseconds where seconds are documented (or vice versa).
  • Normalize internally only if needed.

​
Implementation recommendations

​
Server Location Matters

To achieve the lowest latency for realtime updates:
  • The fastest delivery regions are Central Europe (recommended) and US East.
  • For best performance, deploy your backend in the same datacenters we use, such as:
  • If you’re building prediction markets or models sensitive to latency, consider:
    • Deploying in Austria (AT) via Netcup, or
    • Using AWS eu-west-1 (Ireland)
⚡ Servers colocated near our streaming infrastructure receive updates faster and with fewer hops.

​
Snapshot + realtime pattern

A reliable integration pattern:
  1. Fetch HTTP snapshot (fixtures, odds, or futures)
  2. Subscribe to WebSocket for realtime updates
  3. If WebSocket signals snapshot_required:
    • Re-fetch HTTP snapshot
    • Resume realtime stream

​
Efficient backfills

  • Use since parameters where available
  • Avoid full historical fetches unless required
  • Store odds keyed by their odds identifiers for deduplication

​
Rate limit handling

  • Read X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset
  • On HTTP 429, respect Retry-After and back off

​
Summary

This API is designed so that:
  • IDs are self-describing
  • Relationships are derivable without joins
  • Odds identifiers are globally unique
  • Arbitrage and storage logic are straightforward and robust
Modeling your system around these principles will result in a fast, maintainable, and future-proof integration.