Skip to content

Livematches in play

Demo: Matchboard, opens in a new tab

History · REST · Season exports

Historical sports data API, a whole season at a time

DataSportsAPI is a historical sports data API as well as a live one: finished seasons stay readable through the same REST endpoints as today's matches, with their results, lineups, events, statistics and standings. On Enterprise the oldest seasons reach back to 1920, and from Business up you can also export a whole league season as JSON, CSV or Parquet in one request.

  • Same endpoints as live data
  • Back to 1920 on Enterprise
  • JSON · CSV · Parquet
  • Stable ids across seasons
Football
Cricket
Baseball
Seasons of results, one id per team

Depth

How far back each plan reads

History is one of three limits on every plan, next to the request quota and the per-minute rate. The window is measured back from the start of today in UTC, and it only ever applies to the past: fixtures still to come and matches in play are open on every plan.

Inside the window, a finished match is as complete as a live one: the final score by period, the events, both lineups with player statistics, team statistics and the referee. Tables, rounds and season leaders stay readable season by season, and because our team, player and league ids never change, a join across ten seasons is a join on one id.

History window, counted back from 00:00 UTC today
  • Free7 days
  • Starter30 days
  • Pro6 months
  • Business12 months
  • EnterpriseFull history
← further backtoday · upcoming and live always open →

Season exports

A whole season in three steps

When you need everything a league did in a season, hundreds of paged calls are the slow way. An export packs the season into files on our side: start it, poll it, download it.

A season we have built before comes back in seconds; one built from scratch takes a few minutes. The download links are signed, so they need no key, and they last an hour. Read the export again for fresh links.

# 1. Start an export of one league season (Business and up)
curl -X POST "https://api.datasportsapi.com/v2/exports" \
  -H "Authorization: Bearer $DATASPORTSAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "league": 17, "season": 61627, "format": "parquet" }'

# 2. Ask again every few seconds until status is "ready"
curl "https://api.datasportsapi.com/v2/exports/42" \
  -H "Authorization: Bearer $DATASPORTSAPI_API_KEY"

# 3. Each files[].url is a signed link: no key needed, valid for an hour
curl -o fixtures.parquet "https://…"
GET /v2/exports/42 · ready
{
  "data": {
    "id": 42, "league": 17, "season": 61627, "format": "parquet",
    "status": "ready", "error": null, "fixtureCount": 380,
    "createdAt": "2026-11-01T18:00:00.000Z",
    "finishedAt": "2026-11-01T18:00:41.000Z",
    "files": [
      { "name": "fixtures.parquet", "bytes": 21944,
        "contentType": "application/vnd.apache.parquet", "url": "https://…" },
      { "name": "standings.parquet", "bytes": 3120,
        "contentType": "application/vnd.apache.parquet", "url": "https://…" }
    ],
    "linksExpireAt": "2026-11-01T19:01:02.000Z"
  }
}

Formats

JSON, CSV or Parquet

The files are built from the same data the endpoints serve, so nothing is renamed or reshaped behind your back.

  • json

    Business and up

    season.json

    One document with the league, the season, its rounds, every fixture, the standings, top players and top teams, each shaped exactly as its endpoint returns it.

    Best for: Reuse the parsers you already wrote for REST.

  • csv

    Business and up

    fixtures.csv · standings.csv

    Two flat tables: one row per fixture, one row per table position.

    Best for: Spreadsheets and quick imports.

  • parquet

    Business and up

    fixtures.parquet · standings.parquet

    The same two tables, typed and compressed in a columnar format.

    Best for: pandas, Polars, DuckDB, Spark and warehouses.

Fixtures table columns

  • fixture_id
  • sport
  • start_time
  • round
  • round_name
  • status
  • status_description
  • home_team_id
  • home_team
  • away_team_id
  • away_team
  • home_score
  • away_score
  • winner
  • venue

Standings table columns

  • table
  • primary
  • position
  • team_id
  • team
  • played
  • wins
  • draws
  • losses
  • scores_for
  • scores_against
  • points
  • zone
Exports per day
20Per account, per UTC day. The 21st start answers 429 export_limit; the count resets at 00:00 UTC.
Kept for
7 daysThen the export and its files are gone, so store what you need.
Download links
1 hourSigned and key-free. Read the export again for new ones.
Scope
One league seasonA league id plus one of its season ids. For several seasons, start several exports.
Build time
Seconds to minutesSeconds for a season already cached, a few minutes for one built from scratch.
Your recent exports
Last 20GET /v2/exports lists them, newest first, with fresh links on the ready ones.

Choosing

REST or a season export?

