Use ESPN Scores, Standings, Teams & News by League with Python

Pull live and recent scores, league standings, team rosters, news headlines, and full game boxscores for NFL, NBA, MLB, NHL, MLS, Premier League, La Liga, F1, UFC, PGA Golf, ATP Tennis, and more.

1. Choose the data you need

Review the published README for supported collection modes, examples, and limits. The recipe below uses the current published input definition.

2. Prepare a source-based input

This JSON contains published prefills and required-field defaults. Review every value for your task before running it; it is not a promise of successful collection.

{
  "datePreset": "today",
  "includeGameDetails": false,
  "includeGameLog": false,
  "includePlayByPlay": false,
  "includePlayerStats": false,
  "includeTeamDetails": false,
  "league": "nba",
  "liveOnly": false,
  "maxItems": 1,
  "mode": "news",
  "newsScope": "league",
  "rankingType": "all",
  "statusFilter": "all"
}

Download input.example.json and save your reviewed copy as input.json.

Field	Type	Required	Description
`mode`	string	required	What to fetch from ESPN.
`league`	string	optional	League slug. The sport is derived automatically.
`leagues`	array	optional	Optional multi-league override for modes that iterate leagues (scoreboard, odds, standings, teams, teamDetail, news, players, schedule, rankings), e.g. ["nba","nfl"].
`datePreset`	string	optional	Date window for scoreboard and odds. ESPN accepts one date per request, so ranges are fetched one day at a time.
`startDate`	string	optional	First date for datePreset=custom, in YYYYMMDD or YYYY-MM-DD.
`endDate`	string	optional	Last date for datePreset=custom (inclusive), in YYYYMMDD or YYYY-MM-DD. Maximum 366 days.
`season`	integer	optional	ESPN season year for standings, schedule, players and rankings (e.g. 2025). Leave blank for the current season.
`seasonType`	string	optional	Filter a team schedule by season phase (ignored for soccer schedules, which ESPN reports as one league season).
`teamIds`	array	optional	Teams for teams/teamDetail/schedule/players. Accepts 2, BOS or nba/BOS. Get IDs from mode=teams.
`eventIds`	array	optional	Games for gameDetail/odds. Accepts 401909904 or nba/401909904. Get IDs from mode=scoreboard.
`athleteQueries`	array	optional	Player names to search, e.g. ["LeBron James", "Jannik Sinner"].
`athleteIds`	array	optional	ESPN athlete IDs for direct profiles, e.g. ["1966"].
`rankingType`	string	optional	Which poll to return. 'all' includes every poll ESPN publishes for the league.
`statusFilter`	string	optional	Filter scoreboard, odds or schedule rows by game state.
`liveOnly`	boolean	optional	Keep only in-progress games (scoreboard and odds).
`newsScope`	string	optional	League news is capped at 50 articles by ESPN. Global pages the ESPN now feed and filters to the selected league.
`includeTeamDetails`	boolean	optional	Fetch each team's record, venue and next event. Adds one request per team.
`includeGameDetails`	boolean	optional	Attach the full game summary to every team-sport game. Adds one request per game.
`includePlayerStats`	boolean	optional	Attach latest season stats to player rows and the player box score to gameDetail. Adds requests per player.
`includeGameLog`	boolean	optional	Attach the current-season game log to each player. Adds one request per athlete.
`includePlayByPlay`	boolean	optional	Include the full play-by-play list in gameDetail (scoring plays are always included).
`maxItems`	integer	optional	Hard cap on data records. Notice rows explain unsupported or empty requests.

3. Start an Actor run

Set APIFY_TOKEN in your environment. Python 3.10 or newer is sufficient; this recipe uses no third-party packages.

Execution may incur charges. Review current pricing on Apify. The request asks for a 120-second timeout and a charge limit; these settings are subject to Apify’s pricing and do not guarantee an all-inclusive spending cap.

import json
import os
import urllib.request

# Save the schema-derived example as input.json; review and edit it first.
with open("input.json", encoding="utf-8") as stream:
    actor_input = json.load(stream)

token = os.environ["APIFY_TOKEN"]
request = urllib.request.Request(
    "https://api.apify.com/v2/acts/9euiAfrRYDea19ZZ9/runs?timeout=120&maxTotalChargeUsd=0.50",
    data=json.dumps(actor_input).encode("utf-8"),
    headers={"Authorization": "Bearer " + token, "Content-Type": "application/json"},
    method="POST",
)
# This starts a potentially billable run. Do not automatically retry this POST.
with urllib.request.urlopen(request, timeout=40) as response:
    run = json.load(response)["data"]
print("Run ID:", run["id"])
print("Status:", run["status"])
# Inspect and download results in Apify Console once the run succeeds.

4. Inspect the actual results

Open the run in Apify Console and wait for a successful completion. Use the published output schema to locate results and the dataset schema to understand declared views. Missing or optional record fields must not be treated as guaranteed values.

ESPN records for games, standings, teams, players, news, schedules, rankings and odds, with a recordType on every row.

Questions before you run

Which inputs are required?

The published required fields are mode

What does this guide verify?

The fields, prefills, and schema links are rendered from the published build. This is a usage recipe, not a paid live extraction test. Source availability and collection results can vary.

What if the run request times out?

Check Apify Console before retrying. The first request may already have created a run. Do not automatically repeat a run-creation POST.

Open on Apify Full Actor reference

Generated from source build LQ5zzKBf9U6Ues2Nj and its README and schemas. Source changes regenerate this guide; no third-party editorial claims are inferred.