# MLB Teams, Player Search & Season Schedule Lookup (`vexaloom-labs/mlb-teams-player-search-and-season-schedule-lookup`) Actor

Look up every current MLB team, search for a player by name, or pull a full season's schedule and scores, with stadium, roster, and matchup details for each record.

- **URL**: https://apify.com/vexaloom-labs/mlb-teams-player-search-and-season-schedule-lookup.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** Automation, Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## MLB Teams, Player Search & Season Schedule Lookup

Pull Major League Baseball reference data in three shapes: the full list of current MLB teams with their stadium and founding details, a name search across MLB players with bio and position info, or a season's full schedule of games with final or in-progress scores.

### What this actor does

- Lists every current MLB team with city, stadium, founding year, and official website
- Searches MLB players by name and returns position, physical stats, nationality, and a short bio
- Pulls a full season's game schedule with home/away teams, scores, venue, and status
- Tags every record with a `recordType` so mixed exports stay easy to filter
- Only includes a field when the data source actually supplied it — no blank or placeholder values

### Output per team (`recordType: "mlb_team"`)

- `teamId` — unique team identifier
- `teamName` — full team name
- `shortName` — abbreviated team name
- `city` — team's home location
- `stadium` — home stadium name
- `formedYear` — year the franchise was founded
- `website` — official team website
- `logoUrl` — team logo image URL
- `teamUrl` — reference page for the team
- `scrapedAt` — ISO 8601 timestamp of when the record was collected

### Output per player (`recordType: "mlb_player"`)

- `playerId` — unique player identifier
- `playerName` — player's full name
- `team` — current team name
- `nationality` — player's nationality
- `position` — playing position
- `height` / `weight` — physical stats as published
- `birthDate` — date of birth
- `description` — short biography (truncated to 300 characters)
- `imageUrl` — player photo or cutout image
- `profileUrl` — reference page for the player
- `scrapedAt` — ISO 8601 timestamp of when the record was collected

### Output per game (`recordType: "mlb_game"`)

- `eventId` — unique game/event identifier
- `eventName` — game title (typically "Away Team vs Home Team")
- `homeTeam` / `awayTeam` — team names
- `homeScore` / `awayScore` — final or current score (omitted for games that haven't been played yet)
- `season` — season the game belongs to
- `matchDate` — date the game was/is scheduled
- `venue` — stadium where the game is played
- `status` — game status as published
- `eventUrl` — reference page for the game
- `scrapedAt` — ISO 8601 timestamp of when the record was collected

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `teams` | `teams` (all current MLB teams), `players` (search by name), or `games` (a season's schedule) |
| `searchQuery` | string | `Shohei Ohtani` | Player name to search; used only in `players` mode |
| `season` | string | `2024` | Season year to pull games for (`2022`, `2023`, or `2024`); used only in `games` mode |
| `maxItems` | integer | `20` | Maximum records to return (1–200) |

#### Example: list all current MLB teams

```json
{
    "mode": "teams",
    "maxItems": 30
}
```

#### Example: search for a player

```json
{
    "mode": "players",
    "searchQuery": "Aaron Judge",
    "maxItems": 10
}
```

#### Example: pull a season's schedule

```json
{
    "mode": "games",
    "season": "2023",
    "maxItems": 200
}
```

### Use cases

- **Fantasy baseball tools** pulling player bios and team reference data to enrich a roster app
- **Sports content sites** keeping a simple, always-current list of MLB teams and stadiums
- **Analytics projects** building a season-by-season game log without hand-collecting scores
- **Trivia and reference apps** looking up a player's position, nationality, or physical stats by name
- **Data pipelines** that need a lightweight MLB reference layer without a paid sports-data subscription

### FAQ

**Do I need an API key or MLB account?** No — all three modes read from a free, public sports-data source and require no authentication.

**Why does `players` mode only return results for one name at a time?** Each run searches the single name given in `searchQuery`; run it again with a different name to look up another player.

**Why are `homeScore`/`awayScore` sometimes missing from a game record?** Those fields are only included once a score has actually been published for that game; scheduled-but-not-yet-played games omit them rather than showing a zero.

**Which seasons can I pull with `games` mode?** 2022, 2023, or 2024 — pick the one you need in the `season` input.

**Why is `description` cut off at 300 characters?** Player biographies are truncated to keep records a consistent, manageable size; the full bio is not currently returned.

**Is this affiliated with Major League Baseball?** No. This is an independent actor that reads publicly available MLB reference data; it is not endorsed by or affiliated with MLB or any team.

# Actor input Schema

## `mode` (type: `string`):

What data to fetch.

## `searchQuery` (type: `string`):

Player name for players mode.

## `season` (type: `string`):

MLB season year.

## `maxItems` (type: `integer`):

Maximum records to return.

## Actor input object example

```json
{
  "mode": "teams",
  "searchQuery": "Shohei Ohtani",
  "season": "2024",
  "maxItems": 20
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset containing all scraped MLB team, player, or game records.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "teams",
    "searchQuery": "Shohei Ohtani",
    "season": "2024",
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/mlb-teams-player-search-and-season-schedule-lookup").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "teams",
    "searchQuery": "Shohei Ohtani",
    "season": "2024",
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/mlb-teams-player-search-and-season-schedule-lookup").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "teams",
  "searchQuery": "Shohei Ohtani",
  "season": "2024",
  "maxItems": 20
}' |
apify call vexaloom-labs/mlb-teams-player-search-and-season-schedule-lookup --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/mlb-teams-player-search-and-season-schedule-lookup"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/wVtKgpxucAbbIa9P3/builds/V6ZY83AGWDTk4LlbA/openapi.json