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
BaseballDepth
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.
- Free7 days
- Starter30 days
- Pro6 months
- Business12 months
- EnterpriseFull history
Where the history lives
The same calls you use for this weekend work for any season inside your window. Walk a league from its seasons to its rounds to each match, or start from a team or a player.
- GET
/v2/leagues/{id}/seasonsSeasonsEvery season of a league, newest first: the ids the other calls take.All plans - GET
/v2/leagues/{id}/standingsStandingsA past season's tables, with home and away tables where they exist.All plans - GET
/v2/leagues/{id}/roundsRoundsThe rounds of a season, to walk it in order.All plans - GET
/v2/leagues/{id}/fixturesLeague fixturesEvery fixture of one round, with final scores.All plans - GET
/v2/fixtures/{id}FixtureOne finished match in full: venue, referee, managers, aggregate.All plans - GET
/v2/fixtures/{id}/eventsEventsThe goals, cards and substitutions of a past match.All plans - GET
/v2/fixtures/{id}/h2h/fixturesHead-to-head fixturesPast meetings of two teams, trimmed to your plan's window.All plans - GET
/v2/players/{id}/careerCareerA player's season-by-season table at club and international level.All plans - GET
/v2/leagues/{id}/championsChampionsRecent title winners: the last ten seasons the source records.All plans - POST
/v2/exportsCreate an exportA whole league season as files, built in the background.Business and up
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://…"{
"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 upseason.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 upfixtures.csv · standings.csv
Two flat tables: one row per fixture, one row per table position.
Best for: Spreadsheets and quick imports.
parquet
Business and upfixtures.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?
| Topic | REST endpoints | Season export |
|---|---|---|
| Plans | Every plan, inside its history window | Business and up, inside the same window |
| Unit | One record or one list per call | One league season per export |
| Format | JSON, shaped like today's data | JSON, CSV or Parquet files |
| Requests | One per call, per page | One to start, a few to poll |
| Detail | Everything: events, lineups, player statistics | Fixtures, tables, rounds and season leaders |
| Best for | Match pages, head-to-head, back-filling an app | Warehouses, notebooks, model training, archives |
Worth knowing before you load ten seasons
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.
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.
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.
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.
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.
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.
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 detailsStarter
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 detailsPro
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 detailsBusiness
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 detailsEnterprise
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.
Keep reading
More of the sports data API
Other ways in
- Live scores APIEvery match in play in one call, with score, status and clock current to the second.Read more
- Real-time sports APIA WebSocket with snapshots, deltas and replay, plus signed webhooks, from the Business plan up.Read more
- Free sports APIThe core match data for all 24 sports on the Free plan, with no card to sign up.Read more
- Betting odds APIPre-match and in-play prices per fixture from Pro, a day of markets in one call, live moves from Business.Read more
- Sports statistics APIMatch stats by period, player and team season totals, xG, ratings and league leaderboards.Read more
Sport by sport
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.







