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:

{
  "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:

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

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

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

Select one source ID:

{
  "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:

{
  "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:

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:

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:

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:

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:

{
  "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 and Understat Football xG & Shot Data. Their tables and performance records are not substitutes for Football-Data.org competition IDs.