API Playground - MLB.TheOhtani.com

Overview

The API Playground is an interactive tool for exploring MLB’s Stats API. Test endpoints, view responses, and understand the data structure without writing code.

The API Playground is currently under development. This documentation describes planned features based on the application’s route structure.

Getting Started

Access the API Playground from the main navigation:

Select API Version

Choose which version of the MLB Stats API you want to explore (v1, v1.1, etc.).

Browse Endpoints

Navigate through available API endpoints organized by category.

Test Requests

Make live API calls and see real responses from MLB’s servers.

Explore Data

Examine the JSON response structure and available fields.

API Versions

MLB provides multiple API versions:

v1.1 (Recommended)
v1.0

Latest stable version with:

Enhanced field filtering
Improved performance
Extended data coverage
Better documentation

Endpoint Categories

API endpoints are organized by data type:

Schedule Endpoints

/api/v1/schedule

Get games by date range, team, or season.

/api/v1.1/schedule

Enhanced scheduling with flexible date parameters.

Game Endpoints

/api/v1.1/game/{gamePk}/feed/live

Live game data with play-by-play.

/api/v1/game/{gamePk}/boxscore

Detailed box score statistics.

/api/v1/game/{gamePk}/linescore

Inning-by-inning scoring summary.

/api/v1/game/{gamePk}/winProbability

Play-by-play win probability data.

Player Endpoints

/api/v1/people/{personId}

Individual player information and stats.

/api/v1/people/search

Search for players by name.

Team Endpoints

/api/v1/teams

List of all MLB teams.

/api/v1/teams/{teamId}/roster

Current team roster.

Standings Endpoints

/api/v1/standings

League and division standings with customizable parameters.

Query Parameters

Most endpoints accept parameters to filter and customize responses:

Common Parameters

sportId

Filter by sport:

1 = MLB (default)
Other values for minor leagues

season

Specify season year:

2024, 2023, etc.
Defaults to current season

gameType

Filter by game type:

R = Regular Season
S = Spring Training
F = Wild Card
D = Division Series
L = League Championship
W = World Series

hydrate

Include additional data:

hydrate=team - Include team details
hydrate=linescore - Add linescore
hydrate=decisions - Include pitching decisions
Multiple values comma-separated

fields

Select specific response fields:

Reduces payload size
Improves performance
Comma-separated list
Example: fields=teams,away,home,name,id

Making Requests

The playground interface provides:

Request Builder

Select Endpoint

Choose from the categorized list of available endpoints.

Add Parameters

Fill in required path parameters (like gamePk or personId).

Configure Options

Set optional query parameters and hydration options.

Execute Request

Click “Send Request” to make the API call.

Response Viewer

After executing a request:

JSON Response: Formatted and syntax-highlighted
Status Code: HTTP response code (200, 404, etc.)
Response Time: How long the request took
Headers: Response headers from the API
Copy Button: Copy JSON to clipboard
Download: Save response as a file

Use the fields parameter to request only the data you need, reducing response size and improving load times.

Example Use Cases

Get Today’s Games

GET /api/v1/schedule?date=2024-07-15

Returns all games scheduled for July 15, 2024.

Live Game Data

GET /api/v1.1/game/717159/feed/live?fields=gameData,liveData,plays,currentPlay

Fetches live data for game #717159 with only play information.

Player Stats

GET /api/v1/people/660271?hydrate=stats(group=hitting,type=season)

Gets Shohei Ohtani’s hitting stats for the current season.

Team Standings

GET /api/v1/standings?leagueId=103&season=2024&standingsTypes=regularSeason

Returns American League standings for 2024.

Field Filtering

Reduce response size by requesting specific fields:

{
  "gameData": { ... }, // Entire game object
  "liveData": { ... },  // All live data
  "metaData": { ... }   // Metadata
}

Field filter:

fields=gameData,teams,away,home,name,id

Hydration Options

Enrich responses with related data:

Available Hydrations

team - Team details
linescore - Inning-by-inning scores
flags - Game flags (no-hitter, perfect game)
scoringplays - All plays that scored runs
decisions - Winning/losing/saving pitcher
person - Player biographical info
stats - Statistical data
currentTeam - Player’s current team

Multiple Hydrations

hydrate=team,linescore,decisions

Combine multiple hydrations in a single request.

More hydrations = larger response size. Only request what you need.

Rate Limiting

The MLB Stats API has rate limits:

Limits vary by endpoint
Excessive requests may be throttled
Use field filtering to reduce calls
Cache responses when possible
The playground enforces reasonable limits

Error Handling

Common error responses:

404 Not Found

The requested resource doesn’t exist:

Invalid game ID
Player not found
Wrong endpoint path

400 Bad Request

Invalid parameters:

Missing required parameter
Invalid date format
Malformed field filter

500 Server Error

API server issue:

Try again later
Check MLB API status
Report persistent errors

Best Practices

Use Field Filtering

Request only needed fields to improve performance and reduce bandwidth.

Cache Responses

Store responses for historical data that won’t change.

Handle Errors

Check status codes and handle errors gracefully in your application.

Respect Limits

Don’t exceed rate limits; implement backoff strategies.

Integration Examples

The playground helps you understand the API before integrating it into your app:

Test Endpoints: Verify the data structure
Copy Requests: Use the generated URLs in your code
Understand Responses: Know what fields are available
Debug Issues: Test parameters and troubleshoot errors

Related: API Overview

View complete API documentation and endpoint reference.

Saving Requests

Future feature: Save frequently used requests for quick access later.

Future feature: Share playground configurations via URL parameters.

Back to Features

Explore other core features of MLB.TheOhtani.com.

Get Started

Core Features

Using the App

​Overview

​Getting Started

​API Versions

​Endpoint Categories

​Schedule Endpoints

/api/v1/schedule

/api/v1.1/schedule

​Game Endpoints

/api/v1.1/game/{gamePk}/feed/live

/api/v1/game/{gamePk}/boxscore

/api/v1/game/{gamePk}/linescore

/api/v1/game/{gamePk}/winProbability

​Player Endpoints

/api/v1/people/{personId}

/api/v1/people/search

​Team Endpoints

/api/v1/teams

/api/v1/teams/{teamId}/roster

​Standings Endpoints

/api/v1/standings

​Query Parameters

​Common Parameters

​Making Requests

​Request Builder

​Response Viewer

​Example Use Cases

​Get Today’s Games

​Live Game Data

​Player Stats

​Team Standings

​Field Filtering

​Hydration Options

​Available Hydrations

​Multiple Hydrations

​Rate Limiting

​Error Handling

​Best Practices

Use Field Filtering

Cache Responses

Handle Errors

Respect Limits

​Integration Examples

Related: API Overview

​Saving Requests

​Sharing Playground Links

Back to Features

Build docs developers (and LLMs) love

Overview

Getting Started

API Versions

Endpoint Categories

Schedule Endpoints

Game Endpoints

Player Endpoints

Team Endpoints

Standings Endpoints

Query Parameters

Common Parameters

Making Requests

Request Builder

Response Viewer

Example Use Cases

Get Today’s Games

Live Game Data

Player Stats

Team Standings

Field Filtering

Hydration Options

Available Hydrations

Multiple Hydrations

Rate Limiting

Error Handling

Best Practices

Integration Examples

Saving Requests

Sharing Playground Links