Can I replace missing NCAAB fields with NBA data?

No. The schemas may be related, but the identities, competitions, and capability depth are not interchangeable.

What should the UI do with an empty response?

Check the status and error envelope, then show a dated empty state. Never turn a failed read into a factual zero.

Where do the plan labels come from?

The route floors come from the endpoint-plan registry used by the product and its checks. A sport-specific floor can override the shared route floor.

Tutorial · 8 min · endpoints verified 2026-09-22

How to build a March Madness archive

Browse the served NCAA Tournament bracket with real seeds, rounds and final scores. This guide uses only the routes currently supported for NCAAB; it never fills a gap with NBA data.

API coverage and endpoint overview: Explore the NCAAB API

Why this is hard

The data contract behind a March Madness archive

The bracket is its own product surface. It does not live in the NCAAB match collection, whose round field is null on every row, so a tournament archive must read the dedicated bracket route instead of filtering the regular-season schedule by date.

Request the bracket from /v1/ncaab/tournament, not from the NCAAB match collection.
A season label is the year the season BEGAN: season=2025 is the bracket played in March and April 2026.
region_label is null on every served row, so ?region= matches nothing; select a stage with ?round= instead.
NCAAB odds and bracket projections are not served, so neither belongs in this archive.
Preserve canonical match and team IDs instead of joining on display names.
Show source timestamps and a useful empty state when a query returns no rows.

Path 1 · recommended

Have your AI agent build it

Use MCP for discovery, then make the workflow-specific REST request when the MCP tool set does not expose that enrichment.

1. Connect the MCP server

Add the server in your MCP client and sign in with your Big Balls account. Your client registers itself and handles the token exchange — there is no key to copy.

MCP client configjson

{
  "mcpServers": {
    "bigballs-sports-data": {
      "url": "https://mcp.bigballsdata.com/mcp"
    }
  }
}

2. Tools your agent gets

get_matches
Live, upcoming or historical matches for a sport or league.
get_coverage
Machine-readable map of what we hold and what we do not.

3. Ask for what you want

Paste this at your agent. It is written to make the model check coverage before it designs anything, which is what stops it inventing a field we do not serve.

Prompttext

Build a March Madness archive. Start with get_coverage for basketball, then get_matches with league=ncaab. Preserve canonical IDs and timestamps. Use only NCAAB capabilities documented by Big Balls Sports Data. If a field is unavailable, show that state and do not substitute an NBA value.

What the agent cannot reach

The MCP server does not expose every REST route used below. It also cannot make an unsupported NCAAB field appear, so keep the REST capability boundary visible in the final interface.

Path 2 · hand-coded

Build it yourself

The sequence below starts from a league-filtered collection, follows a returned ID, and shapes only fields the response actually carries.

01
List the NCAAB population
Begin with an explicit sport and league filter. Check HTTP status before interpreting an empty data array.
League-scoped requestbash
```
curl -s "https://api.bigballsdata.com/v1/ncaab/tournament?season=2025" \
+  -H "x-api-key: $BBS_API_KEY"
```
02
Follow the canonical identifier
Keep the canonical IDs from every list row; they are the stable links to later detail and team-history calls.
Inspect the collectionbash
```
curl -s "https://api.bigballsdata.com/v1/ncaab/tournament?season=2025" \
+  -H "x-api-key: $BBS_API_KEY" | jq '.data[0]'
```

Create the product view model

Transform the served fields without inferring unavailable metrics. The example keeps null and empty states explicit.

Honest view modeltypescript

const bracket = games.map((game) => ({
  gender: game.gender, round: game.round, tipoff: game.scheduled_at,
  home: { team: game.home_team.full_name, seed: game.home_team.seed, score: game.home_team.score },
  away: { team: game.away_team.full_name, seed: game.away_team.seed, score: game.away_team.score },
}));

Reference

Every endpoint this tutorial uses

All on the gateway at api.bigballsdata.com. Verified against production on 2026-09-22.

Method	Path	Returns	Why you need it	Plan
GET	/v1/ncaab/tournament?season=2025	The played bracket: men's and women's games with seeds, rounds and final scores	This is the only route that carries tournament round and seed context.	Free
GET	/v1/matches?sport=basketball&league=ncaab	League-scoped games, teams, status and scores	Defines the exact game population and supplies canonical identifiers.	Free

Pricing, honestly

The bracket route starts on Free

The whole served bracket is Free, and ?limit= defaults to 200 so one request returns it. A paid plan does not add rounds, regions or projections that the feed does not carry.

Free key

jsonjson

Every served bracket game with seed, round and final score.

Solo

jsonjson

Higher volume on the surrounding regular-season collection.

Cache completed games instead of polling immutable rows.
Treat plan_required as a product boundary, not a retryable outage.
Keep the NCAAB capability set separate from NBA.

See the full plan ladder →

Other build guides

Known gaps

What this workflow deliberately leaves out

A useful first version is narrower than a misleading one. Add another panel only when its league-specific route and fields are verified.

Request the bracket from /v1/ncaab/tournament, not from the NCAAB match collection.
A season label is the year the season BEGAN: season=2025 is the bracket played in March and April 2026.
region_label is null on every served row, so ?region= matches nothing; select a stage with ?round= instead.
NCAAB odds and bracket projections are not served, so neither belongs in this archive.

Questions

Can I replace missing NCAAB fields with NBA data?: No. The schemas may be related, but the identities, competitions, and capability depth are not interchangeable.
What should the UI do with an empty response?: Check the status and error envelope, then show a dated empty state. Never turn a failed read into a factual zero.
Where do the plan labels come from?: The route floors come from the endpoint-plan registry used by the product and its checks. A sport-specific floor can override the shared route floor.

Related APIs

Other APIs you can build with:

NCAA Basketball API Basketball API — Every League, One Schema NBA API — Live Scores, Box Scores & Props WNBA API

Also on this sport

NBA Player Props API Injury Data API for Developers: Free

Stats reference

NBA Player Stats API NBA Player Props API

Ship a March Madness archive

Start with the supported NCAAB workflow, preserve its evidence, and add depth only when the league really serves it.

Datasets

Tools

Tutorials

Compare

Product