Using a football fixtures API

A typical fixture record includes the competition, the season, both teams with identifiers, a scheduled date and time, a venue reference where available, and a status string. Once the match is played, the same record may gain a score and events. FootballAPI.net's season fixtures family returns a full-season list for one competition, and in our samples league 1204 returned a complete schedule with static match identifiers.

Static identifiers matter because they survive rescheduling. If a match moves from Saturday to Sunday, the identifier stays the same and only the date changes. Your database should update the existing row rather than inserting a new one.

Create a table keyed on the supplied match identifier, with columns for both team identifiers, the competition identifier, the kick-off timestamp in UTC, the status and the last time you refreshed the record. Keep the raw JSON as well if storage allows; it makes debugging far easier when a field changes shape.

Avoid deleting fixtures that disappear from a response. A match may drop out temporarily because of a source hiccup. Mark it as unseen and review it, rather than removing it and breaking every page that links to it.

Fixtures change slowly most of the time. Refreshing once or twice a day is usually enough, with an extra refresh on match days for the competitions you feature. Use the request-budget planner to estimate how many calls your cadence consumes each day, including retries. Compare that estimate with the published daily API allowance rather than assuming that a monthly subscription provides a monthly request pool.

For the next few days specifically, the recent-and-upcoming family offers results and fixtures by relative day offset. That is a cheaper way to keep the immediate window fresh without reloading an entire season.

Store kick-off times in UTC and convert only at display time, using the visitor's locale or your site's chosen zone. Time zone handling is one of the most common sources of bugs in football products, particularly around clock changes.

Status strings such as postponed, cancelled or awarded should change how a fixture renders. A postponed match should not show a countdown, and an awarded result should be explained rather than shown as a normal score. Build a small mapping from supplied status values to your own display states, and log any value you have not seen before.

Each fixture is a natural hub. Link it to both team pages by identifier, to the competition's table, and, after the match, to statistics and line-ups where they exist. Because everything joins on identifiers, these links remain correct even when names are edited upstream.

Remember that the catalogue is authoritative for feed identifiers and parameters. The examples in our documentation use illustrative feed names; always confirm the current identifier in the catalogue or the playground before you hard-code it.

Suppose you run a site for a club in league 1204. Each morning your server requests the season fixtures for that league, filters rows where either team identifier equals your club's, and upserts them by match identifier. On match days a second job requests the recent-and-upcoming window with offsets for yesterday, today and tomorrow, which catches late kick-off changes and final scores without reloading the season.

Your pages never call the API. They read from your fixtures table, render kick-off times in the visitor's zone and display a small refreshed-at timestamp. If the morning job fails, yesterday's data still renders, and an alert tells you to investigate.

The most frequent mistake is inserting a new row whenever a date changes, which creates duplicate fixtures that both appear on the page. The second is joining fixtures to teams by name, which breaks the first time a club's official name is edited. The third is treating an empty response as proof that no fixtures exist, which can wipe a schedule during a brief upstream outage.

Each of these is avoided with the same discipline: key on identifiers, keep the previous good state, and treat unexpected emptiness as an error to investigate.

Many sites follow several competitions at once: a domestic league, a domestic cup and a continental tournament. Request each competition's fixtures separately by league identifier, then merge them in your own database. Sorting the merged list by UTC kick-off gives a single club calendar without any special endpoint.

Watch for the same match identifier appearing in two requests, which can happen when a fixture belongs to overlapping views. Upserting by identifier handles that automatically. Use the competition directory to find the identifiers for each tournament rather than copying numbers from forums or old code, because identifiers for cups and continental competitions are easy to confuse.

When a team is knocked out of a cup, its future fixtures in that competition simply stop appearing. Do not delete the past ones; they remain useful for archive pages and season summaries.