ESPN NFL Season-Aware Stats Scraper

What does this Actor do?

ESPN NFL Season-Aware Stats Scraper collects public ESPN NFL team standings, roster/player metadata, scoreboard events, and news. It uses bounded HTTPS requests to ESPN’s public CDN and public site API routes, normalizes the business fields, and records source-season provenance for every normal row.

The Actor does not log in, use credentials, use a proxy, request arbitrary URLs, bypass CAPTCHA, paywalls, geofences, rate limits, device checks, or WAFs, or invent missing values. A blocked or unreadable source produces an exact diagnostic row instead of a fabricated business record.

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

Scope and use cases

Use this Actor for season-aware NFL team snapshots, public roster research, scoreboard and schedule collection, and ESPN NFL news discovery. A run can discover teams from the public standings feed or accept bounded public ESPN team slugs, abbreviations, or IDs.

Normal dataset rows are one of nfl-team, nfl-player, nfl-game, or nfl-news. Diagnostics are separate four-field rows with a public ESPN URL, error message, error code, and timestamp.

Source targets and public-page boundaries

The Actor uses these public ESPN routes:

• NFL standings and team discovery
• Team metadata and rosters
• Scoreboard
• NFL news

These are public ESPN web/CDN feeds, not private endpoints. Requests are sequential, response-size limited to 8 MiB, timed out at 15 seconds, and retried only for bounded transient server or transport failures. The Actor stops at the configured record limit and never substitutes a guessed team, player, game, or article.

Input

Complete public input

{
  "teams": [
    "buf"
  ],
  "maxTeams": 1,
  "maxItems": 30,
  "season": 2026,
  "requestDelayMs": 250,
  "includePlayers": true,
  "maxPlayersPerTeam": 12
}

Input fields

• teams is optional and accepts up to 32 public ESPN team slugs, abbreviations, or numeric IDs. An empty list discovers teams from the public standings feed.
• maxTeams accepts 1 through 32 selected teams and defaults to 8.
• maxItems accepts 1 through 500 total output rows, including diagnostics, and defaults to 120.
• season accepts 2000 through 2035 and defaults to the current NFL season.
• requestDelayMs accepts 0 through 5,000 milliseconds and defaults to 250.
• includePlayers defaults to true and controls public roster retrieval.
• maxPlayersPerTeam accepts 0 through 100 and defaults to 20.
• fixtureFile is an optional local QA-only JSON path inside the Actor directory. Omit it for real ESPN evidence.

Unknown fields, credentials, proxy settings, arbitrary URLs, and email/contact extraction are rejected.

Runnable input examples

Public smoke run

{
  "teams": [
    "buf"
  ],
  "maxTeams": 1,
  "maxItems": 5,
  "season": 2026,
  "includePlayers": false,
  "requestDelayMs": 0
}

Team and roster run

{
  "teams": [
    "buf",
    "mia"
  ],
  "maxTeams": 2,
  "maxItems": 40,
  "season": 2025,
  "includePlayers": true,
  "maxPlayersPerTeam": 10
}

Standings discovery with no team filter

{
  "teams": [],
  "maxTeams": 4,
  "maxItems": 23,
  "season": 2026,
  "requestDelayMs": 0
}

Player-free bounded run

{
  "teams": [
    "buf"
  ],
  "maxTeams": 1,
  "maxItems": 20,
  "season": 2026,
  "includePlayers": false,
  "maxPlayersPerTeam": 0,
  "requestDelayMs": 500
}

Local fixture QA

{
  "teams": [
    "buf"
  ],
  "maxTeams": 1,
  "maxItems": 5,
  "season": 2026,
  "includePlayers": true,
  "maxPlayersPerTeam": 2,
  "fixtureFile": "fixtures/nfl.json"
}

Fixture mode is deterministic local QA only and is not Cloud evidence.

Output contract

Normal team row

Every normal row contains sourceName, sourceKind, sourceUrl, league, season, requestedSeason, seasonLabel, seasonStartYear, and scrapedAt, plus type-specific public fields.

