Time zones and kick-off times in football data

The single most useful rule is to store every timestamp in UTC. Convert supplied kick-off times to UTC as soon as you receive them, using the time zone the source documents. Your database then holds one unambiguous instant per match, and every later calculation, from countdowns to sorting, works without surprises.

Keep the original supplied value as well, at least during development. If a conversion bug appears, the original lets you see exactly what arrived and fix the logic.

Never store local display strings such as 3pm as the primary value. They lose the date and zone information you need for correct behaviour.

Before converting, you must know what zone the source uses. Our documentation states the zone for each field once it is confirmed. For one field, the update stamp on today's matches, the time zone is still under confirmation, and the coverage page notes it. Treat such fields cautiously: do not use them for anything user-facing until the zone is confirmed.

Kick-off times and update stamps can use different conventions. Do not assume that because one field is in a given zone, every field is.

Convert from UTC to the visitor's zone, or to your site's stated zone, only when rendering. Modern browsers and server runtimes provide reliable time zone conversion through the Intl APIs and established libraries. Use them rather than adding fixed hour offsets, which break twice a year.

Decide whether your site shows times in the visitor's local zone or in a fixed zone for the competition. Both are valid. Whichever you choose, label it clearly, for example with a short zone abbreviation beside each time or a note at the top of the fixture list.

Daylight saving transitions cause the most bugs. A match at a given local time on the weekend the clocks change may be one hour closer or further from a UTC instant than the previous week. If you add fixed offsets, you will get it wrong. If you store UTC and convert with a proper zone database, you will get it right automatically.

Test explicitly with fixtures on the weekends of clock changes in the zones your audience uses. Write automated tests with known inputs and expected outputs.

Kick-off times change, sometimes at short notice. Refresh fixtures regularly and update the stored UTC time by match identifier. If you send notifications, compare the new time with the last one you notified about and send a correction when it changes.

Show the last refresh time on fixture lists, so readers know how current the schedule is.

Relative labels such as kicks off in two hours are friendly but can mislead if the page is cached. Compute them in the browser from the stored UTC instant, not on the server at render time. Otherwise a cached page may tell a reader a match starts in two hours when it started an hour ago.

After kick-off, replace the countdown with the match status rather than a negative time. Since FootballAPI.net presents nothing as live, show the status from the latest refresh and its time.

A match late in the evening in one zone may fall on the next day in another. Group fixtures by date in the display zone, not by the UTC date, otherwise readers see matches under the wrong day heading. This matters especially for international audiences following competitions in other continents.

Convert to UTC on ingest using the documented source zone. Keep the original. Convert at display time with a proper library. Label the zone. Test clock changes. Group by display-zone date. Compute countdowns client-side. Refresh to catch reschedules. Treat fields with unconfirmed zones as internal only until they are confirmed.

Following those steps removes almost every time bug a football site is likely to meet.

If you offer calendar exports or push notifications, time handling becomes even more important, because errors leave your site and land in people's phones. Export events with UTC instants or explicit zone identifiers, never with floating local times. Include the match identifier in each event so a later reschedule can update the existing entry rather than creating a duplicate.

When a kick-off time changes after a notification was sent, send a short correction that states the old and new times clearly. Readers forgive changes; they do not forgive silence.

Your server's own clock should run in UTC and be synchronised. Browser clocks can be wrong, so if a countdown looks odd, compare it with a server-supplied current time. For most sites, computing in the browser is fine, but logging server time with every refresh helps diagnose reader reports.