ESPN Games Data Actor

An Apify Actor that fetches sports games data from ESPN's public API. Supports multiple sports and leagues with flexible date ranges and filtering options.

Features

• Multi-league support: Fetch games from NBA, NFL, MLB, NHL, MLS, EPL, and more in a single run
• Flexible date modes: Today, tomorrow, yesterday, single date, or date ranges
• Team filtering: Filter games by team abbreviations
• Status filtering: Filter by game status (scheduled, in progress, final)
• Timezone conversion: Output dates in your preferred timezone
• Rate limiting: Built-in 1 req/sec rate limiting with exponential backoff

Supported Leagues

Sport	League	Code
Basketball	NBA	nba
Basketball	WNBA	wnba
Basketball	NCAA Men's	ncaam
Basketball	NCAA Women's	ncaaw
Football	NFL	nfl
Football	NCAA Football	ncaaf
Baseball	MLB	mlb
Hockey	NHL	nhl
Soccer	MLS	mls
Soccer	English Premier League	epl
Soccer	La Liga	laliga
Soccer	UEFA Champions League	ucl

Input

Parameter	Type	Required	Default	Description
leagues	string[]	Yes	-	League codes to fetch
dateMode	enum	Yes	today	today, tomorrow, yesterday, single, range
date	string	No	-	Date in YYYYMMDD format (for single mode)
startDate	string	No	-	Start date YYYYMMDD (for range mode)
endDate	string	No	-	End date YYYYMMDD (for range mode)
teams	string[]	No	[]	Filter by team abbreviations (e.g., LAL, NYK)
gameStatus	string[]	No	["pre", "in", "post"]	Filter by game status
timezone	string	No	UTC	Output timezone (e.g., America/New_York)

Example Input

{
  "leagues": ["nba", "nhl"],
  "dateMode": "today",
  "teams": [],
  "gameStatus": ["pre", "in", "post"],
  "timezone": "America/New_York"
}

Date Range Example

{
  "leagues": ["nfl"],
  "dateMode": "range",
  "startDate": "20260118",
  "endDate": "20260120",
  "timezone": "America/Los_Angeles"
}

Output

Each game is output as a flat object:

{
  "gameId": "401584721",
  "sport": "basketball",
  "league": "nba",
  "date": "2026-01-23T00:00:00Z",
  "dateLocal": "2026-01-22T19:00:00-05:00",
  "name": "Cleveland Cavaliers at Charlotte Hornets",
  "shortName": "CLE @ CHA",
  "status": {
    "state": "pre",
    "description": "Scheduled",
    "detail": "7:00 PM ET",
    "clock": null,
    "period": null
  },
  "homeTeam": {
    "id": "30",
    "name": "Charlotte Hornets",
    "abbreviation": "CHA",
    "score": null
  },
  "awayTeam": {
    "id": "5",
    "name": "Cleveland Cavaliers",
    "abbreviation": "CLE",
    "score": null
  },
  "venue": {
    "name": "Spectrum Center",
    "city": "Charlotte",
    "state": "NC"
  },
  "broadcasts": ["NBA TV"]
}

Status States

State	Description
pre	Game is scheduled but hasn't started
in	Game is currently in progress
post	Game has ended (final, postponed, canceled)

Local Development

1. Install dependencies:

   $npm install
   

2. Create input file at storage/key_value_stores/default/INPUT.json

3. Run the actor:

   $npm start
   

4. Output will be saved to storage/datasets/default/

Scheduling Examples

Use Case	Cron Expression	Description
Daily morning digest	0 6 * * *	6 AM daily
Live score updates	*/5 * * * *	Every 5 minutes
Weekly preview	0 8 * * 1	Monday at 8 AM
Nightly results	0 2 * * *	2 AM daily

License

ISC