{ "openapi": "3.0.1", "info": { "title": "Understat xG Scraper – Football Data & Analytics", "description": "Scrape normalized Understat xG data for leagues, teams, players and matches, including shots, rosters, xA, PPDA and global trends. Export JSON, CSV or Excel. Pay $0.75-$1 per 1,000 delivered rows based on your Apify plan.", "version": "0.3", "x-build-id": "ZHA1nGjEAg03tJJiM" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/datascraperes~understat-football-data/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-datascraperes-understat-football-data", "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/datascraperes~understat-football-data/runs": { "post": { "operationId": "runs-sync-datascraperes-understat-football-data", "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/datascraperes~understat-football-data/run-sync": { "post": { "operationId": "run-sync-datascraperes-understat-football-data", "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", "properties": { "mode": { "title": "1. What report do you want?", "enum": [ "league", "team", "player", "match", "player_search", "global_trends" ], "type": "string", "description": "Choose one report per run. League returns teams, players, and matches; Team returns players, matches, and breakdowns; Player returns a profile, matches, and shots; Match returns rosters and shots; Find a player ID searches by name; Global trends returns monthly league averages. Each saved row is billed once at the rate for your Apify plan.", "default": "league" }, "league": { "title": "2. League (League report only)", "enum": [ "EPL", "La_liga", "Bundesliga", "Serie_A", "Ligue_1", "RFPL" ], "type": "string", "description": "Used only for League. Select one of the six competitions available from Understat. It is ignored by Team, Player, Match, player search, and Global trends reports.", "default": "EPL" }, "season": { "title": "3. Season start year (League or Team)", "minimum": 2014, "maximum": 2100, "type": "integer", "description": "Used only for League and Team reports. Enter the year in which the season started: 2024 means 2024/25. Years from 2014 to 2100 are accepted, but the source may not contain every competition and season. A year included in a Team URL overrides this value.", "default": 2024 }, "target": { "title": "4. Target (Team, Player, Match, or player search)", "maxLength": 200, "type": "string", "description": "Leave empty to try a working example. For Team enter a name, slug, or Understat team URL (example: Arsenal). For Player enter its numeric ID or player URL (example: 7322). For Match enter its numeric ID or match URL (example: 26602). For Find a player ID enter at least two characters of the player's name (example: Saka). League and Global trends ignore this field." }, "maxItems": { "title": "5. Maximum rows to save and charge", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Safety limit for the entire run, from 1 to 5,000. The form starts at 1 for a test costing at most USD 0.001; if an API call omits this field, the 1,000-row default costs at most USD 1.00 and less on eligible paid Apify plans. Increase it when you need more data. Only successfully saved rows are billed.", "default": 1000 }, "includePlayers": { "title": "Include player summaries", "type": "boolean", "description": "League and Team only. When enabled, saves one aggregate row per player. It has no effect on Player, Match, player search, or Global trends reports.", "default": true }, "includeMatches": { "title": "Include match rows", "type": "boolean", "description": "League and Team: includes fixtures and completed matches. Player: includes match-by-match performance. It has no effect on Match, player search, or Global trends reports.", "default": true }, "includeShots": { "title": "Include shot rows", "type": "boolean", "description": "Player and Match only. Saves one row per shot with coordinates, xG, situation, result, body part, and assist context. Shot rows can be the largest part of a result.", "default": true }, "includeBreakdowns": { "title": "Include team breakdowns", "type": "boolean", "description": "Team only. Includes aggregate rows by situation, formation, game state, timing, shot zone, attack speed, and result.", "default": true }, "includeRosters": { "title": "Include match rosters", "type": "boolean", "description": "Match only. Saves one row per player appearance, including team, position, minutes, goals, cards, xG, xA, xGChain, and xGBuildup.", "default": true }, "team": { "title": "Legacy team input", "minLength": 1, "maxLength": 200, "type": "string", "description": "Backward-compatible API field. New runs should use target." }, "playerId": { "title": "Legacy player ID input", "minimum": 1, "maximum": 99999999, "type": "integer", "description": "Backward-compatible API field. New runs should use target." }, "matchId": { "title": "Legacy match ID input", "minimum": 1, "maximum": 99999999, "type": "integer", "description": "Backward-compatible API field. New runs should use target." }, "searchQuery": { "title": "Legacy player search input", "minLength": 2, "maxLength": 100, "type": "string", "description": "Backward-compatible API field. New runs should use target." } } }, "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 } } } } } } } } } }