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.
Step 1: Competition
League and stage identities
Step 2: Fixture
Durable static match ID
Step 3: Participants
Separate team and player IDs
Step 4: Display model
Normalised records and saved metadata
Keep each identifier in its own namespace
A competition ID, stage ID, team ID and player ID can all look like ordinary numbers. That does not make them interchangeable. Store them as strings under explicit names such as competitionId, stageId, teamId and playerId. Preserve static_id as the durable cross-feed match identifier when the record supplies it.
Growth and Pro users can discover competitions in the directory. Starter users should begin with saved league IDs in Dashboard → Settings because global directory access is not included. Retrieve the permitted fixtures and take team and match IDs from those records. Single-match statistics uses id and league; single fixture uses matchId and leagueId. Both single-match routes require Growth or Pro, even though the league-addressed season fixture endpoint is available to Starter.
Separate transport metadata from football records
Read the response status before parsing data as a successful result. A normal feed envelope contains data and meta. Preserve available metadata, including the fetched time, instead of treating the browser's current time as proof that the football record itself is current.
Inside data, inspect the feed-specific hierarchy documented in the reference. A fixture collection can preserve tournaments and weeks; statistics preserve match detail sections. Build a small adapter per feed family rather than a giant recursive function that guesses which nested object must be the requested match.
Normalise single objects and repeated collections
Some collections derived from XML are objects when they contain one entry and arrays when they contain several. A null collection is also different from a populated collection whose numerical statistic is zero. Normalise the known collection boundary and preserve both distinctions.
This is an adapter excerpt, not a standalone request. Set payload to the parsed JSON envelope from a fixtures response first. It illustrates a results.tournament.week.match structure; other competitions can use stage or aggregate nesting and need an adapter for their actual shape. It does not enumerate every fixture structure or guarantee a complete count.
const asArray = value => value == null ? [] : Array.isArray(value) ? value : [value];
const idOf = record => String(record?.['@static_id'] ?? record?.static_id ?? '');
// payload is a parsed fixtures response with this specific week-based shape.
const tournaments = asArray(payload.data?.results?.tournament);
for (const tournament of tournaments) {
for (const week of asArray(tournament.week)) {
for (const match of asArray(week.match)) {
const fixtureId = idOf(match);
if (!fixtureId) continue;
// Validate date/team identity, then upsert your own fixture record.
}
}
}Handle optional data without inventing values
A missing player rating is not a zero rating. Missing confirmed teams are not permission to relabel a predicted lineup as confirmed. An absent heatmap is not proof of either zero coverage or continuous player tracking. Optional sections need their own presence checks.
Keep raw saved payloads alongside the normalised records you need for your product. This makes corrections and adapter changes possible without repeatedly importing the same data. Your ordinary website use and caching are permitted within your plan and enabled services.
Use the live contract as your field guide
Follow the endpoint's own reference for its parameter list, date format and optional data. When joining across feeds, verify both IDs and actual fixture context: team identities, competition and date provide valuable cross-checks.
Before launching a new competition, compare one known completed match, one scheduled match and a match with substitutions. These cases expose incorrect null handling, transient IDs and assumptions about collection shape earlier than a large uninspected import.
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.
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.
Build a football product / 10 min
Build formations, ratings and heatmap views
Use confirmed team positions, match-specific ratings and verified heatmap coordinates without confusing predictions, season averages or tracking coverage.