Are batting and pitching fields fixed?

No. The response is a populated field map, so clients must inspect the returned keys.

Can I use player names as ids?

No. Resolve and retain the canonical player id; same-name records are not safe joins.

Are headshots guaranteed?

No. Use the served first-party URL when present and an honest initials fallback when absent.

Tutorial · 11 min · endpoints verified 2026-09-20

How to build a fantasy baseball app

Resolve one player identity, separate batting from pitching, and score only the fields the API actually serves.

API coverage and endpoint overview: Explore the MLB API

Why this is hard

Fantasy scoring starts with identity and role

A player can have batting and pitching fields, and the populated key set varies by row.

Find the canonical player id first.
Do not treat a missing stat as zero.
Keep batting and pitching formulas separate.
Use game logs for recency rather than rewriting season totals.

Path 1 · recommended

Have your AI agent build it

MCP can find players and fetch their aggregate stats.

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

find_players
Find canonical player IDs by name for use with player-stat tools.
get_player_stats
Per-player career or per-season totals and per-game rates.
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 fantasy baseball board. Find each canonical MLB player, fetch baseball player stats, separate hitters and pitchers by served fields, and show unavailable for missing values.

What the agent cannot reach

MCP does not expose game-log or rolling-stat routes. Use REST for recency and do not join ambiguous names.

Path 2 · hand-coded

Build it yourself

Resolve identity once, then retain that id through every player view.

01
Find the player
Search the player catalogue and require a canonical id before enabling detail.
Player lookupbash
```
curl -s "https://api.bigballsdata.com/v1/players?sport=baseball&name=judge" \
  -H "x-api-key: $BBS_API_KEY"
```

Read season stats

The response is a field map; inspect keys before applying a scoring rule.

Player statsbash

curl -s "https://api.bigballsdata.com/v1/players/$PLAYER_ID/stats?sport=baseball" \
  -H "x-api-key: $BBS_API_KEY"

Add recent form

Use the game log or rolling windows to show recency separately from season production.

Rolling statsbash

curl -s "https://api.bigballsdata.com/v1/players/$PLAYER_ID/rolling-stats?sport=baseball" \
  -H "x-api-key: $BBS_API_KEY"

Reference

Every endpoint this tutorial uses

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

Method	Path	Returns	Why you need it	Plan
GET	/v1/players?sport=baseball&name=	Canonical player candidates	Prevents a display-name join from becoming product identity.	Free
GET	/v1/players/:id/stats?sport=baseball	Available batting and pitching season fields	Supplies the season scoring inputs.	Free
GET	/v1/players/:id/game-log?sport=baseball	Per-game player lines	Supports trend charts without reinterpreting aggregates.	Free
GET	/v1/players/:id/rolling-stats?sport=baseball	Rolling player windows	Adds recent form for a production fantasy tool.	Solo

Pricing, honestly

Free proves the scoring model

Free supplies identity and core player statistics. Solo adds production depth such as rolling form and player media where stored.

Free key

jsonjson

Player lookup, season stats and game logs.

Solo

jsonjson

Rolling form, media, and the five-season Solo product entitlement.

Keep the formula visible.
Score only populated fields.
Use an initials fallback for absent headshots.

See the full plan ladder →

Other build guides

Known gaps

Fantasy boundaries

A useful board does not hide missing context.

Injury reports remain coming soon in the coverage manifest.
Not every historical game has per-player lines.
Pitch-level data is not a public endpoint yet.

Questions

Are batting and pitching fields fixed?: No. The response is a populated field map, so clients must inspect the returned keys.
Can I use player names as ids?: No. Resolve and retain the canonical player id; same-name records are not safe joins.
Are headshots guaranteed?: No. Use the served first-party URL when present and an honest initials fallback when absent.

Related APIs

Other APIs you can build with:

MLB API Baseball API

Stats reference

MLB Batting Stats API

Build the first player board

Start with canonical ids and a scoring rule your users can inspect.