# Football-Data.org Competitions Catalog (`automation-lab/football-data-org-competitions`) Actor

Export Football-Data.org competition identity, area and current-season catalog records for recurring reference-data synchronization.

- **URL**: https://apify.com/automation-lab/football-data-org-competitions.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 $4.94 / 1,000 competition exporteds

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

## Football-Data.org Competitions Catalog

Synchronize your football competition reference catalog with **football-data.org competitions**. Export stable competition IDs, names, codes, areas and current-season metadata as flat rows for spreadsheets and sports-data pipelines.

This Actor reads the anonymous Football-Data.org competition list. It does **not** fetch matches, teams, players, standings or historical season details. No Football-Data.org account or API key is required.

### Who is this for?

- Sports-data engineers maintaining competition lookup tables.
- Analysts joining competition IDs to separately licensed datasets.
- Editors refreshing league names, area labels and season dates.
- Application developers keeping competition selectors up to date.

### Why use this Actor?

Get an automation-ready dataset without maintaining a request script, normalization code or scheduled export job. Each run produces one row per unique matching competition, with a source URL and extraction timestamp.

The catalog-only scope keeps the workflow predictable: one public source, no protected detail endpoint requests, exact client-side filters, and no browser or proxy setup. It is not a replacement for a licensed football results feed.

### Quick start

1. Leave the filters empty to request the complete current catalog.
2. Keep `maxItems` at `0` to export every matching catalog entry.
3. Start the Actor and wait for completion.
4. Open the default dataset to inspect the rows.
5. Download JSON, CSV, Excel or another format supported by Apify.
6. Schedule future runs if your reference table needs regular refreshes.

Default input:

```json
{
  "competitionIds": [],
  "competitionCodes": [],
  "areaCodes": [],
  "maxItems": 0
}
```

### What data is extracted?

| Fields | Meaning |
| --- | --- |
| `competitionId`, `name`, `code`, `type` | Competition identity and classification |
| `emblem`, `plan` | Source image URL and source subscription-tier label |
| `areaId`, `areaName`, `areaCode`, `areaFlag` | Area identity and flag URL |
| `currentSeasonId` | Source current-season identifier |
| `seasonStartDate`, `seasonEndDate` | Current-season dates |
| `currentMatchday` | Current-season matchday if supplied |
| `numberOfAvailableSeasons` | Source-reported count, not exported history |
| `lastUpdated` | Source competition update timestamp |
| `sourceUrl` | Public catalog endpoint used |
| `scrapedAt` | Extraction time in UTC |

Optional source fields may be null. The `plan` field is descriptive source metadata: it neither grants access nor means this Actor retrieves paid resources. Emblem and flag URLs are exported as references; image files are not downloaded.

### Input parameters

| Parameter | Default | Behavior |
| --- | --- | --- |
| `competitionIds` | `[]` | ANY exact positive integer ID |
| `competitionCodes` | `[]` | ANY exact whole competition code |
| `areaCodes` | `[]` | ANY exact whole source area code |
| `maxItems` | `0` | Global unique row limit after filtering; 0 means all current matches |

Codes are case-insensitive and surrounding whitespace is trimmed. Empty or omitted arrays do not filter. Different filter groups use **AND**, not OR. For example, an ID filter and code filter must both match the same competition. Strings are not converted to numeric IDs.

Area codes are source labels, not guaranteed ISO country codes. There are no URL inputs, keyword searches, pagination controls, authentication inputs or proxy options. Unknown input fields and malformed values fail explicitly.

### Filter examples

Select two competition codes:

```json
{
  "competitionCodes": ["PL", "BL1"],
  "maxItems": 0
}
```

Select only England-area entries, up to five rows in source order:

```json
{
  "areaCodes": ["ENG"],
  "maxItems": 5
}
```

Select one source ID:

```json
{
  "competitionIds": [2021]
}
```

Filters are applied locally after downloading the catalog. They reduce exported rows and item charges, not the upstream catalog request size. A valid filter with no matching entry returns an empty dataset; it does not broaden the scope silently.

### Output example

A representative normalized Premier League row contains these fields. Season values change as the source updates:

