Skip to content
Tutorials/Endpoint tutorialsIntermediate6 min read

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.

Endpoint reference: fixtures
Flow / From request to your football product
  1. Step 1: Identify

    Prepare leagueId from matching records.

  2. Step 2: Request

    GET /api/v1/football/fixtures

  3. Step 3: Validate

    Check resource IDs, actual dates and available fields.

  4. Step 4: Reuse

    Save a shared snapshot; this feed's source cache lasts 900 seconds.

What you will build

Import a league schedule once and turn it into date pages, team schedules and match links. Use the same saved fixture objects throughout your product.

Full-season fixtures/results with optional paired date_start/date_end in dd.MM.yyyy. Date filters are bounded to seven days per request. Handles week/stage/aggregate nesting, extra time/shootouts, lineups, bench and substitutions where supplied. Cancelled fixtures remain with their status. Starter: restricted to your saved leagues.

Check your plan before starting

This endpoint is included in Starter's league-scoped service set as well as Growth and Pro. Starter customers must save their league choices in Dashboard → Settings first. League-addressed requests must use a saved league; aggregate score responses are filtered to the account's saved leagues.

The service being published does not guarantee every optional field for every competition or fixture. Check the actual records relevant to the page you are building.

Find identifiers and prepare the request

Supply leagueId from the directory. Optional date_start and date_end must be supplied together in DD.MM.YYYY format and span no more than seven days.

Identifiers are strings belonging to specific resources. Keep competition, stage, team, player and static match IDs in separate fields. The code reads identifiers from your environment rather than assuming one sample league is valid for everyone. Growth and Pro customers can discover IDs in the directory; Starter customers should use their saved league IDs from Dashboard → Settings and their permitted fixture or squad records.

  • leagueId: required; positive numeric identifier sent as a string.
  • date_start: optional; DD.MM.YYYY, for example 31.10.2026.
  • date_end: optional; DD.MM.YYYY, for example 31.10.2026.

Make an authenticated server-side request

Set FOOTBALLAPI_KEY to your customer REST key in your server's secret manager. Also set FOOTBALL_LEAGUE_ID for leagueId using the formats above. Save the code as request.mjs and run node request.mjs with Node.js 20 or newer. A widget installation key cannot replace the REST key.

The example makes one request and does not retry automatically. Its 60-second client timeout leaves room for the API's bounded source-read recovery; it is not a promised response time or a browser loading recommendation. Test once in the signed-in playground, then run from a server you control. Visitors should request your own cached delivery route.

A successful transport response is the beginning of validation, not proof that every optional record is populated. Preserve the response metadata alongside the data.

javascript
// Save as request.mjs and run: node request.mjs (Node.js 20+).
// Set the environment variables listed above first. Run only on your server.
const requiredEnv = name => {
  const value = process.env[name]?.trim();
  if (!value) throw new Error(`Set ${name} before running this example`);
  return value;
};
const key = requiredEnv("FOOTBALLAPI_KEY");
const url = new URL("https://footballapi.net/api/v1/football/fixtures");
url.searchParams.set("leagueId", requiredEnv("FOOTBALL_LEAGUE_ID"));
const response = await fetch(url, {
  headers: { Authorization: `Bearer ${key}`, Accept: "application/json" },
  signal: AbortSignal.timeout(60000)
});
if (!response.ok) {
  const retryAfter = response.headers.get("retry-after");
  throw new Error(`Football API HTTP ${response.status}; Retry-After: ${retryAfter ?? "not supplied"}`);
}
const { data, meta } = await response.json();
console.log({ data, meta });

Interpret and render the response

Inspect the returned tournament season, round structure, static match IDs, actual dates and statuses. Deduplicate by static_id before counting completed matches.

Flatten rounds into your internal fixture table while retaining group and round labels. Store venue, kickoff and team IDs even when some optional match-detail sections are absent.

Responses use a data object and meta information. Feed-native fields may use @ prefixes, and repeated elements can be an object or an array. The helper below is an adapter utility, not a standalone renderer: apply it to the specific collection shown in the reference. Preserve missing values instead of turning unavailable statistics into zero.

javascript
const asArray = value => value == null ? [] : Array.isArray(value) ? value : [value];
// Adapter helper: apply to the known collection from this endpoint's reference.
// It does not guess a response path or render a complete page.
// Keep static match IDs and player/team IDs in your saved normalised records.

Save requests without losing useful updates

Prepare visible calendar dates before page load, refresh future fixtures periodically and keep completed fixtures. Schedule changes should update existing records rather than duplicate them.

The published server cache interval for this endpoint is 900 seconds. This is a server reuse interval, not a guarantee of new data every 900 seconds and not a promise that requests served from the API cache are free. Your own cache prevents repeat customer API requests.

Include the endpoint, sorted query parameters, account access scope and relevant date or season in your cache key. Coalesce concurrent misses, serve your own saved response while one background refresh runs, and record its fetched time. Apply corrections to stored results without discarding stable IDs.

Date and time fields are retained as supplied. Establish the timezone for the particular feed before converting a kickoff to UTC or a visitor's local time; do not append Z to a timezone-less value just to make it parse.

Check the result before going live

If a date-range request fails, check the paired filters, date validity and seven-day maximum. Do not replace a populated fixture cache with a failed response.

A 400 response usually needs an input correction, 401 needs a valid key, and 403 needs a plan, saved-league or access check. A disabled endpoint can return 503. Honour Retry-After on 429 responses rather than retrying immediately. Back off on temporary 5xx errors. An empty successful collection is not a reason to launch an unbounded retry loop.

  • Use a known relevant fixture or player for your first comparison.
  • Check that returned competition, season and dates match the page you are building.
  • Keep keys and raw authentication headers out of error logs and support screenshots.
All 51 tutorials