Skip to content
Tutorials/Performance and operationsIntermediate9 min read

Prepare dates and retain football history

Build a fast fixture calendar with timezone-safe dates, bounded imports, saved football history and correction-aware background refreshes.

Flow / Calendar preparation without repeated cold imports
  1. Step 1: Discover

    Competition and season

  2. Step 2: Import

    Fixtures and actual dates

  3. Step 3: Persist

    Stable IDs and snapshots

  4. Step 4: Reconcile

    Future changes and corrections

Confirm the feed timezone before converting dates

Date and time fields are retained as supplied; not every timezone-less kickoff is guaranteed to be UTC. Confirm the timezone for the particular feed before creating a UTC instant. Do not append Z to an unzoned date/time as a guess. Store the original fields, the established timezone and the normalised timestamp.

Relative upcoming and recent-result windows can include adjacent actual fixture dates. Filter by actual date before saving a strict daily archive. Account daily allowance resets use UTC, but that billing boundary does not establish the timezone of every football record. Never relabel a returned fixture to make it fit the requested day.

Prewarm every date your calendar offers

Import season fixtures for selected competitions, then maintain the future dates your interface exposes. If using date_start and date_end, provide both in DD.MM.YYYY form with an ascending range no longer than seven days.

Persist each fixture under static match ID and actual date. A page request should query your store; if the background import is incomplete, distinguish that state from a verified empty matchday. Refresh kickoff changes and postponements without changing the fixture's identity.

Keep completed records rather than repeating imports

Use historical fixtures with an explicit season for past-season schedules and results. For detailed historical statistics, start from a known completed fixture date. Store the returned record, metadata and your own normalised model.

Your permitted website use includes storing and caching supplied data on your infrastructure. Keeping a useful local archive avoids repeated API requests during ordinary browsing. This operational recommendation is not a new promise about unspecified perpetual display rights after subscription cancellation; use your agreed licence for that commercial question.

Retain history while allowing corrections

Permanent storage does not mean permanently ignoring corrections. Track last-fetched and last-changed times, retain stable IDs and update a bounded recent-result window after completion.

Do not replace a populated archive with a failed request, or erase a match because a current-season directory no longer contains its old season. An archive should preserve historical identities, even if display names later change.

Keep the schedule predictable

Run imports with bounded concurrency and durable checkpoints. Save an entire successful batch before advancing its checkpoint. On retries, use idempotent upserts so the same fixture cannot be inserted twice.

Monitor which visible dates are fully prepared, how old future snapshots are and how many API requests the job uses. This is more informative than waiting for a visitor to discover an empty calendar after a slow cold import.

All 51 tutorials