```json
{
  "competitionId": 2021,
  "name": "Premier League",
  "code": "PL",
  "type": "LEAGUE",
  "areaId": 2072,
  "areaName": "England",
  "areaCode": "ENG",
  "sourceUrl": "https://api.football-data.org/v4/competitions"
}
```

The full row also contains the optional fields listed above and `scrapedAt`. Primary results are always in the run's default dataset, making standard dataset integrations straightforward. This Actor does not write to a shared global dataset.

### How much does it cost to export Football-Data.org competitions?

Billing uses pay-per-event: one **start** fee of **$0.005 per run**, plus an **item** charge for every saved competition. At the BRONZE rate, each item costs **$0.008232**. Final prices are shown in the Actor pricing panel and may vary by plan tier.

For example, at that BRONZE rate:

- 1 saved competition: $0.013232 total.
- 10 saved competitions: $0.08732 total.
- 100 saved competitions: $0.8282 total.

A valid no-match run has a start fee but no item charge. Rejected and duplicate records are not charged as items. A run may fail after its start fee; consult the log before retrying. Apify platform fees or subscription conditions are separate from these Actor-event examples.

### Limits and reliability

The public catalog returned 190 competition entries during development. That is a snapshot, not a guaranteed future count. Coverage, optional fields, ordering and update cadence are controlled by Football-Data.org.

`maxItems` supports integers from 0 through 10000. A positive limit truncates matching unique rows in source order. Zero does not unlock protected records or promise unlimited coverage. There are no historical snapshots, change detection, alerts or built-in cross-run reconciliation.

Each catalog request has a 30-second timeout. Network failures, rate limits and server errors receive at most three total attempts with bounded backoff. Permanent HTTP errors, invalid JSON, an empty upstream catalog or a malformed catalog fail rather than masquerading as a successful empty query. No protected resource fallback is attempted.

An Apify charge limit may stop output early. Treat an interrupted or failed run as potentially partial and inspect its logs before using it as a complete replacement snapshot.

### Integrations

Use Apify schedules for periodic catalog snapshots. In your downstream database, upsert by `competitionId`, keep `scrapedAt`, and compare snapshots if you need change tracking. Avoid deleting old database rows based on a failed run or a deliberately limited export.

Send dataset rows to Google Sheets for a reference table, to an ETL job for warehouse joins, or through Make, Zapier and Apify webhooks after successful runs. These are integration patterns, not built-in connectors or alerts provided by this Actor.

### API usage

Start one run through the Apify API; retain the returned run ID and dataset ID:

```bash
curl -X POST \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  'https://api.apify.com/v2/acts/automation-lab~football-data-org-competitions/runs' \
  -d '{"competitionCodes":["PL"],"maxItems":1}'
```

JavaScript with `apify-client`:

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/football-data-org-competitions')
  .call({ competitionCodes: ['PL'], maxItems: 1 });
if (run.status !== 'SUCCEEDED') throw new Error(run.status);
const { items } = await client.dataset(run.defaultDatasetId).listItems({ limit: 20 });
console.log(items);
```

Python with `apify-client`:

```python
import os
from apify_client import ApifyClient
client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/football-data-org-competitions').call(
    run_input={'competitionCodes': ['PL'], 'maxItems': 1})
if run['status'] != 'SUCCEEDED':
    raise RuntimeError(run['status'])
print(client.dataset(run['defaultDatasetId']).list_items(limit=20).items)
```

### MCP use

Select this Actor explicitly rather than a growing default tool group:

```bash
claude mcp add --transport http apify \
  'https://mcp.apify.com?tools=automation-lab/football-data-org-competitions'
```

Equivalent configuration for Claude Desktop, Cursor and VS Code clients with HTTP MCP support:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/football-data-org-competitions"
    }
  }
}
```

Authenticate using your client's supported Apify authorization flow. Example prompts: “Export the Football-Data.org competition catalog for area ENG, then show the IDs, names and current-season dates.” Actor selection also exposes run and storage helpers, not exactly one tool. Discover actual names and argument schemas with scoped `tools/list`.

For an authorized invocation, start once and follow that same run. A run ID is metadata, not rows. `call-actor` can wait 0–45 seconds (default 30). If still running, check the same run using bounded backoff, for example 2, 4 and 8 seconds capped at 10, with a 120-second total deadline. Set client timeouts above the chosen server wait plus transport margin. After a client timeout recover the known run rather than launching a duplicate; if the ID is unknown, report uncertainty. At the deadline report pending and stop.

