Core concepts
Game ids
Section titled “Game ids”Game ids are readable: LEAGUE_AWAY_HOME_YYYYMMDD, e.g.
NBA_ORL_DET_20260503.
- The date is the US Eastern calendar date of the scheduled start.
- A
_2suffix marks the second game of a doubleheader. - Ids are case-insensitive.
- Discover ids via the games reference
endpoint (filter by league, ET date range, team, status) or
betflux games. The same record carries the schedule, teams, score, venue, and weather.
Market identity
Section titled “Market identity”Within a (game, operator), a market is identified by the operator’s own
market id — market_external_id on every lines dataset. Every lines dataset
also carries market_key = OPERATOR:market_external_id (e.g.
FANDUEL:123456), a globally unique market identity and the join key across
closing-lines, market-results, and sportsbook-lines. market_type and
period describe what kind of market it is, not which market: a book
can offer several markets with the same type and period (a main spread and
its alternate-lines market, one “1+ hits” market per player), and
market_name is the operator’s label for telling them apart.
Within a market, a selection is identified by selection_external_id,
the operator’s own selection id. selection_name (e.g. a player for prop
markets, Over; null for plain team markets) is display text shared across
selections, never an identity. A selection carries one or more priced
sides (side: HOME, AWAY, OVER, UNDER, …). closing-lines has one row per
selection per side; market-results one row per selection.
What a selection id means differs by book, and that shapes how a moving line shows up:
| Book | Selection id | A line move looks like |
|---|---|---|
| FanDuel (main markets) | stable; the line moves on the same id | one row, opening_total 212.5 → closing_total 224.5 |
| FanDuel (alternate lines), BetMGM, Pinnacle | one id per line value; the name embeds the line (Over 10, Baltimore Orioles +1.5) |
one row per line value, opening_* == closing_* |
| DraftKings | one id per line value; the name is bare (Over, BAL Orioles) |
one row per line value within the market; a new id appears when the line moves |
Timestamps and dates
Section titled “Timestamps and dates”Timestamp columns are real Parquet timestamps (UTC) — pyarrow and DuckDB
decode them as native datetime values, and the CLI renders them as ISO 8601.
game_date is a Parquet date: the ET calendar date of the start — use it for
“games on April 1” semantics; use game_start for exact times.
Historical data availability
Section titled “Historical data availability”Beta access includes all available historical data. See coverage for the first retained game dates by league and operator. Each requested dataset artifact must exist.