Skip to content
Tutorials/Getting startedBeginner8 min read

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.

Flow / Reliable joins start with distinct identifiers
  1. Step 1: Competition

    League and stage identities

  2. Step 2: Fixture

    Durable static match ID

  3. Step 3: Participants

    Separate team and player IDs

  4. 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.

javascript
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.

All 51 tutorials