{
  "recordType": "nfl-team",
  "sourceName": "ESPN public NFL feeds",
  "sourceKind": "public-espn-cdn",
  "sourceUrl": "https://cdn.espn.com/core/nfl/standings?xhr=1&season=2026",
  "league": "nfl",
  "season": 2026,
  "requestedSeason": 2026,
  "seasonLabel": "2026 NFL season",
  "seasonStartYear": 2026,
  "teamId": "2",
  "teamName": "Buffalo Bills",
  "teamAbbreviation": "BUF",
  "teamSlug": "buf",
  "wins": 3,
  "losses": 0,
  "winPercent": 1,
  "scrapedAt": "2026-09-09T00:00:00.000Z"
}

Normal game row

{
  "recordType": "nfl-game",
  "sourceName": "ESPN public NFL feeds",
  "sourceKind": "public-espn-api",
  "sourceUrl": "https://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard?limit=100&dates=2026",
  "league": "nfl",
  "season": 2025,
  "requestedSeason": 2026,
  "seasonLabel": "2025 NFL season",
  "seasonStartYear": 2025,
  "eventId": "401000001",
  "eventName": "Buffalo Bills at Fixture Team",
  "eventDate": "2026-01-04T18:00:00.000Z",
  "homeTeam": "Fixture Team",
  "awayTeam": "Buffalo Bills",
  "homeScore": 24,
  "awayScore": 27,
  "gameStatus": "Final",
  "completed": true,
  "scrapedAt": "2026-09-09T00:00:00.000Z"
}

Diagnostic row

Diagnostics always contain exactly these four fields and never claim a replacement business record.

{
  "url": "https://site.api.espn.com/apis/site/v2/sports/football/nfl/news?limit=20",
  "error": "The public ESPN endpoint rate-limited the request; no replacement record was claimed.",
  "errorCode": "RATE_LIMITED",
  "scrapedAt": "2026-09-09T00:00:00.000Z"
}

Field semantics

• requestedSeason is the input season.
• season is the source-reported season. For games, this is ESPN event.season.year when present.
• seasonStartYear equals season.
• seasonLabel is normalized as season plus the text NFL season.
• Team fields cover identity and available standings values.
• Player fields cover public roster identity, team, position, jersey, physical values, status, and public profile media.
• Game fields cover event identity, date, season type, competitors, scores, status, venue, and broadcasts.
• News fields cover article identity, headline, description, publication time, image, and public article URL.
• Missing values are omitted. They are never replaced with zero, false, unknown, or a placeholder.

Run summary and source metadata

Normal summary

OUTPUT_SUMMARY, OUTPUT, and SOURCE_METADATA keep execution state and provenance outside normal business rows.

{
  "source": "ESPN public NFL feeds",
  "status": "SUCCESS",
  "season": 2026,
  "requestedSeason": 2026,
  "seasonLabelPolicy": "seasonLabel is normalized as \"{season} NFL season\" using the source-reported season.",
  "seasonStartYearPolicy": "seasonStartYear equals the source-reported season.year, or requestedSeason when the source omits it.",
  "requestedItemCount": 5,
  "recordsStored": 5,
  "normalCount": 5,
  "diagnosticCount": 0,
  "duplicateCount": 0,
  "attemptedRequests": 4,
  "typeCounts": {
    "nfl-team": 1,
    "nfl-game": 1,
    "nfl-news": 3
  },
  "fixtureMode": false,
  "completedAt": "2026-09-09T00:00:08.000Z"
}

Partial and diagnostic outcomes

PARTIAL means at least one normal row and at least one diagnostic row were stored. DIAGNOSTIC means no normal row was available. ERROR is reserved for an unexpected workflow failure. Check diagnostic errorCode and url before retrying.

{
  "source": "ESPN public NFL feeds",
  "status": "PARTIAL",
  "season": 2026,
  "requestedSeason": 2026,
  "requestedItemCount": 5,
  "recordsStored": 2,
  "normalCount": 1,
  "diagnosticCount": 1,
  "duplicateCount": 0,
  "attemptedRequests": 3,
  "typeCounts": {
    "nfl-team": 1
  },
  "fixtureMode": false,
  "completedAt": "2026-09-09T00:00:08.000Z"
}