After success, read `get-dataset-items` in pages of 20 using explicit offsets and needed fields. A reasonable consumer budget is 100 source rows or 64 KiB of serialized UTF-8 result content, whichever comes first. Enforce that byte ceiling host-side before model injection, omitting or summarizing oversized rows with disclosure. If the client cannot intercept oversized responses, do not promise a hard byte guarantee. Track source offsets; stop at exhaustion or budget and report partial/truncated status and continuation offset. Keep full exports outside model context. This context budget does not reduce Actor collection defaults. Discovery, caching and token savings depend on the client; no numeric savings are promised.

### Legality, responsible use and diagnostics

Review Football-Data.org terms, attribution and licensing requirements for your intended use. Public accessibility does not establish unrestricted redistribution rights. This Actor is independently operated and is not affiliated with Football-Data.org. It does not bypass authentication or provide access to paid match data.

Failed operations send sanitized diagnostic input, exceptions and Actor/build/run IDs to our private GlitchTip service for repair. Secret fields and URL queries are removed; reports are retained for 30 days. Do not include secrets in unsupported input fields.

### FAQ and troubleshooting

**Why is my dataset empty?** Check exact codes and IDs and remember filter groups use AND. A source field can be null. A no-match selection is valid; an unavailable or malformed upstream catalog is an error instead.

**Can I get matches or standings?** No. This product exports competition reference metadata only. The source's available-season count does not mean season histories were downloaded.

**Why do season dates or names differ from another service?** This Actor preserves Football-Data.org catalog values. It does not reconcile sports-source disagreements or independently calculate season metadata.

**What if I see a rate-limit or network failure?** Review the terminal log. Transient requests have bounded retries, but availability is not guaranteed. Reduce schedule frequency and retry later; do not launch duplicate overlapping runs blindly.

### Related workflows

For a different public source and a different football analysis job, see our [SoccerStats Football Statistics Scraper](https://apify.com/automation-lab/soccerstats-football-stats-scraper) and [Understat Football xG & Shot Data](https://apify.com/automation-lab/understat-football-xg-shot-data). Their tables and performance records are not substitutes for Football-Data.org competition IDs.

# Changelog

This Actor's version history is a separate document: https://apify.com/automation-lab/football-data-org-competitions/changelog.md

# Actor input Schema

## `competitionIds` (type: `array`):

Exact numeric competition IDs. ANY ID matches within this list; combined with code and area filters using AND. Empty or omitted means no ID filter.

## `competitionCodes` (type: `array`):

Exact whole competition codes, such as PL or BL1. Case-insensitive; surrounding whitespace is trimmed. ANY code matches within the list; combined with other filters using AND. Empty or omitted means all codes.

## `areaCodes` (type: `array`):

Exact whole source area codes, such as ENG or DEU; these are not a promise of ISO country codes. Case-insensitive, trimmed, ANY within this list and AND across other filters. Empty or omitted means all areas.

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

Global maximum unique competition rows after filtering, in source order. Default 0 exports all matching rows available in the single current catalog (not unlimited upstream coverage). Positive values truncate the matching list; no historical seasons or detail requests are fetched.

## Actor input object example

```json
{
  "competitionIds": [],
  "competitionCodes": [],
  "areaCodes": [],
  "maxItems": 0
}
```

# Actor output Schema

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

Unique matching competition rows in the default dataset.

# 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 = {
    "competitionIds": [],
    "competitionCodes": [],
    "areaCodes": [],
    "maxItems": 0
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/football-data-org-competitions").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 = {
    "competitionIds": [],
    "competitionCodes": [],
    "areaCodes": [],
    "maxItems": 0,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/football-data-org-competitions").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 '{
  "competitionIds": [],
  "competitionCodes": [],
  "areaCodes": [],
  "maxItems": 0
}' |
apify call automation-lab/football-data-org-competitions --silent --output-dataset

```

## MCP server setup

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

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/Fl8r9eJzVoB2TIQNw/builds/8LGmuOo4RdWb67jgN/openapi.json