{ "openapi": "3.0.1", "info": { "title": "ESPN Sports Data Scraper: Boxscores, Gamelogs & Odds", "description": "Extract ESPN sports data in bulk: live and historical scores, boxscores, odds, standings, schedules, rosters and player gamelogs, 17 leagues. Flat CSV, Excel and pandas output. Run via API, schedule runs, or integrate with other tools and AI workflows. By MrBridge (mr-bridge.com)", "version": "0.3", "x-build-id": "ikmaGgIokOscq7ZAU" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/mrbridge~espn-sports-data-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-mrbridge-espn-sports-data-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/mrbridge~espn-sports-data-scraper/runs": { "post": { "operationId": "runs-sync-mrbridge-espn-sports-data-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/mrbridge~espn-sports-data-scraper/run-sync": { "post": { "operationId": "run-sync-mrbridge-espn-sports-data-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", "league" ], "properties": { "dataType": { "title": "Data type", "enum": [ "scoreboard", "gameSummary", "playByPlay", "playerBoxscore", "schedule", "teams", "standings", "roster", "athletes", "athleteGamelog", "news" ], "type": "string", "description": "What to extract. Each type produces its own flat row shape. See the README for the full field list per type.", "default": "scoreboard" }, "league": { "title": "League", "enum": [ "nfl", "college-football", "nba", "wnba", "mens-college-basketball", "womens-college-basketball", "mlb", "nhl", "eng.1", "esp.1", "ita.1", "ger.1", "fra.1", "usa.1", "uefa.champions", "uefa.europa", "fifa.world" ], "type": "string", "description": "Which league to pull from. 17 leagues in v1. Not every data type is available for every league (see the capability matrix in the README).", "default": "nba" }, "startDate": { "title": "Start date", "type": "string", "description": "Start of the date range for a scoreboard pull, format YYYY-MM-DD. Use this with End date, or use Seasons for full-season bulk." }, "endDate": { "title": "End date", "type": "string", "description": "End of the date range for a scoreboard pull, format YYYY-MM-DD. Inclusive." }, "seasons": { "title": "Seasons", "type": "array", "description": "One season year per line, for bulk multi-season pulls (scoreboard, standings, gamelog). Season bounds are discovered from ESPN, never hardcoded.", "items": { "type": "string" } }, "seasonType": { "title": "Season type", "enum": [ "all", "1", "2", "3" ], "type": "string", "description": "Which part of the season to pull. Default is All (preseason + regular season + postseason). Picking a single type narrows the request sent to ESPN, which decides what it returns: a run may occasionally include a game whose season_type differs from the one asked for. Each row carries its own season_type, so you can filter afterwards if you need an exact match.", "default": "all" }, "teamIds": { "title": "Team IDs", "type": "array", "description": "ESPN team IDs, one per line. Required for Team schedule and Roster.", "items": { "type": "string" } }, "eventIds": { "title": "Event (game) IDs", "type": "array", "description": "ESPN event/game IDs, one per line. Used by Game summary, Play-by-play and Player boxscore. You can also chain these automatically from a scoreboard run with 'Also fetch game details'.", "items": { "type": "string" } }, "athleteIds": { "title": "Athlete IDs", "type": "array", "description": "ESPN athlete IDs, one per line. Required for Athlete gamelog.", "items": { "type": "string" } }, "withGameDetails": { "title": "Also fetch game details", "type": "boolean", "description": "On a scoreboard run, fetch up to one additional game-summary row per game, with team boxscore totals, play count, and available odds. Each delivered summary is one billed result; the result limit applies across all rows.", "default": false }, "includeOdds": { "title": "Include odds", "type": "boolean", "description": "Attach betting odds (spread, moneyline, over/under) to game detail rows when available.", "default": false }, "includeBoxscore": { "title": "Include boxscore", "type": "boolean", "description": "Include team-level boxscore stats on Game summary rows.", "default": true }, "resolveRefs": { "title": "Resolve athlete references", "type": "boolean", "description": "For the Athletes directory: resolve each athlete reference into a full profile (extra requests). Turn off to emit only IDs and reference URLs (much cheaper).", "default": true }, "allSeasons": { "title": "All available seasons (gamelog)", "type": "boolean", "description": "For Athlete gamelog: discover and pull every season available for the athlete, instead of listing them in Seasons.", "default": false }, "outputFormat": { "title": "Output format", "enum": [ "flat", "raw", "both" ], "type": "string", "description": "flat = one flat snake_case row (data-science ready). raw = the ESPN JSON fragment for the entity. both = flat plus a raw field.", "default": "flat" }, "resultLimit": { "title": "Result limit", "minimum": 0, "type": "integer", "description": "Stop the run after this many results. Each result is one billed row, so this is also your cost ceiling. Set 0 for no limit." }, "maxItems": { "title": "Max items (deprecated)", "minimum": 0, "type": "integer", "description": "Deprecated, replaced by Result limit. Still accepted so runs and tasks saved before this release keep working." }, "maxChargedEvents": { "title": "Max charged events (deprecated)", "minimum": 0, "type": "integer", "description": "Deprecated, replaced by Result limit. Still accepted so runs and tasks saved before this release keep working." }, "ncaaGroups": { "title": "NCAA group override", "minimum": 1, "type": "integer", "description": "Override the ESPN group used for NCAA scoreboards, or leave this blank to use the league-specific default. This setting is ignored for non-NCAA leagues." }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Datacenter proxies are sufficient for ESPN's open API and are the default. Residential is unnecessary here (wasted cost) but available if 403s ever appear.", "default": { "useApifyProxy": true } }, "capturePlan": { "title": "Capture plan", "type": "string", "description": "Maintainer only. Name of a closed diagnostic capture campaign. Requires Internal capture mode. The allowlist lives in the code: any other value is rejected without issuing a request." }, "internalCaptureMode": { "title": "Internal capture mode", "type": "boolean", "description": "Maintainer-only. When true, captures raw ESPN responses to a named KV store for building test fixtures. Not for normal use.", "default": false } } }, "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 } } } } } } } } } }