Find leagues and use their IDs in API requests
Find football leagues by country or name, copy league IDs and request examples, save Starter choices and display league data safely on your website.
Step 1: Find
Search a country or league and copy its competition ID.
Step 2: Check access
Starter: save up to five eligible leagues. Growth and Pro: no saved-league restriction.
Step 3: Request
Your server requests the endpoint using its documented league parameter.
Step 4: Display
Save the response and render your own fixtures, results or league table.
Find the league you want to display
Search the finder below by league name, country or competition ID. Select a result to see its ID and a ready-to-copy league-table request. For example, England's Premier League uses 1204, while Spain's La Liga uses 1399. Use country as well as name: more than one country has a Premier League.
The finder uses our saved competition catalogue, so searching does not make customer API calls or use your daily request allowance. A catalogue entry identifies a competition; individual feeds and seasons can contain different records. Selecting a result here prepares an example only. It does not change your subscription, save Starter choices or configure a widget.
League ID finder
Search locally, pick a competition, copy its ID or a server-side request. Nothing here is sent to the API.
1023 leagues · showing 40
Selected for this example
Premier League
England
1204curl --fail-with-body --get "https://footballapi.net/api/v1/football/standings" \
--data-urlencode "leagueId=1204" \
-H "Authorization: Bearer $FOOTBALLAPI_KEY" \
-H "Accept: application/json"Keep $FOOTBALLAPI_KEY in a server environment variable. Never paste your key into a browser or front-end code.
This only builds an example.
Selecting a league here does not save or change the leagues on your account. This league can be one of your five Starter leagues. Starter customers save their choices in dashboard settings.
Starter: save your account's permitted leagues
Starter and its seven-day trial are restricted to one to five saved leagues from the available Starter selection catalogue. Turn on the Starter-only filter in the finder to see the eligible choices. The full public catalogue is wider than Starter's selection list.
Sign in and open Dashboard → Settings → Your Starter leagues. Choose your leagues and press Save leagues and lock for 30 days. The initial suggested five are Premier League, La Liga, Ligue 1, Bundesliga and Championship; suggestions are not saved until you confirm them. Save your choices before starting Starter checkout.
Your saved choices apply immediately to new requests across every REST API key on your account. Adding a key does not add another five leagues. After saving, replacements are locked for 30 days; Settings shows when you can change them. Choices and their replacement date persist across upgrades, cancellation and a return to Starter.
Growth and Pro are not restricted by saved Starter choices. You can request available competitions without adding them to this five-league list. You still need an eligible active account and access to the service you request.
Use the right league parameter for the endpoint
Finding an ID and saving account access are different from filtering a request. A league-addressed endpoint needs its documented parameter on each call. The standings endpoint uses leagueId: use leagueId=1204 for the Premier League, or replace 1204 with the ID you selected above. Fixtures, squads and several statistics endpoints also use leagueId; read their endpoint references for all required parameters.
Do not add leagueId to every URL. The standalone match-detail endpoint uses league together with id, while the fixture lookup uses leagueId together with matchId. Match-detail identifiers must be taken from the matching records documented for that service. Odds has its own league mapping and filters. An ID from one namespace is not proof that a different endpoint accepts it.
Aggregate feeds such as scores and live return collections rather than a single league selected with leagueId. On Starter, the server filters those collections to your account's saved leagues. To display just one of those competitions, filter the returned categories in your own integration by the matching competition ID. An arbitrary extra query parameter cannot expand Starter access.
Display your chosen league on your website
Run the generated request on your server, with your customer REST key saved as the FOOTBALLAPI_KEY environment variable. Do not paste a real key into the finder, public JavaScript, a WordPress page or a browser request. The finder never asks for your key or sends a football-data request.
Check the HTTP status before reading the successful data and meta envelope. Follow the selected endpoint's reference to find its actual records: standings, fixtures and live scores do not share one flat matches array. Keep IDs as strings, preserve the supplied team identities and normalise singleton objects and arrays at the documented collection boundary.
Use your server template or your own application's backend to turn the saved records into the league table, fixture list or scoreboard your visitors see. Escape text when generating HTML. Refresh a shared server cache rather than making a new authenticated API request for every visitor. Include the endpoint, league ID and other query parameters in the cache key so two leagues cannot accidentally share a response.
This is the REST API workflow, not a widget installation. You control your own website design and which permitted league it displays. A league selection in the finder is not published automatically, and widget installation keys do not replace customer REST keys.
Check these details if a league does not load
For league_selection_required, open Settings and confirm your saved Starter choices. For league_not_selected, use a league in that saved list; if the replacement lock is active, wait until the displayed change date or use a plan without the Starter league restriction. For starter_service_excluded, the endpoint itself is outside Starter, even if the league is one of your five.
An empty collection is not always an access error: a competition may have no live match, no fixture on the requested date or no records for the selected season. Confirm the country, league ID, endpoint, season and date filters before retrying. Do not guess that an old catalogue season means every current service is unavailable.
Keep a last successful response for temporary connection failures, honour Retry-After when a request is rate limited, and use bounded retries rather than an endless loop. If you need help, send support the endpoint, league ID, requested date or season and request ID, with the API key removed.
Related tutorials
Getting started / 9 min
Make your first FootballAPI.net request
Create an account, activate the right football plan, keep your API key server-side and make a first authenticated scores request with cURL or PHP.
Getting started / 8 min
Understand football IDs and response shapes
Learn static fixture IDs, competition and stage mappings, object-or-array collections and null-safe normalisation for football API responses.
Endpoint tutorials / 6 min
Build a current league table
Render current football standings with positions, points, groups and supplied tie-break ordering using a shared competition cache.
Endpoint tutorials / 6 min
Build a season fixture calendar
Import football season fixtures, use leagueId and paired date filters correctly, and prewarm date pages from a shared fixture store.
Performance and operations / 12 min
Save requests with shared football API caches
Design server-side caching, request coalescing, prewarming and usage budgets so football pages load quickly without unnecessary API calls.