# SoccerStats Football Statistics Scraper (`automation-lab/soccerstats-football-stats-scraper`) Actor

Export SoccerStats league tables, team form, fixtures, results, scoring trends, and home-away performance rows.

- **URL**: https://apify.com/automation-lab/soccerstats-football-stats-scraper.md
- **Developed by:** [Automation Lab](https://apify.com/automation-lab) (community)
- **Categories:** Sports
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.62 / 1,000 item extracteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## SoccerStats Football Statistics Scraper

Export public SoccerStats league tables, fixtures, match results, team form, scoring trends, and home-away performance as structured dataset rows.

The Actor is designed for the recurring job behind a **soccerstats league 2** tracker: refresh football datasets without copying tables by hand. It also accepts other public SoccerStats league codes and archived-season codes.

### What can you collect?

- current league standings with position, games, wins, draws, losses, goals, and points;
- upcoming fixture dates, kickoff times, and teams;
- completed match results and source outcome indicators;
- team form tables for several recent-match windows;
- separate home, away, and relative performance tables;
- scoring trends such as goal thresholds, both-teams-scored, clean sheets, and failed-to-score rates.

Every row includes its league code, table name, source URL, record type, and extraction timestamp.

### Who is this SoccerStats scraper for?

**Football analysts** can refresh comparable league and team tables for models and notebooks.

**Sports publishers** can feed fixture, result, and table data into editorial workflows.

**Match researchers** can compare form, home-away splits, and scoring tendencies.

**Data teams** can schedule stable exports to datasets, spreadsheets, warehouses, or webhook automations.

### Why use this Actor?

SoccerStats exposes many useful tables across separate pages. This Actor turns those pages into one consistent record format while preserving section-specific columns in `metrics`.

It supports both easy league-code input and exact SoccerStats league URLs. The same section selection and output limit apply to either input route.

SoccerStats blocks ordinary automated datacenter requests. The Actor therefore uses a bounded UK residential-proxy route, retries once with a fresh identity on transient or challenge failures, and stops with a visible error rather than returning a misleading empty dataset.

### Input

| Field | Type | Default | Description |
|---|---|---:|---|
| `leagueCodes` | string array | `['england4']` | Values from SoccerStats' `league=` URL parameter. An `_YYYY` suffix selects an archived season. |
| `startUrls` | URL array | none | Exact public SoccerStats league URLs. The URL must include a valid `league` parameter. |
| `sections` | string array | all six | Choose `standings`, `fixtures`, `results`, `form`, `homeAway`, and/or `trends`. |
| `maxItems` | integer | `500` | Global output limit from 1 to 10,000 records. |

If both URL and code inputs are supplied, both are processed and duplicate page/section combinations are removed.

### Get started in three steps

1. Open the Actor input page.
2. Keep `england4` for League Two or enter another code from a public SoccerStats league URL.
3. Select the required sections and click **Start**.

For a quick current table and match-results export, use:

```json
{
  "leagueCodes": ["england4"],
  "sections": ["standings", "results"],
  "maxItems": 60
}
```

### Supported sections

#### Standings

Returns the main league table with standard table fields and available source-specific metrics.

#### Fixtures

Returns upcoming match rows from the league page. Fixtures contain a date label, kickoff time, home team, away team, and `scheduled` outcome.

#### Results

Returns completed matches with home and away goals, outcome, and source indicators such as total goals or both-teams-scored.

#### Form

Returns recent form tables, including the match-window and home/away scope in `tableName`.

#### Home-away performance

Returns home table, away table, and relative home-away performance rows.

#### Scoring trends

Returns team scoring-trend rows. Extra table columns are retained by their SoccerStats labels in `metrics`.

### Output fields

| Field | Meaning |
|---|---|
| `recordType` | Selected section that produced the row. |
| `leagueCode`, `leagueName`, `season` | Source league identity and archived season when present. |
| `tableName` | Human-readable table or statistical slice. |
| `position`, `team` | Team-table identity fields. |
| `played`, `wins`, `draws`, `losses` | Standard team record fields when available. |
| `goalsFor`, `goalsAgainst`, `goalDifference` | Team scoring totals. |
| `points`, `pointsPerGame` | Table points and PPG. |
| `date`, `time` | Source match date label and kickoff time. |
| `homeTeam`, `awayTeam` | Match participants. |
| `homeGoals`, `awayGoals`, `outcome` | Result score and outcome, or fixture state. |
| `metrics` | Additional labelled columns from the source table. |
| `sourceUrl`, `scrapedAt` | Provenance and UTC extraction time. |

Fields that do not apply to a record type are `null`. This lets one default dataset carry team and match rows without inventing values.

### Output example

```json
{
  "recordType": "standings",
  "leagueCode": "england4",
  "leagueName": "League Two",
  "season": null,
  "tableName": "League table",
  "position": 1,
  "team": "Sample City",
  "played": 5,
  "wins": 4,
  "draws": 0,
  "losses": 1,
  "goalsFor": 12,
  "goalsAgainst": 6,
  "goalDifference": 6,
  "points": 12,
  "pointsPerGame": 2.4,
  "metrics": { "CS": "60%", "SR": "100%" },
  "sourceUrl": "https://www.soccerstats.com/latest.asp?league=england4",
  "scrapedAt": "2026-09-11T06:00:00.000Z"
}
```

Team names in this documentation are anonymized. Actual runs return the public names shown by SoccerStats.

### How much does it cost to export SoccerStats football statistics?

The Actor uses pay-per-event pricing:

- **$0.005** when a run starts;
- each useful dataset row is charged at the active plan's `item` price;
- current item tiers range from **$0.0011978 on FREE** to **$0.00062496 on GOLD, PLATINUM, and DIAMOND**.

At the FREE-tier price, 25 useful records cost about **$0.03495** including the start event. A 100-row export costs about **$0.12478**. Apify shows the exact charge limit and active tier before a run.

Failed parsing attempts and rejected rows are not charged as items. Residential proxy and platform usage are covered by the Actor's event price rather than billed as a separate Actor event.

### Schedule recurring dataset refreshes

Use an Apify schedule to run the same league and section input daily or weekly. Downstream automations can compare the new dataset against a prior export, update a warehouse, or notify a team when a fixture or table row changes.

The Actor produces snapshots; it does not maintain history or send alerts by itself. Store each run's dataset in your own destination when longitudinal analysis is required.

### Export and integrations

From the Dataset tab you can download JSON, CSV, Excel, XML, or RSS-compatible output.

Common workflows include:

- send current tables to Google Sheets with Make;
- load results into BigQuery or PostgreSQL;
- trigger a webhook when a scheduled run finishes;
- join scoring trends with an internal match model;
- build a lightweight football-content refresh pipeline.

### Run with the Apify API

Set `APIFY_TOKEN` in your shell; do not put a token into source code.

#### cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~soccerstats-football-stats-scraper/runs?token=$APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"leagueCodes":["england4"],"sections":["fixtures","results"],"maxItems":50}'
```

#### JavaScript

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/soccerstats-football-stats-scraper').call({
  leagueCodes: ['england4'],
  sections: ['standings', 'form'],
  maxItems: 100,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
from apify_client import ApifyClient
import os

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/soccerstats-football-stats-scraper').call(run_input={
    'leagueCodes': ['england4'],
    'sections': ['homeAway', 'trends'],
    'maxItems': 100,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)
```

### Use with MCP and AI assistants

#### Claude Code

Add the Actor to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/soccerstats-football-stats-scraper"
```

#### Claude Desktop, Cursor, and VS Code

Use this equivalent configuration in Claude Desktop, Cursor, or VS Code:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/soccerstats-football-stats-scraper"
    }
  }
}
```

Example prompts:

- “Export the current SoccerStats League Two standings and show the top five teams.”
- “Get League Two upcoming fixtures and scoring trends as JSON.”
- “Compare Premier League home and away points-per-game rows.”

### Reliability and limits

SoccerStats is the source of truth for available leagues, seasons, fixtures, and statistical columns. Page content can change without notice.

The Actor validates the expected table shape. A challenge page, unsupported URL, missing league parameter, or changed source layout causes a failed run instead of a successful empty dataset.

Dates are kept as source labels because SoccerStats pages may omit a year and timezone. Normalize them downstream only when your league and season context supplies the missing information.

One run stops at `maxItems`. Records are emitted in page and section processing order, so a small limit may be reached before later selected sections.

### Troubleshooting

#### Why did my run report no records?

Confirm that the league code is current, the selected section exists on that league page, and an archived suffix points to a season that SoccerStats still exposes. A parser-shape error may also indicate a source redesign.

#### Why do some fields contain null?

The dataset combines team tables and match rows. Match scores do not apply to standings, while table points do not apply to fixtures. Section-specific values remain in `metrics`.

#### Why must an exact URL include `league=`?

The league parameter is the stable source scope. Requiring it prevents accidental crawling of unrelated SoccerStats pages and ensures the selected sections can be applied consistently.

### Legality and responsible use

This Actor collects publicly displayed football statistics. Review SoccerStats' terms, robots guidance, and applicable law before running it at scale.

Use modest schedules, request only the sections you need, and do not republish source branding or protected content as your own. Do not use the Actor to bypass accounts, access controls, or personal-data protections.

### FAQ

#### Does it require a SoccerStats account?

No. It targets public league pages and does not accept login credentials.

#### Can it scrape an archived season?

Yes, when SoccerStats provides the season through a league code such as `england4_2025`.

#### Does it predict match outcomes?

No. It exports source statistics for your own analysis; it does not generate predictions or betting advice.

#### Can I select one team?

Not currently. Use the dataset API or your downstream tool to filter `team`, `homeTeam`, or `awayTeam`.

#### Are updates real time?

No guarantee is made. Each run captures what the public SoccerStats page displays at extraction time.

### Related automation-lab Actors

For broader sports workflows, combine this Actor with [SofaScore Live Events & Statistics Scraper](https://apify.com/automation-lab/sofascore-live-events-statistics-scraper) when you need scheduled or live event context from a different source.

Use each source's identifiers independently; the Actors do not claim that team or competition names map perfectly across providers.

# Actor input Schema

## `leagueCodes` (type: `array`):

SoccerStats league identifiers from the league= URL parameter. Add an optional \_YYYY suffix for an archived season.

## `startUrls` (type: `array`):

Optional SoccerStats league URLs with a league query parameter. The selected sections are applied consistently to each URL.

## `sections` (type: `array`):

Choose the SoccerStats datasets to export. Each selected section produces typed rows in the default dataset.

## `maxItems` (type: `integer`):

Stop after this many records across all leagues and sections.

## Actor input object example

```json
{
  "leagueCodes": [
    "england4"
  ],
  "sections": [
    "standings",
    "fixtures",
    "results"
  ],
  "maxItems": 20
}
```

# Actor output Schema

## `dataset` (type: `string`):

Default dataset containing all extracted SoccerStats records.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "leagueCodes": [
        "england4"
    ],
    "sections": [
        "standings",
        "fixtures",
        "results"
    ],
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/soccerstats-football-stats-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "leagueCodes": ["england4"],
    "sections": [
        "standings",
        "fixtures",
        "results",
    ],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/soccerstats-football-stats-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "leagueCodes": [
    "england4"
  ],
  "sections": [
    "standings",
    "fixtures",
    "results"
  ],
  "maxItems": 20
}' |
apify call automation-lab/soccerstats-football-stats-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/soccerstats-football-stats-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/49Cd3OKCRfPJYTQLo/builds/o1y5noBRTiZUC9gDA/openapi.json