{
  "openapi": "3.0.1",
  "info": {
    "title": "Understat Scraper: Football xG & Player Stats",
    "description": "Scrape Understat expected goals (xG), xA, npxG, shots and key passes per player for the Premier League, La Liga, Bundesliga, Serie A, Ligue 1 and RFPL since 2014. Computed per-90 rates. Export CSV, Excel, JSON. No login or API key. La Liga 2025/26 returns 600 players.",
    "version": "0.1",
    "x-build-id": "ZLojdPHYRep6DCeXt"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/recordsdata~understat-xg-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-recordsdata-understat-xg-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/recordsdata~understat-xg-scraper/runs": {
      "post": {
        "operationId": "runs-sync-recordsdata-understat-xg-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/recordsdata~understat-xg-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-recordsdata-understat-xg-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",
        "properties": {
          "entity": {
            "title": "What to export",
            "enum": [
              "players",
              "teams",
              "matches",
              "playerCareer"
            ],
            "type": "string",
            "description": "players: one row per player for a league season or a club squad (xG, xA, shots, minutes). teams: league table per season with xG, xGA, xPoints and PPDA (optional situation splits). matches: results and fixtures with match xG. playerCareer: one row per season of a player's career, found by player ID or name.",
            "default": "players"
          },
          "leagues": {
            "title": "Leagues",
            "maxItems": 6,
            "type": "array",
            "description": "Leagues to export: Premier League (EPL), La Liga, Bundesliga, Serie A, Ligue 1 or the Russian Premier League. Used by the players, teams and matches exports.",
            "items": {
              "type": "string",
              "enum": [
                "EPL",
                "La_liga",
                "Bundesliga",
                "Serie_A",
                "Ligue_1",
                "RFPL"
              ],
              "enumTitles": [
                "Premier League",
                "La Liga",
                "Bundesliga",
                "Serie A",
                "Ligue 1",
                "Russian Premier League"
              ]
            },
            "default": [
              "EPL"
            ]
          },
          "teams": {
            "title": "Teams (optional)",
            "maxItems": 200,
            "type": "array",
            "description": "Club names, for example Arsenal, Manchester City or Real Madrid (spaces or underscores both work). Players export: adds a squad table per club. Teams and matches exports: keeps only these clubs inside the selected leagues. Up to 200 names.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "season": {
            "title": "Season",
            "type": "string",
            "description": "Season start year as 4 digits: 2025 means the 2025/26 season. Data available from 2014 (2014/15) to the current season. Not used by playerCareer or by matches selected by match ID.",
            "default": "2025"
          },
          "matchStatus": {
            "title": "Match status",
            "enum": [
              "played",
              "scheduled",
              "all"
            ],
            "type": "string",
            "description": "Matches export only. played: finished matches with goals and xG. scheduled: upcoming fixtures with Understat win probabilities. all: both.",
            "default": "played"
          },
          "dateFrom": {
            "title": "Matches from date (optional)",
            "type": "string",
            "description": "Matches export only. Keep matches on or after this day, format YYYY-MM-DD (for example 2025-12-01). Leave empty for no start limit.",
            "default": ""
          },
          "dateTo": {
            "title": "Matches to date (optional)",
            "type": "string",
            "description": "Matches export only. Keep matches on or before this day, format YYYY-MM-DD. Leave empty for no end limit.",
            "default": ""
          },
          "matchIds": {
            "title": "Match IDs (optional)",
            "maxItems": 200,
            "type": "array",
            "description": "Matches export only. Understat match IDs or match URLs (the number in understat.com/match/28778). When filled, only these matches are exported and the league, team, season and date filters are ignored. Up to 200.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "playerIds": {
            "title": "Player IDs or names (for player careers)",
            "maxItems": 200,
            "type": "array",
            "description": "Player careers export only. Understat player IDs or player URLs (the number in understat.com/player/8260), or a full player name that matches exactly one player. Up to 200.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "includeShots": {
            "title": "Include shot-level data",
            "type": "boolean",
            "description": "Matches and player careers only. Adds one extra row per shot with pitch X/Y position, xG, minute, situation, body part and result. Billed per shot row. Off by default.",
            "default": false
          },
          "includeSplits": {
            "title": "Include team situation splits",
            "type": "boolean",
            "description": "Teams export only. Adds rows per club with xG and shots for and against by situation, formation, game state, timing, shot zone, attack speed and result. Billed per split row. Off by default.",
            "default": false
          },
          "minMinutes": {
            "title": "Minimum minutes",
            "minimum": 0,
            "type": "integer",
            "description": "Players export only. Only export players with at least this many minutes played in the season. 0 means every player.",
            "default": 0
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "xG",
              "goals",
              "xA",
              "assists",
              "shots",
              "time",
              "xGChain"
            ],
            "type": "string",
            "description": "Players export only. Metric that orders the player rows, highest first: xG, goals, xA, assists, shots, minutes (time) or xGChain.",
            "default": "xG"
          },
          "onlyNew": {
            "title": "Only new or changed rows",
            "type": "boolean",
            "description": "Deliver only rows that are new or changed since the last run with the same filters (new match results, new shots, updated player and team totals). Rows already delivered are skipped and not charged.",
            "default": false
          },
          "stateKey": {
            "title": "Monitor name (optional)",
            "type": "string",
            "description": "Name for the memory of previous results. Leave empty to derive it from your filters. Use the same name to share memory between runs, or a different name to keep separate monitors.",
            "default": ""
          },
          "resetSeen": {
            "title": "Forget previous results",
            "type": "boolean",
            "description": "Clear the memory for this monitor before the run, so every row counts as new again.",
            "default": false
          },
          "maxItems": {
            "title": "Max Items",
            "minimum": 1,
            "maximum": 1000000,
            "type": "integer",
            "description": "Maximum number of rows to export, which is also the cap on what you are charged. Free users: limited to 10 rows (preview). Paid users: optional, up to 1,000,000."
          }
        }
      },
      "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}