How to Let Users Add Matches to Their Calendar (ICS Export)

"Add to calendar" is a small feature that removes real friction — instead of relying on your app's own push notifications (which users may have muted), you can drop a kickoff time directly into whatever calendar app someone already checks every day. This guide covers generating standard .ics files from match data.

Why .ics Instead of a Custom Reminder System

The .ics format (iCalendar) is supported natively by Google Calendar, Apple Calendar, Outlook, and virtually every calendar app. Generating one server-side means zero dependency on push notification permissions or your own reminder infrastructure — the user's own calendar app handles the reminder.

Step 1: Getting the Match Data You Need

Pull the match from /matches, which gives you everything required for a calendar entry — teams, kickoff time, and competition name:

import requests

response = requests.get(
    'https://live-football-api.com/api/v1/matches',
    params={'api_key': 'YOUR_KEY', 'date': '2026-09-05', 'lang': 'en'}
).json()

match = response['data']['matches'][0]

Step 2: Building the .ics File Content

An .ics file is plain text following a specific structure. Here's a minimal generator for a single match:

from datetime import datetime, timedelta

def build_ics(match):
    start = datetime.strptime(match['date_time'], '%Y-%m-%d %H:%M:%S')
    end = start + timedelta(hours=2)  # matches typically run under 2 hours

    summary = f"{match['home']['name']} vs {match['away']['name']}"
    description = f"{match['league']['name']} — kickoff at {match['kickoff']}"

    ics = f"""BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//YourApp//Football Matches//EN
BEGIN:VEVENT
UID:{match['id']}@yourapp.com
DTSTAMP:{datetime.utcnow().strftime('%Y%m%dT%H%M%SZ')}
DTSTART:{start.strftime('%Y%m%dT%H%M%S')}
DTEND:{end.strftime('%Y%m%dT%H%M%S')}
SUMMARY:{summary}
DESCRIPTION:{description}
LOCATION:{match.get('venue', '')}
END:VEVENT
END:VCALENDAR"""
    return ics

Step 3: Serving the File for Download

Set the correct MIME type so browsers and mobile devices recognize it as a calendar file rather than plain text:

# Flask example
from flask import Response

@app.route('/match/<match_id>/calendar.ics')
def match_calendar(match_id):
    match = get_match_by_id(match_id)  # your own lookup
    ics_content = build_ics(match)

    return Response(
        ics_content,
        mimetype='text/calendar',
        headers={'Content-Disposition': f'attachment; filename="match-{match_id}.ics"'}
    )

Step 4: Handling Time Zones Correctly

Kickoff times from the API are typically in the competition's local time or UTC depending on the endpoint — always confirm which, and convert explicitly rather than assuming. A mismatch here is the most common bug in calendar exports, since a wrongly-timed calendar entry is worse than no entry at all:

import pytz

def to_utc_ics_format(date_str, source_tz='Europe/London'):
    naive = datetime.strptime(date_str, '%Y-%m-%d %H:%M:%S')
    localized = pytz.timezone(source_tz).localize(naive)
    utc_time = localized.astimezone(pytz.utc)
    return utc_time.strftime('%Y%m%dT%H%M%SZ')

Using the UTC format (with a trailing Z) in DTSTART/DTEND is the safest choice — every calendar app converts it to the viewer's local time zone automatically, so you don't need to guess where your user actually is.

Step 5: Adding Multiple Matches (a Team's Full Fixture List)

A single .ics file can contain multiple VEVENT blocks — useful for a "subscribe to my team's whole season" feature built from /team_matches:

def build_season_ics(matches, team_name):
    events = '\n'.join(build_vevent_block(m) for m in matches)
    return f"""BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//YourApp//{team_name} Fixtures//EN
{events}
END:VCALENDAR"""

def build_vevent_block(match):
    start = parse_and_convert_to_utc(match['date_time'])
    return f"""BEGIN:VEVENT
UID:{match['id']}@yourapp.com
DTSTAMP:{datetime.utcnow().strftime('%Y%m%dT%H%M%SZ')}
DTSTART:{start}
SUMMARY:{match['home']['name']} vs {match['away']['name']}
END:VEVENT"""

Step 6: A "Live" Subscription Link (Optional, Advanced)

Rather than a one-time download, you can serve a stable URL that calendar apps periodically re-fetch — this keeps postponed or rescheduled matches automatically updated in the user's calendar without them re-downloading anything:

<a href="webcal://yourapp.com/team/arsenal/calendar.ics">
  Subscribe to Arsenal fixtures
</a>

The webcal:// scheme tells the OS to treat it as a live calendar subscription rather than a one-off file download — most calendar apps then re-check that URL periodically for changes.

Frequently Asked Questions

Does adding a calendar event require any special API access?

No, this is entirely built from standard /matches or /team_matches data on your own server — no special endpoint or extra credits are needed beyond the normal match data call.

What happens if a match gets postponed after a user has already added it to their calendar?

A one-time downloaded .ics file won't update automatically — this is exactly what the webcal:// subscription approach solves, since the calendar app re-fetches the source periodically.

Should I include venue information in the calendar event?

Yes if available — the LOCATION field lets the user's calendar app show a map link or travel time estimate, which is a nice touch for fans attending in person.

Can I generate .ics files client-side instead of on my server?

Yes, the same string-building logic works in JavaScript in the browser — generate a Blob with the .ics content and trigger a download via an anchor tag, without needing a server round-trip.