# Soccer Fixtures, Live Scores & Results Scraper (`hgservices/soccer-fixtures-scraper`) Actor

Get football fixtures, live scores and results from 219 soccer leagues: Premier League, LaLiga, Serie A, Bundesliga, Champions League, MLS, Liga MX and more. Goalscorers, cards, team form, venues and betting odds. Export to JSON, CSV or Excel.

- **URL**: https://apify.com/hgservices/soccer-fixtures-scraper.md
- **Developed by:** [Harish Garg](https://apify.com/hgservices) (community)
- **Stats:** 4 total users, 4 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 saved fixtures

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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Soccer Fixtures, Live Scores & Results Scraper — 219 Football Leagues

Get **soccer fixtures, live scores and final results** from 219 football competitions around the world. Premier League, LaLiga, Serie A, Bundesliga, Ligue 1, Champions League, Europa League, MLS, Liga MX, Brasileirão, Argentine Primera, J.League, Saudi Pro League, the World Cup, every major women's league, and many more.

Each row is one match, with the kick-off time in your timezone, the score, the result, goalscorers and cards with the minute, team form, the venue, attendance, TV channels and betting odds. Download the data as JSON, CSV, Excel or HTML, or read it from the API.

No API key. No login. No coding needed.

### What does Soccer Fixtures & Results Scraper do?

- **Fixtures** — upcoming matches with kick-off time, venue, recent form and broadcasters.
- **Live scores** — matches in play right now, with the match clock and the current score.
- **Results** — final scores, the winner, and how the match was decided (normal time, extra time or penalties).
- **Goals and cards** — every goal and every yellow or red card, with the minute and the player. Penalties and own goals are marked.
- **Team statistics** — possession, shots, shots on target, corners and fouls.
- **Betting odds** — moneyline (home, draw, away), over/under total and spread, where available.
- **Whole seasons** — a complete season of one league or of many leagues in one run.
- **Your timezone** — "today" and "this weekend" mean your today and your weekend, not a US one.

### Supported leagues and competitions

219 competitions from every confederation.

| Region | Competitions | Examples |
|--------|--------------|----------|
| Europe (UEFA) | 86 | Premier League, Championship, LaLiga, Serie A, Bundesliga, Ligue 1, Eredivisie, Primeira Liga, Süper Lig, Scottish Premiership, Champions League, Europa League, Conference League, FA Cup, Copa del Rey, DFB-Pokal |
| South America (CONMEBOL) | 38 | Brasileirão Série A and B, Argentine Primera, Copa Libertadores, Copa Sudamericana, Colombian, Chilean, Peruvian, Uruguayan and Ecuadorian leagues |
| North and Central America (CONCACAF) | 32 | MLS, Liga MX, NWSL, USL Championship, Canadian Premier League, CONCACAF Champions Cup, Leagues Cup, Gold Cup |
| Asia and Oceania (AFC) | 18 | J.League, Saudi Pro League, Chinese Super League, Indian Super League, A-League, AFC Champions League Elite |
| Africa (CAF) | 8 | Africa Cup of Nations, CAF Champions League, CAF Confederation Cup, South African Premiership |
| International (FIFA) | 37 | FIFA World Cup and qualifiers, Club World Cup, Olympic football, international friendlies, club friendlies |

39 of the 219 are **women's competitions**, such as the WSL, NWSL, Liga F, Frauen-Bundesliga, UEFA Women's Champions League and the Women's World Cup.

Search the full list in the **Leagues** field of the input form. You can also pick a **League Group** or a **Country**.

### Why use this soccer data scraper?

- **Fixture and results feeds** — Schedule a daily run and publish an up-to-date fixture list for any league, with kick-off times in your users' timezone.
- **Betting and prediction models** — Get complete seasons with results, scorelines, goal minutes, team form and odds. The `retrievedAt` timestamp on each row lets you compare snapshots over time.
- **Live score widgets** — Turn on **In-Play Only** and run every few minutes.
- **Club trackers** — Filter by one club and get its league, cup and European matches together.
- **Player goal logs** — Filter by player name to list every match in which a player scored or was booked.
- **Historical research and fantasy football** — Download past seasons for analysis in Excel, Google Sheets, Python or R.

### How to scrape soccer fixtures and results

1. Click **Try for free** and sign in to Apify. A free account is enough.
2. In **Leagues**, pick one or more competitions. Or pick a **League Group**, such as `top5` or `womens`.
3. In **Date Range**, pick the dates, for example **Today**, **Next 7 days** or **A whole season**.
4. Optional: set your **Output Timezone** and add filters, such as a team, a player or a match status.
5. Click **Start**. The run usually finishes in seconds.
6. Open the **Output** tab. Download the data as JSON, CSV, Excel or HTML, or view it as a table.

### Input

All fields are optional. With an empty input, you get the next 7 days of fixtures in the Premier League, LaLiga, Serie A, Bundesliga, Ligue 1, MLS and the Argentine Liga Profesional.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `leagues` | string\[] | top 5 European leagues, MLS, Argentina (only when no league, group or country is selected) | Competitions by code, such as `eng.1` (Premier League), `esp.1` (LaLiga), `ita.1` (Serie A), `ger.1` (Bundesliga), `fra.1` (Ligue 1), `uefa.champions` or `usa.1` (MLS). The input form shows the name of every competition |
| `leagueGroups` | string\[] | `[]` | Named bundles of leagues. See the table below |
| `countries` | string\[] | `[]` | Every competition of a country, by name (`England`, `Brazil`) or by code (`eng`, `esp`, `ita`, `ger`, `fra`, `bra`, `arg`, `usa`, `mex`, `jpn`, `ksa`) |
| `dateMode` | string | `next7Days` | `today`, `tomorrow`, `yesterday`, `thisWeek`, `thisWeekend`, `next7Days`, `last7Days`, `next30Days`, `last30Days`, `thisMonth`, `single`, `range`, `season` |
| `date` | string | today | For `single`. Format `YYYYMMDD` or `YYYY-MM-DD` |
| `startDate`, `endDate` | string | today, today + 6 days | For `range`. Format `YYYYMMDD` or `YYYY-MM-DD`. Up to 400 days |
| `seasonYear` | integer | current season | For `season`. The year the season starts in: `2025` is 2025-26 in Europe and the 2025 season in Brazil or MLS |
| `teams` | string\[] | `[]` | Only matches of these teams. A club name or part of one (`liverpool`), an abbreviation (`LIV`) or a team ID |
| `homeAwayFilter` | string | `all` | With a team filter: `home`, `away` or `all` |
| `matchStatus` | string\[] | all | `pre` (scheduled), `in` (in play), `post` (finished) |
| `results` | string\[] | `[]` | Only finished matches with these results: `home`, `away`, `draw` |
| `liveOnly` | boolean | `false` | Only matches in play right now |
| `startingWithinHours` | integer | — | Only matches that kick off within this many hours |
| `minGoals` | integer | — | Only matches with at least this many goals |
| `players` | string\[] | `[]` | Only matches in which one of these players scored or was booked |
| `includeMatchEvents` | boolean | `true` | Add the goals and cards timeline |
| `includeTeamStats` | boolean | `false` | Add possession, shots, corners and fouls |
| `includeOdds` | boolean | `false` | Add moneyline, total and spread odds |
| `maxMatches` | integer | — | The maximum number of rows |
| `timezone` | string | `UTC` | IANA timezone, such as `Europe/London`, `America/New_York` or `Asia/Tokyo`. It sets the local kick-off time and the calendar day of each match |

`leagues`, `leagueGroups` and `countries` add together. For example, you can select the Premier League, all women's competitions and all Brazilian football in one run.

#### League groups

| Group | Leagues | Contents |
|-------|---------|----------|
| `top5` | 5 | Premier League, LaLiga, Serie A, Bundesliga, Ligue 1 |
| `europeTop` | 16 | The top five plus the Netherlands, Portugal, Belgium, Turkey, Scotland, Austria, Greece, Sweden, Norway, Denmark and Russia |
| `englishPyramid` | 5 | Premier League down to the National League |
| `uefaClub` | 4 | Champions League, Europa League, Conference League, Super Cup |
| `domesticCups` | 13 | FA Cup, Carabao Cup, Copa del Rey, Coppa Italia, DFB-Pokal, Coupe de France and more |
| `americasTop` | 16 | MLS, Liga MX, Brasileirão, Argentine Primera, Libertadores, Sudamericana and more |
| `asiaTop` | 7 | J.League, Saudi Pro League, Chinese Super League, Indian Super League, A-League, AFC Champions League |
| `africaTop` | 4 | AFCON, CAF Champions League, CAF Confederation Cup, South African Premiership |
| `internationalMen` | 15 | World Cup and qualifiers, Euros, Copa América, Gold Cup, AFCON, Asian Cup, friendlies |
| `womens` | 39 | Every women's competition |
| `uefa`, `conmebol`, `concacaf`, `afc`, `caf` | 86 / 38 / 32 / 18 / 8 | Every competition of that confederation |
| `all` | 219 | Every competition |

#### Input examples

**Today's matches in the top five European leagues**

```json
{
  "leagueGroups": ["top5"],
  "dateMode": "today",
  "timezone": "Europe/London"
}
```

**A full Premier League season with every goal**

```json
{
  "leagues": ["eng.1"],
  "dateMode": "season",
  "seasonYear": 2025,
  "timezone": "Europe/London"
}
```

**One club in every competition, next 30 days**

```json
{
  "countries": ["eng"],
  "leagues": ["uefa.champions"],
  "dateMode": "next30Days",
  "teams": ["liverpool"],
  "timezone": "Europe/London"
}
```

**Live scores from every league**

```json
{
  "leagueGroups": ["all"],
  "dateMode": "today",
  "liveOnly": true
}
```

**Upcoming fixtures with betting odds**

```json
{
  "leagueGroups": ["top5", "uefaClub"],
  "dateMode": "next7Days",
  "matchStatus": ["pre"],
  "includeOdds": true
}
```

**High-scoring matches from the last 30 days**

```json
{
  "leagueGroups": ["europeTop"],
  "dateMode": "last30Days",
  "minGoals": 5
}
```

**A player's goals and cards in one season**

```json
{
  "leagues": ["eng.1", "uefa.champions"],
  "dateMode": "season",
  "seasonYear": 2025,
  "players": ["haaland"]
}
```

### Output

You get one row per match. The **Output** tab has four table views: **All Fixtures**, **Results**, **Upcoming Fixtures** and **Goals & Cards**. Every run also saves a **Run Summary**.

```json
{
  "matchId": "401884790",
  "sport": "soccer",
  "league": "ger.1",
  "leagueName": "German Bundesliga",
  "leagueShortName": "Bundesliga",
  "leagueCode": null,
  "country": "Germany",
  "confederation": "UEFA",
  "season": {
    "year": 2026,
    "displayName": "2026-27 German Bundesliga",
    "slug": "2026-27-german-bundesliga"
  },
  "date": "2026-09-18T18:30Z",
  "dateLocal": "2026-09-18T19:30:00.000+01:00",
  "dayLocal": "2026-09-18",
  "name": "1. FC Union Berlin at Bayern Munich",
  "shortName": "FCU @ MUN",
  "status": {
    "state": "post",
    "name": "STATUS_FULL_TIME",
    "completed": true,
    "description": "Full Time",
    "detail": "FT",
    "clock": 5400,
    "displayClock": "90'+3'",
    "period": 2,
    "decidedBy": "regulation",
    "isPostponed": false,
    "isCanceled": false,
    "isAbandoned": false,
    "playedOut": true
  },
  "result": "home",
  "winner": "Bayern Munich",
  "scoreline": "7-0",
  "homeTeam": {
    "id": "132",
    "name": "Bayern Munich",
    "shortName": "Bayern",
    "abbreviation": "MUN",
    "logo": "https://a.espncdn.com/i/teamlogos/soccer/500/132.png",
    "score": 7,
    "aggregateScore": null,
    "shootoutScore": null,
    "form": "WWWDW",
    "record": "3-1-0",
    "advanced": null
  },
  "awayTeam": {
    "id": "598",
    "name": "1. FC Union Berlin",
    "shortName": "Union Berlin",
    "abbreviation": "FCU",
    "logo": "https://a.espncdn.com/i/teamlogos/soccer/500/598.png",
    "score": 0,
    "form": "LLLDW",
    "record": "0-1-3"
  },
  "venue": {
    "id": "1935",
    "name": "Allianz Arena",
    "city": "München",
    "country": "Germany"
  },
  "attendance": 75000,
  "leg": null,
  "notes": [],
  "broadcasts": ["Fandango"],
  "headline": "Michael Olise scored his first Bayern Munich hat trick as the German champions romped to a 7-0 demolition of visiting Union Berlin.",
  "url": "https://www.espn.com/soccer/match/_/gameId/401884790",
  "retrievedAt": "2026-09-22T14:25:51.787Z",
  "matchEvents": [
    {
      "type": "Goal",
      "minute": "18'",
      "teamSide": "home",
      "playerName": "Jamal Musiala",
      "isGoal": true,
      "isOwnGoal": false,
      "isPenalty": false,
      "isYellowCard": false,
      "isRedCard": false
    },
    {
      "type": "Penalty - Scored",
      "minute": "39'",
      "teamSide": "home",
      "playerName": "Harry Kane",
      "isGoal": true,
      "isPenalty": true
    }
  ]
}
```

With **Include Betting Odds** on, each row also has an `odds` object:

```json
{
  "odds": {
    "provider": "DraftKings",
    "details": "MNC +135",
    "overUnder": 2.5,
    "homeMoneyline": "+175",
    "awayMoneyline": "+135",
    "drawMoneyline": "+260",
    "overOdds": "-175",
    "underOdds": "+130",
    "homeSpread": "+0.5",
    "homeSpreadOdds": "-190",
    "awaySpreadOdds": "+125"
  }
}
```

Odds are American odds. When there is both an opening and a closing price, you get the closing price.

#### Main output fields

| Field | Description |
|-------|-------------|
| `league`, `leagueName`, `country`, `confederation` | The competition |
| `season` | Season year and name, such as `2026-27 German Bundesliga` |
| `date`, `dateLocal`, `dayLocal` | Kick-off in UTC, kick-off in your timezone, and the calendar day in your timezone |
| `status.state` | `pre` (scheduled), `in` (in play) or `post` (finished) |
| `status.displayClock`, `status.period` | The match clock and the half, for live matches |
| `result` | `home`, `away`, `draw`, or `null` if the match has no result yet |
| `winner` | The name of the winning team. `null` for a draw |
| `scoreline` | The score, home team first, such as `"2-1"` |
| `status.decidedBy` | `regulation`, `extraTime` or `penalties` |
| `status.playedOut` | `false` for postponed, cancelled and abandoned matches |
| `homeTeam`, `awayTeam` | Name, abbreviation, logo, score, form (last five results, newest first) and season record (wins-draws-losses) |
| `venue`, `attendance`, `broadcasts` | Stadium, crowd and TV channels |
| `headline`, `url` | Match report headline and a link to the match page |
| `matchEvents` | Goals and cards, with the minute, player and team |
| `teamStats` | Possession, shots, shots on target, corners and fouls, for each team |
| `odds` | Moneyline, total and spread |
| `retrievedAt` | When the data was collected. The same value for every row of one run |

#### Results after extra time and penalties

A match that is level after extra time is a **draw** in `result`, whoever wins the shootout. The shootout score is in `homeTeam.shootoutScore` and `awayTeam.shootoutScore`, and `advanced` shows which team went through.

#### Two-legged ties

`leg` is `1` or `2`. `aggregateScore` on each team is the aggregate score, and `advanced` shows which team went through. `result` is always the result of the single match, not of the tie.

### Use the scraper with the Apify API

You can run the scraper and read the results from any programming language with the [Apify API](https://docs.apify.com/api/v2). Get your API token in Apify Console under **Settings → API & Integrations**, and replace `<YOUR_API_TOKEN>` below.

**JavaScript / Node.js**

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

const client = new ApifyClient({ token: '<YOUR_API_TOKEN>' });

const run = await client.actor('hgservices/soccer-fixtures-scraper').call({
    leagueGroups: ['top5'],
    dateMode: 'next7Days',
    timezone: 'Europe/London',
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const match of items) {
    console.log(match.dateLocal, match.homeTeam.name, 'v', match.awayTeam.name);
}
```

**Python** (`apify-client` 3.0 or later)

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_API_TOKEN>")

run = client.actor("hgservices/soccer-fixtures-scraper").call(run_input={
    "leagues": ["eng.1"],
    "dateMode": "season",
    "seasonYear": 2025,
})
if run is None:
    raise RuntimeError("The run was not found.")

for match in client.dataset(run.default_dataset_id).iterate_items():
    print(match["dayLocal"], match["name"], match["scoreline"])
```

**cURL** — run the scraper and get the results in one call:

```bash
curl -X POST "https://api.apify.com/v2/acts/hgservices~soccer-fixtures-scraper/run-sync-get-dataset-items?format=json" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "leagues": ["eng.1", "esp.1"], "dateMode": "thisWeekend", "timezone": "Europe/London" }'
```

Change `format=json` to `format=csv` or `format=xlsx` to get a spreadsheet. The one-call endpoint waits up to 300 seconds. For a very large run, start it with `POST /v2/acts/hgservices~soccer-fixtures-scraper/runs`, and read the dataset when the run finishes, or use a webhook.

### Use soccer data in Claude, ChatGPT and other AI assistants

This scraper works as a tool for AI assistants through the [Apify MCP server](https://mcp.apify.com/). Your assistant can find the scraper, read its input options, run it, and use the match data in its answer.

**Claude (claude.ai or Claude Desktop)** — Go to **Settings → Connectors**, add a custom connector, and enter `https://mcp.apify.com`. Sign in to Apify when Claude asks.

**Claude Code**

```bash
claude mcp add --transport http apify https://mcp.apify.com
```

**ChatGPT** — Turn on **Developer mode** in **Settings → Apps & Connectors → Advanced settings**. Then create a connector with the MCP server URL `https://mcp.apify.com`.

**Cursor, VS Code and other MCP clients** — Add `https://mcp.apify.com` as a remote MCP server. To give the assistant only this scraper, use `https://mcp.apify.com?tools=hgservices/soccer-fixtures-scraper`.

Then ask in plain language:

> Use the Soccer Fixtures Scraper to list this weekend's Premier League and LaLiga matches with kick-off times in New York time.

> Get Arsenal's results in all competitions this season and tell me their home and away record.

> Which Serie A matches in the last 30 days had five or more goals, and who scored?

For the best results, tell the assistant the league, the dates and your timezone. This keeps the run fast and the cost low.

### Integrations and scheduling

Connect the scraper to the tools you already use with [Apify integrations](https://apify.com/integrations): **Google Sheets, Slack, Zapier, Make, n8n, Airbyte, Keboola, GitHub** and more. You can also use **webhooks** to call your own endpoint when a run finishes.

Use **Schedules** in Apify Console to run the scraper automatically:

| Use case | Cron | Input |
|----------|------|-------|
| Tomorrow's fixtures, every morning | `0 6 * * *` | `dateMode: tomorrow` |
| Weekend results, every Sunday night | `0 23 * * 0` | `dateMode: thisWeekend`, `matchStatus: ["post"]` |
| Live scores, every 5 minutes | `*/5 * * * *` | `liveOnly: true` |
| Next week's fixtures with odds, every Monday | `0 9 * * 1` | `dateMode: next7Days`, `includeOdds: true` |
| Season archive, every July | `0 3 1 7 *` | `dateMode: season` |

### Run summary

Every run saves a `SUMMARY` record in the key-value store. It tells you how many matches the run found, how many are scheduled, live or finished, and which leagues had no matches in your dates.

```json
{
  "totalMatches": 1304,
  "scheduled": 0,
  "inPlay": 0,
  "finished": 1304,
  "matchesBeforeFilters": 1304,
  "leaguesRequested": 3,
  "leaguesWithMatches": 3,
  "emptyLeaguesCount": 0,
  "emptyLeagues": [],
  "dateMode": "season",
  "window": { "season": 2025 },
  "timezone": "Europe/London",
  "retrievedAt": "2026-09-22T14:26:47.022Z"
}
```

### How much does it cost to scrape soccer fixtures?

See the **Pricing** tab for the current price. Every Apify account gets free monthly platform credit, which is enough to try the scraper on real matches.

To keep the cost low:

- Select only the leagues you need, or use a small **League Group** instead of `all`.
- Use the shortest date range that gives you the data.
- Set **Maximum Fixtures** to limit the number of rows.

The default memory of 512 MB is enough for most runs, including a full season of 20 leagues. A run over all 219 competitions for a whole season returns more than 30,000 rows and takes about 20 minutes. For a run of that size, set **Memory** to 1024 MB in the run options.

### Data notes

- **No substitutions, line-ups or assists.** The match timeline has goals and cards only.
- **Shootout kicks are not in the timeline.** Read the shootout from each team's `shootoutScore`.
- **Odds are not available for every match.** Odds are mostly available for upcoming matches in the larger leagues. Other rows have `odds: null`.
- **Team statistics start at kick-off.** Scheduled matches have no `teamStats`, and the set of statistics changes from league to league.
- **Lower divisions have less detail.** Attendance, venue, TV channels and headlines are less common below the top division.
- **Some tournaments are not played every year.** World Cup qualifiers, the Olympics and the Copa América have matches only in their own years. A run for another year returns no rows for them.

### FAQ

**Do I need an API key or an account on a sports website?**
No. You need only an Apify account.

**How far back can I get results?**
Many leagues have results for many past seasons. Use `dateMode: season` with a `seasonYear`, or a `range` of up to 400 days.

**Why did my run return no rows?**
Usually there were no matches in your dates, for example during an international break or the off-season, or your filters matched nothing. The run log and the `SUMMARY` record show the leagues with no matches.

**Can I get live scores?**
Yes. Set `dateMode` to `today` and turn on **In-Play Only**. Schedule the run every few minutes for a live feed.

**What does "today" mean?**
Today in the **Output Timezone** you choose. A match at 02:00 in Tokyo is on a different day in London, and the scraper puts it on the correct day for your timezone.

**Can I get fixtures for one team only?**
Yes. Put the club name in **Team Filter**, for example `real madrid`. Add the club's country in **Countries** and its European competition in **Leagues** to get every match it plays. A name also matches the club's women's and youth teams, for example "Liverpool" also finds Liverpool Women and Liverpool U21. To get only one team, select only the leagues it plays in.

**Can I combine this data with other sports data?**
Yes. The [ESPN Sports Scores & Schedules](https://apify.com/hgservices/apify-actor-espn) scraper covers the NFL, NBA, MLB, NHL and college sports. The `league`, `team` and `player` fields have the same names in both datasets. `leagueCode` (`epl`, `laliga`, `ucl`, `mls`) is the same key that scraper uses for those competitions.

**Is it legal to scrape soccer fixtures and results?**
This scraper collects only public match information and never signs in. You are responsible for how you use the data, and for the terms of use of the data source.

### Related scrapers

- [ESPN Sports Scores & Schedules](https://apify.com/hgservices/apify-actor-espn) — scores and schedules for the NFL, NBA, MLB, NHL, college sports and more.

### Support

Did you find a bug, or do you need a field or a competition that is not here? Open an issue on the **Issues** tab. Custom solutions are available on request.

*This scraper uses public data from ESPN. It is not affiliated with, endorsed by, or sponsored by ESPN.*

# Actor input Schema

## `leagues` (type: `array`):

Competitions to scrape. The list holds all 219 competitions — type a name to search it. This field adds together with League Groups and Countries.

## `leagueGroups` (type: `array`):

Named bundles of leagues, added to the Leagues above. "all" is every one of the 219 competitions.

## `countries` (type: `array`):

Add every competition of a country, by name or by code. For example, England or eng adds the Premier League, the Championship, the FA Cup and the WSL. Codes include eng, esp, ita, ger, fra, ned, por, sco, bel, tur, bra, arg, mex, usa, jpn, ksa.

## `dateMode` (type: `string`):

Which dates to cover. Days are counted in the Output Timezone below, so a Saturday means your Saturday.

## `date` (type: `string`):

Used by the "A single date" mode. Format YYYYMMDD or YYYY-MM-DD, for example 2026-09-20. Defaults to today.

## `startDate` (type: `string`):

Used by the "A date range" mode. Format YYYYMMDD or YYYY-MM-DD. Defaults to today.

## `endDate` (type: `string`):

Used by the "A date range" mode. Format YYYYMMDD or YYYY-MM-DD. Defaults to today plus six days. A range is capped at 400 days.

## `seasonYear` (type: `integer`):

Used by the "A whole season" mode. Give the year the season starts in: 2025 means 2025-26 for the Premier League and the 2025 calendar year for Brazil or MLS. Leagues on different calendars can go in the same run. Defaults to the current season.

## `teams` (type: `array`):

Only return fixtures involving these teams. A term matches a team ID or an abbreviation exactly, or any part of a club name — "liverpool", "LIV" and "364" all find the same club. Use full names across many leagues, because abbreviations repeat between countries.

## `homeAwayFilter` (type: `string`):

Narrow the Team Filter to home or away fixtures. Ignored when no team is named.

## `matchStatus` (type: `array`):

Keep only fixtures in these states. Leave empty for all three.

## `results` (type: `array`):

Keep only finished matches with these outcomes. This drops every fixture that has not been played. A match level after extra time counts as a draw, whoever won the shootout.

## `liveOnly` (type: `boolean`):

Keep only matches being played right now.

## `startingWithinHours` (type: `integer`):

Keep scheduled matches starting within this many hours. In-play and finished matches are not affected.

## `minGoals` (type: `integer`):

Keep only matches with at least this many goals in total. Drops fixtures with no score yet.

## `players` (type: `array`):

Keep only matches in which one of these players scored or was booked. Case insensitive, partial match. Needs Include Goals & Cards switched on, because that is the data it reads.

## `includeMatchEvents` (type: `boolean`):

Add the goal and card timeline to every row: minute, scorer, and whether it was a penalty, an own goal, a yellow or a red. Substitutions and assists are not included.

## `includeTeamStats` (type: `boolean`):

Add possession, shots, shots on target, corners and fouls for each side. Published only for matches that have kicked off, and not by every league.

## `includeOdds` (type: `boolean`):

Add the moneyline, the total and the spread where a price is available. Mostly available for upcoming fixtures in the larger leagues; absent from most finished matches.

## `maxMatches` (type: `integer`):

Stop after this many rows, counted after filtering and sorting by kick-off. Leave empty for all of them.

## `timezone` (type: `string`):

IANA timezone, for example Europe/London, America/New_York or Asia/Tokyo. It sets dateLocal and dayLocal, and it decides which calendar day each match belongs to. Defaults to UTC.

## Actor input object example

```json
{
  "leagues": [
    "eng.1",
    "esp.1",
    "ita.1",
    "ger.1",
    "fra.1",
    "usa.1",
    "arg.1"
  ],
  "leagueGroups": [],
  "countries": [],
  "dateMode": "next7Days",
  "teams": [],
  "homeAwayFilter": "all",
  "matchStatus": [],
  "results": [],
  "liveOnly": false,
  "players": [],
  "includeMatchEvents": true,
  "includeTeamStats": false,
  "includeOdds": false,
  "timezone": "Europe/London"
}
```

# Actor output Schema

## `allFixtures` (type: `string`):

No description

## `results` (type: `string`):

No description

## `upcoming` (type: `string`):

No description

## `goalsAndCards` (type: `string`):

No description

## `summary` (type: `string`):

No description

# 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 = {
    "leagues": [
        "eng.1",
        "esp.1",
        "ita.1",
        "ger.1",
        "fra.1",
        "usa.1",
        "arg.1"
    ],
    "dateMode": "next7Days",
    "timezone": "Europe/London"
};

// Run the Actor and wait for it to finish
const run = await client.actor("hgservices/soccer-fixtures-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 = {
    "leagues": [
        "eng.1",
        "esp.1",
        "ita.1",
        "ger.1",
        "fra.1",
        "usa.1",
        "arg.1",
    ],
    "dateMode": "next7Days",
    "timezone": "Europe/London",
}

# Run the Actor and wait for it to finish
run = client.actor("hgservices/soccer-fixtures-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 '{
  "leagues": [
    "eng.1",
    "esp.1",
    "ita.1",
    "ger.1",
    "fra.1",
    "usa.1",
    "arg.1"
  ],
  "dateMode": "next7Days",
  "timezone": "Europe/London"
}' |
apify call hgservices/soccer-fixtures-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,hgservices/soccer-fixtures-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/TaTbfem0Wwf7kHycL/builds/2VZcu7bwKWJV1vT9j/openapi.json