get_spray_chart
10 creditsMulti-tablePOST /v1/get_spray_chart
Data refreshed · changelog
Where a batter or team hits the ball, by trajectory and field
Use it when you want where a hitter or team puts the ball in play, by field and trajectory, or every ball's location to draw a chart.
Parameters
batter_idstringoptionalteamstringoptionalseasonnumber | stringoptional- Season (a year; default: the latest; ignored with game_id).
include_ballsbooleanoptional- Add each ball in play's x/y (up to 3,000).
season_typeenum: regular | postseason | alloptional- regular, postseason, or all (default): which games' balls in play to count.
Notes
- Over MCP, ask for it in plain English and the client calls
get_spray_chartitself. Point any MCP client athttps://mcp.fastballapi.com/mcp?key=YOUR_API_KEY. - Each call costs 10 credits, taken before it runs and refunded if the server errors.
- Not the call you need? Find the right call by what you are trying to answer.
Request
curl -X POST https://mcp.fastballapi.com/v1/get_spray_chart \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"batter_id": "30951",
"season": 2025
}'Response
json
{
"season": 2025,
"balls_in_play": 395,
"by_trajectory": [
{
"trajectory": "G",
"balls": 171,
"hits": 40,
"hr": 0,
"hit_rate": 0.234
},
{
"trajectory": "F",
"balls": 111,
"hits": 34,
"hr": 25,
"hit_rate": 0.306
},
{
"trajectory": "L",
"balls": 101,
"hits": 58,
"hr": 2,
"hit_rate": 0.574
}
],
"by_field": [
{
"field": "right",
"balls": 179,
"hits": 69,
"hr": 17,
"hit_rate": 0.385
},
{
"field": "left",
"balls": 118,
"hits": 41,
"hr": 6,
"hit_rate": 0.347
},
{
"field": "center",
"balls": 98,
"hits": 24,
"hr": 4,
"hit_rate": 0.245
}
]
}Response fields
seasonnumberballs_in_playnumberby_trajectory[]array- List of objects
by_trajectory[].trajectorystringby_trajectory[].ballsnumberby_trajectory[].hitsnumberby_trajectory[].hrnumberby_trajectory[].hit_ratenumberby_field[]array- List of objects
by_field[].fieldstringby_field[].ballsnumberby_field[].hitsnumberby_field[].hrnumberby_field[].hit_ratenumber
Used in
- MLB spray chart data: Where every ball in play went, with its trajectory (ground ball, line drive, fly ball, pop-up) and result, for any batter or team. REST or MCP.
- Guide: How do I build an MLB spray chart in Python?
Related endpoints
list_teams1 cr
Returns the team this one takes.
Team ids, abbreviations and colours for a season
get_games2 cr
Returns the team this one takes.
Games with runs, hits and errors by season, date, range or team
get_injuries2 cr
Filters by the same team.
The latest injury report
get_player_games5 cr
Filters by the same season and season_type.
A player's full batting and pitching game log
Try it
500 free credits every month: 50 calls to get_spray_chart, and no card.