Finding competition IDs with the league directory

Hard-coded identifiers copied from a forum post or an old project are a common source of bugs. Different providers number competitions differently, cup competitions are easy to confuse with leagues, and women's and youth competitions often have similar names to senior men's ones. A single wrong digit can return a perfectly valid response for an entirely different competition.

The directory is the source of truth. Query it, find the competition by name and country, confirm the identifier, and store it with a note of where it came from.

Our sample league identifier, 1204, is used throughout the documentation as an example. Your product's competitions will have their own identifiers.

The directory is a list, not a search engine. Fetch it once, store it, and build a simple internal search over names and countries. Present your editors with a dropdown or search box that writes the chosen identifier into your configuration, so nobody types numbers by hand.

Refresh the stored directory occasionally, perhaps monthly, and at the start of each season. New competitions appear and seasons roll over.

Many feeds take a season alongside the league identifier. The directory's season catalogue tells you which seasons exist for each competition. Use it to populate season selectors and to avoid requesting seasons that are not available, which would otherwise produce empty responses that look like errors.

Season labels vary: some competitions run within a calendar year, others span two years. Store the label exactly as supplied and display it as is.

Create a competitions table keyed on the supplied identifier, with name, country, type and current season. Reference it from fixtures, standings and squads. If you also have internal slugs for URLs, store them alongside the identifier, never instead of it.

When a competition is renamed, perhaps for sponsorship, the identifier remains. Your pages update their display name and old URLs continue to work through the slug mapping.

Add a startup check that confirms each configured competition identifier exists in the stored directory. If one is missing, log a clear error. That small check catches typos and retired competitions before they produce confusing empty pages.

Also check that the season you request is listed for that competition. A request for a future season before the directory lists it is a common cause of puzzling empty fixtures.

The directory tells you which competitions exist, not how complete each feed is for them. A competition can appear in the directory while its match detail or predicted line-ups remain unavailable. Check feed families on the coverage page and test your competitions directly.

For grouped tournaments and cups, inspect standings and fixtures carefully, since their structures differ from regular leagues.

An editor wants to add a new competition. They open your admin tool, search the stored directory by country, find the competition, choose the current season and save. Your configuration now holds the identifier and season, and the nightly jobs begin requesting fixtures, standings and squads for it.

The startup check confirms the identifier is valid. The first fixtures run populates the schedule. Nobody typed a number, and the audit log records exactly which directory entry was chosen.

At the end of each season, review your configured competitions. Archive those you no longer cover, roll the season forward on the rest, and confirm that every identifier still appears in the refreshed directory. This ten-minute review prevents a slow build-up of stale configuration that otherwise wastes requests on competitions nobody reads.

The first common mistake is mixing up a domestic cup with the league of the same country, which returns fixtures that look plausible but are wrong. The second is using a youth or reserve competition by accident because the name matched a search. The third is carrying an identifier forward after a competition has been restructured, so requests return an old format or nothing at all.

All three are prevented by choosing identifiers from the directory through a tool that shows country and type alongside the name, and by validating configuration whenever the directory refreshes. Keep a short note with each configured competition explaining why it was chosen; future colleagues will thank you.

When in doubt, request a small feed such as standings for the identifier and eyeball the team names. If they are not the clubs you expected, you have the wrong competition, and it is far better to learn that in a test than on a live page.

Use readable slugs for public URLs and keep the identifier as the internal key. A URL such as a competition slug with the season is friendly to readers and search engines, while the identifier ensures the right data loads. If you ever need to rename a slug, add a redirect so external links keep working.