TopicREST endpointsSeason export
PlansEvery plan, inside its history windowBusiness and up, inside the same window
UnitOne record or one list per callOne league season per export
FormatJSON, shaped like today's dataJSON, CSV or Parquet files
RequestsOne per call, per pageOne to start, a few to poll
DetailEverything: events, lineups, player statisticsFixtures, tables, rounds and season leaders
Best forMatch pages, head-to-head, back-filling an appWarehouses, notebooks, model training, archives

Worth knowing before you load ten seasons

  1. Seasons are the unit

    Take season ids from a league's seasons list. year is the label to show; startYear and endYear are the numbers to sort and filter on.

  2. Some seasons have no rounds

    The NBA and NHL regular seasons are not split into rounds at the source, so their exports carry no fixtures. The export's error field says what was left out.

  3. Replays can appear twice

    A match postponed and replayed later can show up as two fixtures, each with its own id. Filter on status when you count games.

  4. Ids hold across seasons

    Teams, players and leagues keep the same id year after year, so you can join a decade of results without fuzzy name matching.

  5. Some home and away tables are computed

    Where the NBA, NHL and NFL publish none, we build them from the finished regular-season fixtures and say so in meta.source.

  6. Champions go back ten seasons

    The champions list covers the last ten seasons the source records. For older winners, read each season's final table.

Plans

History on every plan, full depth on Enterprise

Every plan reads the past through the same endpoints; the plan decides how far back. Season exports start on Business, for seasons within the last 12 months, and the whole archive comes with Enterprise.

  1. Free

    Included

    $0 a month

    • 1,000 requests / day
    • 10 requests a minute
    • Last 7 days of history

    Last 7 days: the past week's results, events and lineups, enough to try the shape of past data.

    Free plan details
  2. Starter

    Included

    $49 a month

    • 250,000 requests / month
    • 120 requests a minute
    • Last 30 days of history

    Last 30 days: a month of form and results for a product that is already live.

    Starter plan details
  3. Pro

    Included

    $199 a month

    • 1,000,000 requests / month
    • 600 requests a minute
    • Last 6 months of history

    Last 6 months: most of a season, with the premium analytics on past matches too.

    Pro plan details
  4. Business

    Included

    $1,500 a month

    • 5,000,000 requests / month
    • 3,000 requests a minute
    • Last 12 months of history

    Last 12 months: a full year of matches, plus season exports as JSON, CSV and Parquet for the seasons inside it.

    Business plan details
  5. Enterprise

    Included

    $2,500 a month

    • 10,000,000 requests / month
    • 6,000 requests a minute
    • Full history

    The whole archive, back to 1920 in the oldest competitions, with exports of any season and the tracking data.

    Enterprise plan details

Questions

Historical sports data, answered

The season exports guide has the export object field by field.

How far back does the historical data go?

It depends on the plan. Enterprise reads the whole archive: across the headline competitions of each sport the median reach is 16 years, and the oldest season goes back to 1920. Business reads the last 12 months, Pro the last 6 months, Starter the last 30 days and Free the last 7 days, each counted back from 00:00 UTC today. In old seasons, results and tables tend to start earlier than lineups and statistics do. Matches still to come and matches in play are open on every plan.

Can I download a whole season as CSV or Parquet?

Yes, on Business and Enterprise. POST /v2/exports with a league id, a season id and a format (json, csv or parquet) builds the files in the background; poll /v2/exports/{id} until it is ready and download each file from its signed link. Business exports the seasons within the last 12 months, and an older one answers 403 history_not_in_plan; Enterprise exports any season. You can start 20 exports per UTC day, and each one is kept for 7 days.

Which sports have historical data?

All 24. Fixture sports keep their seasons, rounds, fixtures, events, lineups and tables; motorsport and cycling keep series seasons, races, results and standings. Season exports work on leagues, so they cover the fixture sports.

What happens if I ask for data older than my plan allows?

A single record from before your window, such as an old fixture, a past day's list or a finished season's table, answers 403 history_not_in_plan with historyFrom, the earliest date open to you. A list that reaches back, such as a team's fixtures, is trimmed instead and reports the cut-off in meta.historyFrom. Both count as requests.

Are betting odds part of the history or the exports?

No. Exports hold match data only: fixtures, tables, rounds, top players and top teams. Odds stay on their own endpoints, as they do everywhere else in the API.

Which format suits machine learning?

Parquet, in most cases. It is typed and compressed, loads straight into pandas, Polars, DuckDB or Spark, and the fixtures and standings tables join on team_id. Choose JSON when you need the nested detail exactly as the endpoints return it.

Ten seasons, one id per team.

Try the shape of past data on the free plan; exports start on Business, and the whole archive is on Enterprise.