{
  "source": "ESPN public NFL feeds",
  "status": "DIAGNOSTIC",
  "season": 2026,
  "requestedSeason": 2026,
  "requestedItemCount": 1,
  "recordsStored": 1,
  "normalCount": 0,
  "diagnosticCount": 1,
  "duplicateCount": 0,
  "attemptedRequests": 1,
  "typeCounts": {},
  "fixtureMode": false,
  "completedAt": "2026-09-09T00:00:08.000Z"
}

Source metadata

{
  "sourceName": "ESPN public NFL feeds",
  "sourceWebsite": "https://www.espn.com/nfl/",
  "directRequestsOnly": true,
  "fixtureMode": false,
  "seasonConvention": "ESPN NFL season.year is the season start year; a January or February game can belong to the prior season even when its calendar date is in the requested year.",
  "generatedAt": "2026-09-09T00:00:08.000Z"
}

How to scrape in Apify Console

Console steps

1. Open the Actor in Apify Console.
2. Select a season and optionally enter public ESPN team slugs or abbreviations.
3. Set maxItems and decide whether public roster players are needed.
4. Click Start and wait for the run to finish.
5. Review normal rows, diagnostic rows, OUTPUT_SUMMARY, and SOURCE_METADATA together.
6. Export the dataset in the format you need.

For a real run, leave fixtureFile empty. Fixture mode is for local deterministic QA and must not be used as evidence of live ESPN availability.

Cost and performance

Requests are sequential and paced by requestDelayMs. The run is bounded by maxTeams, maxItems, maxPlayersPerTeam, the 15-second per-request timeout, the 8 MiB response limit, and bounded retries. Lower maxItems and set includePlayers to false for a quick smoke check.

The Actor does not use a proxy or browser automation. Exact cost depends on Apify Actor compute, request latency, response size, and the number of selected teams and public roster records.

Advanced usage

Season-aware analysis

Use season for the requested feed year, then group games by the emitted season field. January and February games can belong to the prior NFL season even when their calendar date is in the next year.

Team selection

An empty teams array discovers teams from the public standings feed. A non-empty teams array requests only the listed public ESPN keys, bounded by maxTeams. Team records can be followed by roster, scoreboard, and news rows until maxItems is reached.

Fail-closed behavior

Access refusal, login prompts, CAPTCHA, paywalls, geofences, WAF checks, invalid JSON, oversized responses, and rate limits become diagnostics. The Actor never turns a blocked source into a zero-valued record.

API access

Apify API clients can start a run with the same JSON input, then read the default dataset and OUTPUT_SUMMARY, OUTPUT, and SOURCE_METADATA key-value records. This accesses Apify storage; it does not provide access to private ESPN systems.

{
  "teams": [
    "buf"
  ],
  "maxTeams": 1,
  "maxItems": 5,
  "season": 2026,
  "includePlayers": false
}

Do not place credentials, cookies, private headers, or signed storage URLs in support tickets or public examples.

Troubleshooting

The run contains only diagnostics

Inspect each diagnostic errorCode and url. Retry later for a transient network or upstream error; do not increase access or bypass settings because none are supported.

The season appears inconsistent

Compare requestedSeason, season, seasonStartYear, and seasonLabel. ESPN season.year is the NFL season start year, not always the calendar year of eventDate.

Fewer records than maxItems

maxItems is an upper bound. The public feed may contain fewer usable teams, players, games, or articles, or a diagnostic may consume one output slot.

Fixture data appears in a run

Check SOURCE_METADATA.fixtureMode and OUTPUT_SUMMARY.fixtureMode. Remove fixtureFile for real ESPN evidence.

Issues and support

For support, include the Apify run ID, non-secret input shape, summary status, diagnostic error codes, and public source URL. Do not include cookies, private headers, credentials, or signed storage URLs.

Privacy and non-affiliation

This Actor is an independent third-party tool. It collects public information from ESPN’s public NFL feeds and does not claim affiliation with, sponsorship by, or endorsement from ESPN. Treat athlete names, profiles, and images as potentially personal data; use them only for a lawful, legitimate purpose and respect ESPN’s terms and applicable law.