# ESPN Scores & Schedules (`crawlerbros/espn-scores-schedules`) Actor Scrape live scores, final results, and upcoming game schedules from ESPN across 16 leagues and 5 sports. No account or proxy required. - **URL**: https://apify.com/crawlerbros/espn-scores-schedules.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** News, SEO tools, Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 4 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $1.00 / 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## ESPN Scores & Schedules Extract publicly available game scores and schedules from [ESPN](https://www.espn.com) — no account, login, or proxy required. Supports 16 leagues across basketball, football, baseball, hockey, and soccer. ### What This Scraper Does This actor calls ESPN's public JSON API to retrieve game results, scores, and upcoming fixture data for any combination of supported leagues and dates. With **Fetch Game Details** enabled, each game record is enriched with top performers (leaders), betting odds, attendance, and game headlines. ### Supported Leagues | Code | League | Sport | |---|---|---| | `nba` | NBA | Basketball | | `nfl` | NFL | Football | | `mlb` | MLB | Baseball | | `nhl` | NHL | Hockey | | `mls` | MLS | Soccer | | `wnba` | WNBA | Basketball | | `ncaam` | NCAA Men's Basketball | Basketball | | `ncaaw` | NCAA Women's Basketball | Basketball | | `ncaaf` | NCAA Football | Football | | `epl` | English Premier League | Soccer | | `laliga` | La Liga | Soccer | | `ucl` | UEFA Champions League | Soccer | | `bundesliga` | Bundesliga | Soccer | | `seriea` | Serie A | Soccer | | `ligue1` | Ligue 1 | Soccer | | `ligamx` | Liga MX | Soccer | ### Input | Field | Type | Default | Description | |---|---|---|---| | **Leagues** | string[] | `["nba"]` | One or more league codes from the table above. | | **Date Mode** | enum | `today` | `today`, `yesterday`, `tomorrow`, `single`, or `range`. | | **Date** | string | — | `YYYYMMDD` — required when Date Mode is `single`. | | **Start Date** | string | — | `YYYYMMDD` — required when Date Mode is `range`. | | **End Date** | string | — | `YYYYMMDD` — required when Date Mode is `range`. Max span: 30 days. | | **Timezone** | string | `UTC` | IANA timezone (e.g. `America/New_York`) for `dateLocal` and for resolving `today`/`yesterday`/`tomorrow`. | | **Fetch Game Details** | boolean | `false` | Adds leaders, odds, attendance, and headlines per game. One extra request per game. | | **Max Items** | integer | `100` | Cap on total records returned (1–10,000). | #### Date Mode Examples | Mode | What it fetches | |---|---| | `today` | Games scheduled or completed today in the given timezone | | `yesterday` | Yesterday's final scores | | `tomorrow` | Tomorrow's scheduled fixtures | | `single` + `date: "20240115"` | All games on 15 January 2024 | | `range` + `startDate: "20240101"` + `endDate: "20240107"` | Seven days of games | ### Output Each record represents one game. Fields marked `?` are optional and appear only when ESPN provides them. #### Core Fields (always present) | Field | Type | Description | |---|---|---| | `gameId` | string | ESPN event ID | | `league` | string | League code e.g. `"nba"` | | `sport` | string | Sport e.g. `"basketball"` | | `status` | string | `"scheduled"`, `"in_progress"`, `"final"`, `"postponed"`, or `"cancelled"`. Note: delayed games are reported as `"scheduled"` — check `statusDetail` for the text `"Delayed"`. | | `statusDetail` | string? | Human-readable detail e.g. `"Q3 4:23"`, `"Final"`, `"7:30 PM ET"` | | `date` | string | ISO 8601 UTC kickoff time | | `dateLocal` | string? | Kickoff in requested timezone | | `name` | string | Full game name e.g. `"Boston Celtics at Los Angeles Lakers"` | | `shortName` | string | Abbreviated matchup e.g. `"BOS @ LAL"` | | `homeTeam` | object | `{id, name, abbreviation, score, logo}` | | `awayTeam` | object | `{id, name, abbreviation, score, logo}` | | `venue` | object? | `{name, city, state, country}` | | `broadcasts` | string[]? | TV/streaming channels e.g. `["ESPN", "ABC"]` | | `scrapedAt` | string | ISO 8601 UTC scrape timestamp | #### Extra Fields (Fetch Game Details: true) | Field | Type | Description | |---|---|---| | `leaders` | object? | `{home: [{name, position, stat, value}], away: [...]}` — top performers | | `odds` | object? | `{provider, details, overUnder, spread}` — pre-game betting line | | `attendance` | integer? | Actual game attendance | | `headline` | string? | Game recap or preview headline | | `gameNotes` | string[]? | Notable notes e.g. records set, milestones | #### Error Records If a league/date combination fails, the record contains: | Field | Description | |---|---| | `inputLeague` | The league code that was attempted | | `inputDate` | The date string that was attempted | | `error` | Human-readable error message | | `scrapedAt` | Timestamp | ### Frequently Asked Questions **Do I need an ESPN account or API key?** No. This scraper uses ESPN's public JSON API which is freely accessible without any login or authentication. **Is a proxy required?** No. ESPN's public API has no bot protection. This scraper works out of the box on Apify cloud without any proxy configuration. **How do I get yesterday's NBA scores?** Set **Leagues** to `["nba"]` and **Date Mode** to `yesterday`. Run the actor and all final scores from the previous day will be in the dataset. **How do I get scores for multiple leagues at once?** Add multiple codes to the **Leagues** array — e.g. `["nba", "nfl", "epl"]`. Each league and date combination is fetched independently. **What does the `score` field look like for a scheduled game?** The `score` field on `homeTeam` and `awayTeam` will be `0` for games that haven't started yet. Check the `status` field: a value of `"scheduled"` means the game has not begun. **What is the maximum date range?** 30 days. Requesting a range larger than 30 days will return an error. For historical bulk data, run multiple 30-day range requests. **How often is the data updated?** The actor fetches data live from ESPN's API at run time. For real-time in-game scores, schedule the actor to run every few minutes using Apify's scheduler. **What leagues are available for soccer?** MLS (`mls`), English Premier League (`epl`), La Liga (`laliga`), UEFA Champions League (`ucl`), Bundesliga (`bundesliga`), Serie A (`seriea`), Ligue 1 (`ligue1`), and Liga MX (`ligamx`). # Actor input Schema ## `leagues` (type: `array`): One or more league codes to scrape. Supported: nba, nfl, mlb, nhl, mls, wnba, ncaam, ncaaw, ncaaf, epl, laliga, ucl, bundesliga, seriea, ligue1, ligamx. ## `dateMode` (type: `string`): Which date(s) to fetch. 'today', 'yesterday', 'tomorrow' use the timezone field. 'single' requires the date field. 'range' requires startDate and endDate (max 30 days). ## `date` (type: `string`): Required when dateMode is 'single'. Format: YYYYMMDD — e.g. 20240115. ## `startDate` (type: `string`): Required when dateMode is 'range'. Format: YYYYMMDD. ## `endDate` (type: `string`): Required when dateMode is 'range'. Format: YYYYMMDD. Maximum span is 30 days. ## `timezone` (type: `string`): IANA timezone used for the dateLocal field and for resolving today/yesterday/tomorrow. E.g. America/New_York, Europe/London. ## `fetchDetails` (type: `boolean`): Fetch per-game detail: leaders, odds, attendance, headlines. Makes one extra request per game. ## `maxItems` (type: `integer`): Maximum total game records to return across all leagues and dates. ## Actor input object example ```json { "leagues": [ "nba" ], "dateMode": "today", "timezone": "UTC", "fetchDetails": false, "maxItems": 100 } ```` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "leagues": [ "nba" ], "dateMode": "today" }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/espn-scores-schedules").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "leagues": ["nba"], "dateMode": "today", } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/espn-scores-schedules").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "leagues": [ "nba" ], "dateMode": "today" }' | apify call crawlerbros/espn-scores-schedules --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/espn-scores-schedules", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "ESPN Scores & Schedules", "description": "Scrape live scores, final results, and upcoming game schedules from ESPN across 16 leagues and 5 sports. No account or proxy required.", "version": "0.0", "x-build-id": "7bmIcIDZDOdZE6xCs" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~espn-scores-schedules/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-espn-scores-schedules", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~espn-scores-schedules/runs": { "post": { "operationId": "runs-sync-crawlerbros-espn-scores-schedules", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~espn-scores-schedules/run-sync": { "post": { "operationId": "run-sync-crawlerbros-espn-scores-schedules", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "leagues": { "title": "Leagues", "type": "array", "description": "One or more league codes to scrape. Supported: nba, nfl, mlb, nhl, mls, wnba, ncaam, ncaaw, ncaaf, epl, laliga, ucl, bundesliga, seriea, ligue1, ligamx.", "default": [ "nba" ], "items": { "type": "string" } }, "dateMode": { "title": "Date Mode", "enum": [ "today", "yesterday", "tomorrow", "single", "range" ], "type": "string", "description": "Which date(s) to fetch. 'today', 'yesterday', 'tomorrow' use the timezone field. 'single' requires the date field. 'range' requires startDate and endDate (max 30 days).", "default": "today" }, "date": { "title": "Date (YYYYMMDD)", "type": "string", "description": "Required when dateMode is 'single'. Format: YYYYMMDD — e.g. 20240115." }, "startDate": { "title": "Start Date (YYYYMMDD)", "type": "string", "description": "Required when dateMode is 'range'. Format: YYYYMMDD." }, "endDate": { "title": "End Date (YYYYMMDD)", "type": "string", "description": "Required when dateMode is 'range'. Format: YYYYMMDD. Maximum span is 30 days." }, "timezone": { "title": "Timezone", "type": "string", "description": "IANA timezone used for the dateLocal field and for resolving today/yesterday/tomorrow. E.g. America/New_York, Europe/London.", "default": "UTC" }, "fetchDetails": { "title": "Fetch Game Details", "type": "boolean", "description": "Fetch per-game detail: leaders, odds, attendance, headlines. Makes one extra request per game.", "default": false }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum total game records to return across all leagues and dates.", "default": 100 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```