How do I build an MLB spray chart in Python?
Where a hitter puts the ball in play, by trajectory and field, plus the x and y of every ball in play if you want to draw it.
Code verified October 10, 2026. One call to get_spray_chart, 10 credits.
The call
batter_id comes from search_players. Leave include_balls out for the totals alone.
import requests
import pandas as pd
API_KEY = "YOUR_API_KEY"
resp = requests.post(
"https://mcp.fastballapi.com/v1/get_spray_chart",
headers={"x-api-key": API_KEY},
json={
"batter_id": "33192",
"season": 2026,
"include_balls": True,
},
timeout=60,
)
resp.raise_for_status()
data = resp.json()["data"]
balls = pd.DataFrame(data["balls"])
print(pd.DataFrame(data["by_field"]))
print(balls.groupby("trajectory")["result"].value_counts().head(10))
# x and y are pixels on a 250 x 250 field image, home plate near (125, 205).
print(balls[["x", "y"]].describe().round(1))
Replace YOUR_API_KEY with a key from your dashboard. Python needs requests and pandas (pip install requests pandas). JavaScript runs on Node 18 or newer, or in the browser.
What comes back
The data object of the response, trimmed to the first rows. Every field is real output from the run above.
{
"season": 2026,
"balls_in_play": 153,
"by_trajectory": [
{
"trajectory": "G",
"balls": 58,
"hits": 12,
"hr": 0,
"hit_rate": 0.207
},
{
"trajectory": "F",
"balls": 50,
"hits": 21,
"hr": 17,
"hit_rate": 0.42
},
"...2 more"
],
"by_field": [
{
"field": "left",
"balls": 66,
"hits": 32,
"hr": 11,
"hit_rate": 0.485
},
{
"field": "right",
"balls": 47,
"hits": 16,
"hr": 6,
"hit_rate": 0.34
},
"...1 more"
],
"balls": [
{
"x": 97,
"y": 151,
"trajectory": "G",
"result": "ground-out"
},
{
"x": 191,
"y": 76,
"trajectory": "F",
"result": "fly-out"
},
"...151 more"
]
}What to do next
- get_plate_appearances (10 credits). Filter a hitter's at-bats by result, inning or runners in scoring position.
- get_player (5 credits). Season batting and pitching lines for the same player.
More guides
Start with 500 free credits
No card. REST or MCP.