Skip to content
Football API service

Current football competitions API

Build a current-season competition selector from supplied mappings, without mistaking a directory entry for guaranteed fixture, statistics or streaming coverage.

Primary endpoint

GET/api/v1/football/current-competitions

No query parameters.

Access: Growth and Pro. Header: X-API-Key.

Current competition mapping diagram connecting a league identifier to season boundaries and detail coverage.
Conceptual mapping, not an illustration of guaranteed competition coverage.
01

A focused directory for current competition discovery

A football product needs a dependable way to discover which competition identifiers belong in its current navigation. The current-competitions operation supplies the current competition mapping rather than requiring editors to maintain a handwritten list of league numbers. It is useful when preparing a new season, adding a competition selector or reconciling a saved identifier after a competition changes its display name. The response remains a directory, not a schedule: it does not say that a particular match has kicked off, that every club has a crest, or that a detailed statistics record exists for every fixture. Treat discovery and match delivery as separate stages of your integration.

02

Requesting the current mapping securely

Send an authenticated GET request to /api/v1/football/current-competitions. There are no query parameters. A valid account API key belongs in the X-API-Key header, supplied by your server rather than embedded in a browser page. This global directory requires Growth or Pro and an enabled endpoint; a Starter league selection does not unlock global discovery. Keep a readable error distinction between a missing key, an account without the required service and a temporary upstream failure. A successful request returns the standard data and meta envelope. Do not store an error response over your previous valid mapping, because doing so could empty every competition selector at once.

Server-side directory requestbash
curl --fail-with-body 'https://footballapi.net/api/v1/football/current-competitions' -H "X-API-Key: $FOOTBALLAPI_KEY"
From mapping to fixture selectionRead current mappings, retain competition IDs and seasons, inspect coverage flags, then request entitled fixture data.01Current mappingsdirectory02League and seasonstable keys03Coverage flagsoptional hints04Fixture requestentitlement checked
From mapping to fixture selection. A directory describes identifiers; the requested service still checks your account access.
03

Keep identifiers separate from competition labels

The sampled mapping is available beneath data.fixtures.mapping and preserves source attributes with their at-sign prefixes. Useful attributes can include @id, @country, @name, @season, @date_start, @date_end and @iscup. Store the competition identifier as a string, even when it contains only digits. A display name can change without creating a new competition, and two competitions in different countries can have similar names. Your selector should therefore submit the identifier while showing the supplied label and country. Retain the original season and date strings alongside any parsed representation, making later corrections possible without pretending that your application's interpretation was the original record.

04

Reading live-detail flags without overstating coverage

Competition mappings can include @live_lineups, @live_stats and @live_pbp. These are useful hints for deciding which optional features to prepare, but they are not substitute responses from the associated endpoints. A competition-level flag cannot establish whether today's particular match has confirmed teams, player ratings or populated commentary. Match-level score records can provide more specific commentary_available and heatmap identifiers. Check those before preparing detail requests, and inspect the returned content before showing a tab as populated. In particular, a live_pbp flag does not itself publish the text-commentary adapter: populated play records must be verified before that operation appears as an enabled customer service.

05

Current mappings, full mappings and historical seasons

Use current-competitions for a current-oriented selector, competitions for the broader mapping directory and seasons when discovering historical season identifiers. Do not merge their meanings into a single unsupported promise of complete archive depth. A competition disappearing from the current list is not proof that its historical fixtures should be deleted. Preserve saved historical mappings and the season references attached to stored matches. Conversely, a directory entry that exists across several seasons does not imply that every optional statistic is available throughout that period. Keep current navigation, historical navigation and service-specific coverage checks separate so a season transition does not silently corrupt older pages or change their identity.

06

Refreshing a directory without making pages wait

This endpoint has a one-hour gateway cache. A background refresh on a modest schedule is more useful than making every page visitor request the complete mapping. Store a last successful version, its retrieval time and enough diagnostics to notice an unexpected change in the number or shape of records. Publish a replacement atomically after validation, rather than clearing the directory before its successor is ready. A successful cache hit still counts as an API request; a page served from your own saved mapping does not. During a season rollover you can refresh more deliberately, but polling faster than the gateway cache will not create new directory content.

07

Designing country and competition selectors

Group competitions using the supplied country value while retaining the full record behind each option. Country flags are a presentation choice, not an identifier system; international tournaments may need a neutral regional marker rather than a guessed national flag. Search can match names and countries, but the selected value must remain the original competition ID. When a label is absent, do not invent a league name from a nearby record. Hide incomplete options or send them for editorial review. Keep women's competition markers and cup indicators where supplied, because stripping them can make two genuinely different competitions appear identical in a compact navigation list.

08

Testing mapping changes and downstream requests

Test singleton objects, arrays, empty collections and unfamiliar optional attributes when reading mapping records. Do not assume a source collection will always have the same cardinality as your first sample. For a selected competition, validate the subsequent fixture response independently and preserve its competition and season context. Your tests should also cover a renamed competition, an absent coverage flag and a current directory refresh that fails while an older copy remains available. Successful transport is one check; useful, correctly identified content is another. Keep logs free of API keys and source URLs, and retain request IDs so support can investigate failures without receiving your credentials.

09

A practical competition-onboarding workflow

Start by saving the current mapping and choosing a small set of competitions relevant to your audience. Confirm their season values, prepare fixture requests and map the participating teams by team ID. Then add the specific detail services your product needs, checking real match content instead of enabling every possible tab by default. Send users to the API reference for exact parameter and error definitions, and to the seasons guide when they leave the current campaign. This incremental workflow gives editors a useful competition browser early while keeping archive coverage, optional live statistics and separately activated streaming services distinct. Review saved mappings periodically rather than treating the first successful import as permanent truth.

10

Reviewing directory changes before exposing new choices

Compare newly fetched IDs with your saved mapping and review additions, removals and changed season boundaries separately. A change in total record count is useful monitoring information, but it cannot by itself tell you which competition disappeared or why. Keep a small change report keyed by ID and avoid alerting solely on harmless display-name edits. When a new competition enters your selector, verify one relevant fixture request and its season context before promoting related detail features. This review keeps navigation helpful without turning a reference-data refresh into an uncontrolled expansion of the competitions your application claims to support.

Questions developers ask

Does this endpoint require a competition ID?
No. It is a global current-mapping directory with no query parameters.
Is the current directory included with Starter?
No. Current-competitions requires Growth or Pro and endpoint activation.
Does live_pbp prove commentary is available now?
No. It is a coverage hint. A populated commentary sample and actual published operation are required.
Should I delete archived competitions missing from this list?
No. Preserve historical mappings and season references independently of current navigation.
How often is the gateway response refreshed?
The endpoint uses a one-hour cache. Refresh your own saved directory in the background.

Check the plan before you write the integration.

Starter £29, Growth £99, Pro £249 per month. Starter only: 7 days free, once per account, card required. Then £29/month unless cancelled. No VAT currently charged. Existing EUR subscriptions are unchanged.