NBA Calendar Invites From ESPN's Unofficial API
Fetch games from ESPN's undocumented scoreboard or team schedule endpoints under site.api.espn.com, then write each one as an iCalendar VEVENT with a UID derived from ESPN's event id, a UTC start time and an estimated end. Publish a subscription feed or email invitations, and accept that the unofficial feed can change without notice.
What the video demonstrates
The video comes from 31events.com, whose channel promotes a product it calls the Calendar Invite Server: software installed into the buyer's own AWS account from a CloudFormation template, sending invites through Amazon Simple Email Service and tracking RSVPs. The vendor's own materials describe it as a set of APIs that assemble calendar invites in AWS and hand them to SES, with invite data stored in S3 and DynamoDB.
In the demo, a public on-demand page shows cards for upcoming NBA games pulled live from ESPN's data. A visitor types an email address on a card, and a calendar invitation for that game, Bulls versus Timberwolves in the example, lands in the recipient's calendar. When the recipient accepts, then changes to maybe, the response appears in the server's reporting view. The presenter then edits the event to add a promotional note about visiting a booth, and the update propagates to the invite already on the recipient's calendar. The stated use case is promotions: getting a brand's message onto a fan's calendar beside the game.
The product is commercial and the demo is the vendor's. What follows is how the underlying pattern works, so you can judge it or build a simpler version yourself.
ESPN's API is unofficial, and that matters
ESPN once ran a public developer program. It stopped issuing keys in 2014, and coverage at the time reported that existing public keys stopped working on 8 December 2014. The JSON endpoints people use today, under site.api.espn.com, are the undocumented feeds behind ESPN's own site and apps. They need no key and respond quickly, which is why they appear in so many hobby projects.
Undocumented means unsupported. Field names, paths and behaviour can change without notice, there is no published rate limit to stay inside, and use is governed by ESPN's site terms rather than any developer agreement. A personal calendar of your team's games is a low-stakes use. Sending promotional invites to members of the public, or building a commercial product on the feed, is a different risk class; read the terms and consider a licensed source.
Design for breakage
Validate every response against the fields you depend on, fail loudly when one disappears, and keep the last good schedule on disk so a broken fetch never deletes events from users' calendars.
The endpoints that carry schedules
Three NBA endpoints cover most calendar work. Each responded with JSON when checked on 20 November 2026.
Scoreboard by date. site.api.espn.com/apis/site/v2/sports/basketball/nba/scoreboard?dates=YYYYMMDD returns that day's games as an events array. The date parameter follows the US game date: requesting 20261120 returned a Charlotte at Atlanta game whose start time was 2026-11-21T00:00Z, which is 7 p.m. Eastern on the 20th.
Team schedule. .../nba/teams/{id}/schedule returns a team's season of events; team 4 returned the Chicago Bulls. The team list at .../nba/teams supplies the IDs.
Useful fields. Each event carries a stable id, a date in UTC, a full name such as Charlotte Hornets at Atlanta Hawks, a shortName such as CHA @ ATL, and a competitions array with the venue name and a status block. The status type reads STATUS_SCHEDULED before tip-off with a human-readable detail. A timeValid flag indicates whether the listed time is confirmed, which matters for games whose times are still to be set.
Turning events into ICS
An .ics file is plain text in the iCalendar format defined by RFC 5545. Each game becomes one VEVENT inside a VCALENDAR that declares VERSION:2.0 and a PRODID naming your application.
UID. Required, and the most important choice you make. Derive it from ESPN's event id, for example the id plus your domain. A stable UID is what lets a later update replace an event instead of duplicating it.
DTSTAMP. Also required: when this version of the event was generated.
DTSTART and DTEND. ESPN gives the start; it does not give an end. Estimate one, two and a half hours is a reasonable placeholder for an NBA game, and say so in the description.
SUMMARY, LOCATION, DESCRIPTION. The event name, the venue, and anything else, such as a link to the game page.
SEQUENCE. Increment it whenever the event changes, so calendar clients accept the new version.
Feed or invitation
There are two delivery models. A subscription feed is one .ics URL that calendars poll; it uses METHOD:PUBLISH, needs no email, and updates when the client refreshes, which can take hours. An emailed invitation uses METHOD:REQUEST under the iTIP scheduling rules in RFC 5546, arrives immediately and supports RSVPs, which is what the video's server tracks. It also means sending email, with the deliverability and consent obligations that come with it.
Time zones without surprises
Times cause most calendar bugs. RFC 5545 allows three DTSTART forms: UTC with a trailing Z, local time with a TZID parameter, and floating local time with neither. Floating time is wrong for games, since it shows the same clock time in every zone.
ESPN already supplies UTC, so the simplest correct output is UTC: DTSTART:20261121T000000Z. Every client converts it to the viewer's zone. If you prefer local times, for example in the arena's zone, use a TZID such as America/New_York and include a matching VTIMEZONE component, which the specification requires for each TZID used.
Three more traps. ESPN's date strings have minute precision and no seconds, so parse them explicitly. A late game's UTC date is the next calendar day, so never label games from the UTC date. And when timeValid is false, mark the event tentative or all-day rather than inventing a tip-off time.
Keeping invites current
Schedules change: postponements, time changes for television, and NBA Cup knockout games added once the group stage ends. Re-fetch on a schedule, compare against the stored copy, and for any changed event bump SEQUENCE and resend or republish with the same UID. A postponed game should be cancelled with STATUS:CANCELLED rather than silently deleted.
If the calendar is the front end of something analytical, such as a schedule annotated with results or prices, a supported feed removes the fragility. Parlay Ledger's REST API serves game results, real-time and historical odds and player statistics in a unified format with documented endpoints, which suits a post-game update that writes the final score into the event description.
Frequently asked questions
- Does ESPN have an official API?
- Not a public one today. ESPN ran a developer program but stopped issuing keys in 2014, and reporting at the time said existing public keys stopped working on 8 December 2014. The site.api.espn.com endpoints people use now are undocumented feeds behind ESPN's own site, with no developer agreement, no published limits and no stability guarantee.
- What is the calendar invite server in the video?
- A commercial product from 31events.com, installed into the buyer's AWS account from a CloudFormation template. According to the vendor, it assembles calendar invites, sends them through Amazon SES, and stores invite and RSVP data in S3 and DynamoDB. The demo used it to send NBA game invites from ESPN data and push promotional updates to them.
- How do you get the NBA schedule from ESPN's API?
- Call site.api.espn.com/apis/site/v2/sports/basketball/nba/scoreboard with a dates parameter in YYYYMMDD format for one day, or the teams/{id}/schedule endpoint for one team's season. Each event includes an id, a UTC start time, team names, a venue and a status. The endpoints are unofficial, so validate the fields you rely on.
- Should ICS game times use UTC or a local time zone?
- UTC is the simplest correct choice: write DTSTART with a trailing Z and every calendar converts it for the viewer. Local time with a TZID also works, but the file must then include a matching VTIMEZONE component. Never use floating time without a zone, because the game would show at the same clock time everywhere.