# ESPN News (`crawlerbros/espn-news`) Actor Scrape ESPN news articles and headlines across 16 leagues and 5 sports. Optional team filter. No account or proxy required. - **URL**: https://apify.com/crawlerbros/espn-news.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** News, Other, SEO tools - **Stats:** 1 total users, 0 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 News Scraper Scrape news articles and headlines from [ESPN](https://www.espn.com) — no account or subscription required. Supports 16 leagues across 5 sports including the NBA, NFL, MLB, NHL, MLS, WNBA, NCAA basketball and football, Premier League, La Liga, Champions League, Bundesliga, Serie A, Ligue 1, and Liga MX. ### What This Scraper Does This actor fetches news articles from ESPN's public JSON API and returns one flat record per article with headline, description, full HTML body, author, publication timestamp, image URLs, and related team/athlete references. Optional team filter fetches additional team-specific articles. ### Supported Leagues | Code | Sport | League | |---|---|---| | `nba` | Basketball | NBA | | `wnba` | Basketball | WNBA | | `ncaam` | Basketball | NCAA Men's | | `ncaaw` | Basketball | NCAA Women's | | `nfl` | Football | NFL | | `ncaaf` | Football | NCAA Football | | `mlb` | Baseball | MLB | | `nhl` | Hockey | NHL | | `mls` | Soccer | Major League Soccer | | `epl` | Soccer | English Premier League | | `laliga` | Soccer | La Liga (Spain) | | `ucl` | Soccer | UEFA Champions League | | `bundesliga` | Soccer | Bundesliga (Germany) | | `seriea` | Soccer | Serie A (Italy) | | `ligue1` | Soccer | Ligue 1 (France) | | `ligamx` | Soccer | Liga MX (Mexico) | ### Input | Field | Type | Description | |---|---|---| | **Leagues** | List of strings | League codes to scrape. Defaults to `["nba"]`. | | **Teams** | List of strings (optional) | Filter by team abbreviation (case-insensitive, e.g. `"LAL"`) or ESPN numeric team ID (e.g. `"13"`). Team-filtered articles are fetched IN ADDITION to league-wide articles. Unknown entries log a warning and are skipped. | | **Fetch Full Article Body** | Boolean | If enabled, makes one extra API call per article to fetch the full HTML body (`story` field). Without this, only headlines and summaries are returned. Adds ~300ms per article. Default: `false`. | | **Max Items** | Integer | Maximum number of article records across all leagues (1–10,000). Default: 100. | #### Team Filter Examples - Just Lakers: `"teams": ["LAL"]` - By ID: `"teams": ["13"]` - Multiple: `"teams": ["LAL", "BOS", "GS"]` - Mixed: `"teams": ["LAL", "17"]` #### Why ~10 Articles Per League? ESPN's public news endpoint returns a fixed feed of approximately 10 articles per request and does NOT support pagination, offset, or date filtering. To get more articles per league, use the **Teams** filter — each team adds another ~10 team-specific articles to the fetch. ### Output Each record represents one article. Fields marked `?` are optional and appear only when ESPN returns data for them. Duplicates (same article fetched via both league-wide and team filters) are automatically deduped by `articleId`. | Field | Type | Description | |---|---|---| | `articleId` | string | ESPN article ID (dedup key) | | `league` | string | League code e.g. `"nba"` | | `sport` | string | e.g. `"basketball"` | | `type` | string? | e.g. `"Story"`, `"Preview"`, `"HeadlineNews"`, `"Media"` | | `headline` | string | Always present | | `description` | string? | Short summary | | `story` | string? | Full HTML body of the article (only when **Fetch Full Article Body** is enabled) | | `byline` | string? | Author name | | `published` | string? | ISO 8601 publication timestamp | | `lastModified` | string? | ISO 8601 last-modified timestamp | | `premium` | boolean? | If `true`, ESPN+ paid content | | `url` | string? | Web URL to the article | | `mobileUrl` | string? | Mobile web URL | | `images` | object[]? | Array of `{url, caption?, credit?, width?, height?}` | | `keywords` | string[]? | ESPN keyword tags | | `relatedTeams` | object[]? | Array of `{teamId, teamName, abbreviation}` | | `relatedAthletes` | object[]? | Array of `{athleteId, athleteName}` | | `inputTeam` | string? | The team-filter entry that fetched this article (only on team-filtered results) | | `scrapedAt` | string | ISO 8601 UTC scrape timestamp | Fields only appear when ESPN returns data — no nulls. #### Error Records If a league news feed fails to fetch after retries, an error record is emitted: | Field | Description | |---|---| | `inputLeague` | League code attempted | | `inputTeam` | Team (if team-filtered fetch failed) | | `error` | Human-readable message | | `scrapedAt` | Timestamp | ### Frequently Asked Questions **Do I need an ESPN account?** No. This scraper only uses ESPN's public JSON API. **Is a proxy required?** No. ESPN's public API has no bot protection for typical use. **Can I get articles from a specific date?** No — ESPN's public news endpoint does not support date filtering. Articles are returned in reverse chronological order (newest first). To capture daily news, run the actor on a schedule (e.g., hourly or daily) and dedupe downstream by `articleId`. **How many articles can I get per league per run?** ESPN returns ~10 articles for the league-wide feed. Use the **Teams** filter to get ~10 more per team — so for NBA with all 30 teams, you can get up to ~310 articles per run. Duplicates are auto-removed. **What's the difference between the `story` field and `description`?** `description` is a one-sentence summary; `story` is the full article HTML body (with `

