# World Cup Results & Tables (`trovevault/world-cup-results-tables`) Actor

Extracts World Cup fixtures, results, scores, teams, groups, venues, and tables. Export data, run via API, schedule and monitor runs, or integrate with other tools.

- **URL**: https://apify.com/trovevault/world-cup-results-tables.md
- **Developed by:** [Trove Vault](https://apify.com/trovevault) (community)
- **Categories:** News, Other, Automation
- **Stats:** 72 total users, 31 monthly users, 100.0% runs succeeded, 2 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.85 / 1,000 match or standings

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/platform/actors/running/actors-in-store#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

### What does World Cup Results & Tables do?

World Cup Results & Tables returns structured **FIFA World Cup fixtures, results, scores, venues, groups, and calculated group tables** for supported tournaments.

The actor is built for lightweight World Cup dashboards, spreadsheets, reporting feeds, scheduled tournament monitoring, and API workflows that need clean rows instead of manually checking football pages during the tournament.

The default tournament is **World Cup 2026**, hosted by Canada, Mexico, and the United States. Recent validated tournaments are also available for comparison and testing.

### Why use World Cup Results & Tables?

Use this actor when you need World Cup match data in a consistent Apify dataset. It normalizes match rows and keeps group tables in a separate output table so downstream workflows can distinguish fixtures/results from standings.

Main capabilities:

- Retrieve World Cup fixtures, dates, teams, venues, scores, stage, group, and winners.
- Filter by tournament year, stage, group, and team.
- Show only completed games when you want results without upcoming fixtures.
- Calculate group standings from completed group-stage results.
- Schedule repeat runs during the tournament and export data through the Apify API.
- Append rows into an existing Apify dataset with `datasetId`.
- Add your own workflow identifier with `runId`.

### What data can it extract?

#### Match rows

| Field | Type | Description |
|---|---:|---|
| `tournamentName` | string | World Cup tournament name |
| `year` | number | Tournament year |
| `stage` | string | `group` or `knockout` |
| `round` | string | Matchday or knockout-round label |
| `group`, `groupName` | string | Group label when available |
| `matchDate` | string | ISO 8601 date/time when safely normalized |
| `localDate`, `localTime` | string | Local date and time when available |
| `venue` | string | Stadium and city when available |
| `homeTeam`, `awayTeam` | string | Teams for the match row |
| `homeScore`, `awayScore` | number | Full-time score when available |
| `halfTimeHomeScore`, `halfTimeAwayScore` | number | Half-time score when available |
| `extraTimeHomeScore`, `extraTimeAwayScore` | number | Extra-time score when available |
| `penaltyHomeScore`, `penaltyAwayScore` | number | Penalty shootout score when available |
| `status` | string | `scheduled` or `finished` |
| `winner` | string | `home`, `away`, `draw`, or empty |
| `runId` | string | Optional workflow identifier |

#### Group table rows

| Field | Type | Description |
|---|---:|---|
| `tournamentName` | string | World Cup tournament name |
| `year` | number | Tournament year |
| `group`, `groupName` | string | World Cup group |
| `position` | number | Calculated group position |
| `teamName` | string | Team name |
| `played`, `won`, `drawn`, `lost` | number | Group-stage record |
| `goalsFor`, `goalsAgainst` | number | Group-stage goals |
| `goalDifference` | number | Goals for minus goals against |
| `points` | number | Calculated points |
| `runId` | string | Optional workflow identifier |

### Supported tournaments

This version supports validated tournament records for:

- World Cup 2018
- World Cup 2022
- World Cup 2026

The actor does not claim full historical World Cup coverage in this launch version. Additional years can be added after their tournament files and output semantics are validated.

### Use cases

- Build World Cup 2026 dashboards and score trackers.
- Feed editorial tools with structured fixtures and results.
- Keep spreadsheets of World Cup matches and group tables.
- Schedule daily tournament updates through Apify.
- Monitor specific teams during the group stage and knockout rounds.
- Compare recent World Cups using the same output schema.

### How to use it

1. Open the actor input tab.
2. Choose the World Cup year.
3. Pick a stage: all stages, group stage, or knockout stage.
4. Optionally select a group or enter a team filter.
5. Keep Include Matches enabled for fixtures and scores.
6. Enable Completed Games Only when you want finished results without scheduled fixtures.
7. Keep Include Group Tables enabled when you want calculated standings.
8. Run the actor and download the Matches and Group Tables outputs as JSON, CSV, Excel, XML, or HTML.

### Input

See the input tab for full configuration options.

Example input:

```json
{
  "year": 2026,
  "stage": "all",
  "group": "all",
  "includeMatches": true,
  "includeGroupTables": true,
  "completedOnly": false,
  "maxMatches": 104
}
```

Example team-specific input:

```json
{
  "year": 2026,
  "stage": "all",
  "team": "Portugal",
  "includeMatches": true,
  "includeGroupTables": true,
  "completedOnly": true,
  "maxMatches": 20
}
```

### Output

The actor creates two output tables:

- **Matches**: fixtures and results from the selected tournament scope.
- **Group Tables**: calculated group standings from completed group-stage matches.

Example output:

```json
[
  {
    "tournamentName": "World Cup 2022",
    "year": 2022,
    "stage": "group",
    "round": "Matchday 1",
    "group": "Group A",
    "groupName": "Group A",
    "matchDate": "2022-11-20T00:00:00.000Z",
    "localDate": "2022-11-20",
    "localTime": "19:00 UTC+3",
    "venue": "Al Bayt Stadium, Al Khor",
    "homeTeam": "Qatar",
    "awayTeam": "Ecuador",
    "homeScore": 0,
    "awayScore": 2,
    "halfTimeHomeScore": 0,
    "halfTimeAwayScore": 2,
    "extraTimeHomeScore": null,
    "extraTimeAwayScore": null,
    "penaltyHomeScore": null,
    "penaltyAwayScore": null,
    "status": "finished",
    "winner": "away"
  },
  {
    "tournamentName": "World Cup 2022",
    "year": 2022,
    "stage": "group",
    "group": "Group A",
    "groupName": "Group A",
    "position": 1,
    "teamName": "Netherlands",
    "played": 3,
    "won": 2,
    "drawn": 1,
    "lost": 0,
    "goalsFor": 5,
    "goalsAgainst": 1,
    "goalDifference": 4,
    "points": 7
  }
]
```

### API usage example

```bash
curl "https://api.apify.com/v2/acts/trovevault~world-cup-results-tables/runs?waitForFinish=120" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 2026,
    "stage": "all",
    "group": "all",
    "includeMatches": true,
    "includeGroupTables": true,
    "completedOnly": false,
    "maxMatches": 104
  }'
```

### Data semantics

Group tables are calculated only from completed matches that have a `group` value and a full-time score. Knockout matches never affect group tables.

For scheduled tournament monitoring, a match can remain `scheduled` until public records add a full-time score. The actor does not infer live scores from unofficial feeds.

When `completedOnly` is enabled, match rows exclude scheduled fixtures and return only games with full-time scores. Group tables already use completed group-stage matches regardless of this setting.

When appending both output types to an external `datasetId`, the actor adds `entityType` as `match` or `groupTable` so downstream systems can split the rows.

### Limitations

This actor uses public tournament records that are normalized into Apify-ready match and table rows. It is not an official FIFA live data feed.

World Cup 2026 fixtures, group labels, venues, and results depend on public records being updated. During the tournament, recent results can lag until those records change.

This version does not include player-level stats, scorers, cards, substitutions, odds, squads, rankings, or live minute-by-minute data. Historical coverage is limited to the supported years listed above.

### FAQ

#### Does this actor cover World Cup 2026?

Yes. World Cup 2026 is the default input and the primary launch use case.

#### Does it include every World Cup ever played?

No. This launch version supports 2018, 2022, and 2026 because those years have validated coverage for this actor.

#### Are group tables official?

No. Group tables are calculated from completed full-time results in the normalized tournament records. They are useful for dashboards and exports, but official standings should be checked with FIFA when required.

#### Can I monitor one team?

Yes. Fill the Team Filter field, for example `Portugal`, `Brazil`, or `United States`.

#### Can I get only knockout matches?

Yes. Set Stage to Knockout stage. Group tables are still based only on completed group matches if Include Group Tables is enabled.

#### Is this suitable for spreadsheets?

Yes. Matches and group tables are flat outputs and export cleanly to CSV or Excel.

### Troubleshooting

If a run returns fewer rows than expected, check the selected year, stage, group, team filter, Completed Games Only setting, and `maxMatches` value first.

If 2026 results are still empty before matches are played, that is expected. Fixtures can be present while scores and calculated group tables remain incomplete.

For bugs, missing supported years, or output issues, use the Issues tab on the actor page.

### Related actors

For domestic football workflows, see Spain Football Results & Tables, Italy Football Results & Tables, France Football Results & Tables, and Turkey Football Results & Tables.

### Changelog

#### 0.1

Initial version with supported World Cup fixtures, results, filters, and calculated group tables for 2018, 2022, and 2026.

# Actor input Schema

## `year` (type: `string`):

World Cup tournament year to retrieve. The default is 2026 for the Canada, Mexico, and USA tournament. Earlier supported tournaments are included for historical dashboards and comparisons.

## `stage` (type: `string`):

Tournament stage to return. Use all for the full tournament, group for group-stage matches and tables, or knockout for knockout-round match rows only.

## `group` (type: `string`):

Optional group filter. Leave as all to include every group. Group tables are calculated only from completed group matches.

## `team` (type: `string`):

Optional team name filter. When filled, match rows include only games where either team contains this text. Leave blank for the full selected tournament scope.

## `includeMatches` (type: `boolean`):

Whether to return match rows with dates, teams, venues, scores, stage, group, status, and winner.

## `includeGroupTables` (type: `boolean`):

Whether to calculate and return group standings from completed group-stage matches. Knockout matches never affect group tables.

## `completedOnly` (type: `boolean`):

When enabled, match rows include only games that already have a full-time score. Group tables are always calculated from completed group-stage matches.

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

Maximum match rows to return after filters. Use a small value for test runs and scheduled checks, or a larger value for full-tournament exports.

## `datasetId` (type: `string`):

ID of an existing Apify dataset to append results to, in addition to the default Matches and Group Tables outputs. Use this when chaining scheduled World Cup updates into a long-lived dashboard dataset.

## `runId` (type: `string`):

ID of an existing Apify actor run or workflow step to associate with output rows. The actor copies this value into each row when provided.

## Actor input object example

```json
{
  "year": "2026",
  "stage": "all",
  "group": "all",
  "includeMatches": true,
  "includeGroupTables": true,
  "completedOnly": false,
  "maxMatches": 104
}
```

# Actor output Schema

## `matches` (type: `string`):

No description

## `standings` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("trovevault/world-cup-results-tables").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("trovevault/world-cup-results-tables").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{}' |
apify call trovevault/world-cup-results-tables --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=trovevault/world-cup-results-tables",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/BM6uHE6W5kbe9EzJl/builds/32rGsg2zmpAqoffyf/openapi.json