# ESPN Hidden API Multi-Sport Scores Scraper (`jungle_synthesizer/espn-hidden-api-multi-sport-scores-scraper`) Actor Scrapes scores, schedules, rosters, and athlete data from ESPN's undocumented public JSON APIs (site.api.espn.com + sports.core.api.espn.com). Covers NFL, NBA, MLB, NHL, soccer, and college sports — no auth, no HTML parsing, survives site redesigns. - **URL**: https://apify.com/jungle\_synthesizer/espn-hidden-api-multi-sport-scores-scraper.md - **Developed by:** [BowTiedRaccoon](https://apify.com/jungle_synthesizer) (community) - **Categories:** Sports, AI - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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 Hidden API Multi-Sport Scores Scraper Extract scores, schedules, team rosters, and athlete data from ESPN's undocumented public JSON APIs — covering NFL, NBA, MLB, NHL, soccer, and more. No HTML parsing, no authentication, no proxy required. > **Why the hidden API?** ESPN's `site.api.espn.com` and `sports.core.api.espn.com` are the same endpoints ESPN's own website and mobile app use. They return clean, structured JSON and have been stable for years. Unlike HTML scrapers that break on every redesign, API-based extraction survives indefinitely. --- ### What Data Does It Return? All three modes return flat JSON records with consistent field names. #### Scoreboard (`scoreboard`) Game scores and schedules for any sport and league. Returns one record per game with home/away teams, scores, status (scheduled, in-progress, final), venue, and season/week context. #### Team Roster (`roster`) All athletes on a specific team's roster. Returns athlete name, position, jersey number, and status. Requires the ESPN `teamId` (find it from scoreboard `home_team_id` / `away_team_id` fields). #### Athlete List (`athletes`) Paginated full league athlete directory via `sports.core.api.espn.com`. Returns athlete name, position, jersey, and team association for every active (and recently inactive) player in the league. --- ### Input | Field | Type | Required | Description | |-------|------|----------|-------------| | `dataType` | string | Yes | What to fetch: `scoreboard`, `roster`, or `athletes` | | `sport` | string | Yes | ESPN sport slug (e.g. `basketball`, `football`, `baseball`, `hockey`, `soccer`) | | `league` | string | Yes | ESPN league slug (e.g. `nba`, `nfl`, `mlb`, `nhl`, `eng.1`, `wnba`, `ncaaf`, `ncaab`) | | `teamId` | string | For roster | ESPN team ID. Find from scoreboard output (`home_team_id`, `away_team_id`) | | `date` | string | No | Date in `YYYYMMDD` format for scoreboard. Defaults to today | | `season` | integer | No | Season year for athletes list. Defaults to current active season | | `maxItems` | integer | No | Maximum records to return | #### Example Inputs **NBA games today:** ```json { "dataType": "scoreboard", "sport": "basketball", "league": "nba", "maxItems": 20 } ```` **NFL Week 1 2025 schedule:** ```json { "dataType": "scoreboard", "sport": "football", "league": "nfl", "date": "20250907", "maxItems": 50 } ``` **Premier League today:** ```json { "dataType": "scoreboard", "sport": "soccer", "league": "eng.1", "maxItems": 20 } ``` **Los Angeles Lakers roster (teamId 13):** ```json { "dataType": "roster", "sport": "basketball", "league": "nba", "teamId": "13", "maxItems": 20 } ``` **Full NBA athlete directory:** ```json { "dataType": "athletes", "sport": "basketball", "league": "nba", "maxItems": 500 } ``` *** ### Output Schema Each record is a flat JSON object. Fields not applicable to the current `dataType` are `null`. | Field | Type | Modes | Description | |-------|------|-------|-------------| | `sport` | string | all | Sport slug | | `league` | string | all | League slug | | `data_type` | string | all | `scoreboard`, `roster`, or `athletes` | | `event_id` | string | scoreboard | ESPN event ID | | `event_name` | string | scoreboard | Full game display name | | `event_date` | string | scoreboard | Game date/time (ISO 8601) | | `status` | string | all | Game status or athlete status | | `season_year` | integer | scoreboard | Season year | | `week` | integer | scoreboard | Week number (NFL/college football) | | `home_team` | string | scoreboard | Home team name | | `home_team_id` | string | scoreboard | ESPN home team ID | | `away_team` | string | scoreboard | Away team name | | `away_team_id` | string | scoreboard | ESPN away team ID | | `home_score` | integer | scoreboard | Home team score | | `away_score` | integer | scoreboard | Away team score | | `home_record` | string | scoreboard | Home team season record (e.g. `60-22`) | | `away_record` | string | scoreboard | Away team season record | | `venue` | string | scoreboard | Stadium/arena full name | | `venue_city` | string | scoreboard | Venue city | | `athlete_id` | string | roster, athletes | ESPN athlete ID | | `athlete_name` | string | roster, athletes | Athlete full name | | `position` | string | roster, athletes | Position display name | | `jersey` | string | roster, athletes | Jersey number | | `roster_team` | string | roster, athletes | Team name | | `team_id` | string | roster, athletes | ESPN team ID | *** ### Supported Sports and Leagues | Sport | League | Input | |-------|--------|-------| | American Football | NFL | `sport: football, league: nfl` | | American Football | College Football (FBS) | `sport: football, league: college-football` | | Basketball | NBA | `sport: basketball, league: nba` | | Basketball | WNBA | `sport: basketball, league: wnba` | | Basketball | College Basketball (Men's) | `sport: basketball, league: mens-college-basketball` | | Baseball | MLB | `sport: baseball, league: mlb` | | Ice Hockey | NHL | `sport: hockey, league: nhl` | | Soccer | English Premier League | `sport: soccer, league: eng.1` | | Soccer | MLS | `sport: soccer, league: usa.1` | | Soccer | UEFA Champions League | `sport: soccer, league: uefa.champions` | | Soccer | La Liga | `sport: soccer, league: esp.1` | | Soccer | Bundesliga | `sport: soccer, league: ger.1` | Any valid ESPN sport/league slug combination works. Invalid combinations return an empty events array. *** ### Tips - **Find team IDs**: Run a scoreboard query, then read `home_team_id` and `away_team_id` from the results. - **Historical scores**: Pass a `date` in `YYYYMMDD` format to the scoreboard mode to retrieve past game results. - **Off-season**: Scoreboard queries during the off-season return zero or few results — this is expected. - **Rate limits**: ESPN's CDN is permissive. No proxy needed. For bulk roster pulls across all teams, run one query per team with `maxItems: 0`. # Actor input Schema ## `sp_intended_usage` (type: `string`): Please describe how you plan to use the data extracted by this crawler. ## `sp_improvement_suggestions` (type: `string`): Provide any feedback or suggestions for improvements. ## `sp_contact` (type: `string`): Provide your email address so we can get in touch with you. ## `dataType` (type: `string`): What to fetch: "scoreboard" (game scores/schedule), "roster" (team roster with athletes), or "athletes" (full league athlete list via sports.core.api). ## `sport` (type: `string`): ESPN sport slug. Examples: football, basketball, baseball, hockey, soccer, mma, golf, tennis, racing. ## `league` (type: `string`): ESPN league slug. Examples: nfl, nba, mlb, nhl, eng.1 (Premier League), wnba, ncaaf, ncaab. ## `teamId` (type: `string`): ESPN team ID. Required when dataType is "roster". E.g. "26" for Detroit Pistons. Find IDs from scoreboard competitor.id. ## `date` (type: `string`): Date string in YYYYMMDD format for the scoreboard endpoint. Defaults to today when omitted. ## `season` (type: `integer`): Season year for athlete list. Defaults to the current active season when omitted. ## `maxItems` (type: `integer`): Maximum number of records to return. ## Actor input object example ```json { "sp_intended_usage": "Describe your intended use...", "sp_improvement_suggestions": "Share your suggestions here...", "sp_contact": "Share your email here...", "dataType": "scoreboard", "sport": "basketball", "league": "nba", "maxItems": 10 } ``` # Actor output Schema ## `results` (type: `string`): No description # 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 = { "sp_intended_usage": "Describe your intended use...", "sp_improvement_suggestions": "Share your suggestions here...", "sp_contact": "Share your email here...", "dataType": "scoreboard", "sport": "basketball", "league": "nba", "maxItems": 10 }; // Run the Actor and wait for it to finish const run = await client.actor("jungle_synthesizer/espn-hidden-api-multi-sport-scores-scraper").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 = { "sp_intended_usage": "Describe your intended use...", "sp_improvement_suggestions": "Share your suggestions here...", "sp_contact": "Share your email here...", "dataType": "scoreboard", "sport": "basketball", "league": "nba", "maxItems": 10, } # Run the Actor and wait for it to finish run = client.actor("jungle_synthesizer/espn-hidden-api-multi-sport-scores-scraper").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 '{ "sp_intended_usage": "Describe your intended use...", "sp_improvement_suggestions": "Share your suggestions here...", "sp_contact": "Share your email here...", "dataType": "scoreboard", "sport": "basketball", "league": "nba", "maxItems": 10 }' | apify call jungle_synthesizer/espn-hidden-api-multi-sport-scores-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=jungle_synthesizer/espn-hidden-api-multi-sport-scores-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "ESPN Hidden API Multi-Sport Scores Scraper", "description": "Scrapes scores, schedules, rosters, and athlete data from ESPN's undocumented public JSON APIs (site.api.espn.com + sports.core.api.espn.com). Covers NFL, NBA, MLB, NHL, soccer, and college sports — no auth, no HTML parsing, survives site redesigns.", "version": "0.1", "x-build-id": "tZdCgoiusHnWnEMGx" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/jungle_synthesizer~espn-hidden-api-multi-sport-scores-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-jungle_synthesizer-espn-hidden-api-multi-sport-scores-scraper", "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/jungle_synthesizer~espn-hidden-api-multi-sport-scores-scraper/runs": { "post": { "operationId": "runs-sync-jungle_synthesizer-espn-hidden-api-multi-sport-scores-scraper", "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/jungle_synthesizer~espn-hidden-api-multi-sport-scores-scraper/run-sync": { "post": { "operationId": "run-sync-jungle_synthesizer-espn-hidden-api-multi-sport-scores-scraper", "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", "required": [ "dataType", "sport", "league" ], "properties": { "sp_intended_usage": { "title": "What is the intended usage of this data?", "minLength": 1, "type": "string", "description": "Please describe how you plan to use the data extracted by this crawler." }, "sp_improvement_suggestions": { "title": "How can we improve this crawler for you?", "minLength": 1, "type": "string", "description": "Provide any feedback or suggestions for improvements." }, "sp_contact": { "title": "Contact Email", "minLength": 1, "type": "string", "description": "Provide your email address so we can get in touch with you." }, "dataType": { "title": "Data Type", "enum": [ "scoreboard", "roster", "athletes" ], "type": "string", "description": "What to fetch: \"scoreboard\" (game scores/schedule), \"roster\" (team roster with athletes), or \"athletes\" (full league athlete list via sports.core.api)." }, "sport": { "title": "Sport", "type": "string", "description": "ESPN sport slug. Examples: football, basketball, baseball, hockey, soccer, mma, golf, tennis, racing." }, "league": { "title": "League", "type": "string", "description": "ESPN league slug. Examples: nfl, nba, mlb, nhl, eng.1 (Premier League), wnba, ncaaf, ncaab." }, "teamId": { "title": "Team ID (roster mode only)", "type": "string", "description": "ESPN team ID. Required when dataType is \"roster\". E.g. \"26\" for Detroit Pistons. Find IDs from scoreboard competitor.id." }, "date": { "title": "Date (scoreboard mode only)", "type": "string", "description": "Date string in YYYYMMDD format for the scoreboard endpoint. Defaults to today when omitted." }, "season": { "title": "Season year (athletes mode only)", "type": "integer", "description": "Season year for athlete list. Defaults to the current active season when omitted." }, "maxItems": { "title": "Max Items", "type": "integer", "description": "Maximum number of records to return.", "default": 15 } } }, "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 } } } } } } } } } } ```