`, ``, etc.). **When does the `story` field appear?** Only when you enable the **Fetch Full Article Body** input option. ESPN's main news feed returns only headlines and summaries. The body requires an additional API call per article, so it's opt-in. Enable it if you need the full article HTML for downstream processing. **How do I handle the HTML body?** The `story` field contains raw HTML. You can strip tags downstream (e.g., BeautifulSoup for plain text), render it in an HTML viewer, or extract specific elements like paragraphs or links. **Why are some articles marked `premium: true`?** Those are ESPN+ paid content. The API returns the same metadata (headline, description, body) but you'd need an ESPN+ account to read the article on espn.com. The scraped data itself is fully available. **How do dedup + team filters work together?** If you specify `teams: ["LAL"]` and `leagues: ["nba"]`, the scraper fetches the NBA league feed AND the Lakers team feed. An article appearing in both is returned once (with `inputTeam` set to `LAL` if it was seen via the team feed first). Use this to maximize coverage without duplicates. **What's the difference between this actor and the other ESPN actors?** - **Scores & Schedules** — game results, live scores, upcoming schedules - **Standings** — team rankings and W/L records - **Rosters & Player Stats** — team rosters and player career stats - **News** — articles and headlines (this actor) **Can I combine multiple leagues?** Yes. Pass multiple codes in `leagues`, e.g. `["nba", "epl", "mlb"]`. Each record is tagged with its league. **How often is ESPN updating the news?** News is near real-time. ESPN publishes new articles throughout the day, so a hourly schedule will usually pick up 5–20 fresh articles per league. # Actor input Schema ## `leagues` (type: `array`): League codes to scrape. Supported: nba, nfl, mlb, nhl, mls, wnba, ncaam, ncaaw, ncaaf, epl, laliga, ucl, bundesliga, seriea, ligue1, ligamx. ## `teams` (type: `array`): Optional team filter by abbreviation (case-insensitive, e.g. 'LAL') or ESPN numeric team ID. If provided, team-filtered articles are fetched in addition to the league-wide feed. Unknown entries log warnings. ## `fetchFullBody` (type: `boolean`): If enabled, makes one extra API call per article to fetch the full HTML body (`story` field). Adds ~300ms per article. Without this, only headline and description are returned. Default: false. ## `maxItems` (type: `integer`): Maximum number of article records to return across all leagues (1–10,000). ## Actor input object example ```json { "leagues": [ "nba" ], "fetchFullBody": 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" ] }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/espn-news").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"] } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/espn-news").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" ] }' | apify call crawlerbros/espn-news --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/espn-news", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "ESPN News", "description": "Scrape ESPN news articles and headlines across 16 leagues and 5 sports. Optional team filter. No account or proxy required.", "version": "0.0", "x-build-id": "SmS1WN9KED40i5pHL" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~espn-news/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-espn-news", "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-news/runs": { "post": { "operationId": "runs-sync-crawlerbros-espn-news", "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-news/run-sync": { "post": { "operationId": "run-sync-crawlerbros-espn-news", "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": [ "leagues" ], "properties": { "leagues": { "title": "Leagues", "type": "array", "description": "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" } }, "teams": { "title": "Teams (optional)", "type": "array", "description": "Optional team filter by abbreviation (case-insensitive, e.g. 'LAL') or ESPN numeric team ID. If provided, team-filtered articles are fetched in addition to the league-wide feed. Unknown entries log warnings.", "items": { "type": "string" } }, "fetchFullBody": { "title": "Fetch Full Article Body", "type": "boolean", "description": "If enabled, makes one extra API call per article to fetch the full HTML body (`story` field). Adds ~300ms per article. Without this, only headline and description are returned. Default: false.", "default": false }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of article records to return across all leagues (1–10,000).", "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 } } } } } } } } } } ```