No auth required. Calendar data is public — send the standard required URL parameters (
client_id, app-name, app-version) and a User-Agent header, but no user Authorization token.Last-Modified header to know when they were last refreshed.
Why use these instead of API calls
- No user
Authorizationtoken required (still sendclient_id,app-name,app-version, andUser-Agentlike every Simkl request). - Hugely cheaper — one file covers thousands of airings across hundreds of shows.
- Cacheable on the user’s device for hours.
Files
Airing next (rolling window — yesterday + next 33 days)
Monthly archives
Three regeneration tiers:- Current month + next 3 months ahead — regenerated every 6 hours. Future-month files contain only what’s already been scheduled or announced, so item counts taper off the further ahead you go.
- Previous 12 months — regenerated every 24 hours.
- Older than 12 months — archived in place. Files remain queryable indefinitely but are no longer regenerated;
Last-Modifiedfreezes at end-of-month. The earliest v2 month is July 2024. Some archived months were generated beforeepisode.runtime,watchingandcompletedexisted, and lack those keys.
{{PAST_YEAR}}/{{PAST_MONTH}}) and the furthest future month available right now ({{FUTURE_YEAR}}/{{FUTURE_MONTH}}, which is currentMonth + 3). These dates substitute on page load — they always reflect today:
currentMonth + 3, before July 2024, or with a zero-padded month (/2026/05/) returns 404.
Response shape
Every v2 file — rolling and monthly, all three catalogs — is a single object with exactly two keys:calendar is the schedule. metadata is the show library. A show airing 12 episodes this month appears 12 times in calendar but only once in metadata. That’s the whole point of the split: title, poster, IDs, ratings, and genres are stored once instead of being repeated on every airing.
To render a row, take a calendar entry and look up its show:
metadata keys are strings. It’s a JSON object, so simkl_id becomes a string key. In JavaScript metadata[entry.simkl_id] works because JS coerces the number to a string on property access. In strongly-typed languages, convert explicitly — Python metadata[str(entry["simkl_id"])], Swift metadata[String(entry.simklId)], Kotlin metadata[entry.simklId.toString()].simkl_id in calendar is guaranteed to have a matching metadata record, and there are no orphan metadata records — the two are always consistent within a single file.
Sample (TV)
calendar[] — the schedule
Air / release timestamp, always UTC with a trailing
Z — e.g. 2026-07-20T04:00:00Z. Convert to the user’s local timezone for display. Entries are ordered chronologically.Marks finale episodes so you can badge them in the UI.
null on ordinary episodes and on all movie entries.TV and anime only — the key is absent entirely on movie files, and on anime movies in the anime file (Type 2 null — see Null and missing values). A movie release has no episode, so the whole object is omitted rather than set to
null.metadata{} — the show library
Keyed by simkl_id (as a string). One record per distinct title in the file.
Anime files only. Romanized title (e.g.
Chibi Maruko-chan). Type 4 null when none is on file.Link to the title on simkl.com. Normally a root-relative path (
/tv/3437/king-of-the-hill) — prefix with https://simkl.com to build a full link. Sparse TV records may instead carry a fully-qualified URL, so normalize before use rather than blindly concatenating.Localized and alternate titles. Each entry is
name (string), lang (integer — Simkl internal language code, not ISO 639), and type (such as official or original — treat it as an open set).Image path fragment. Combine with the prefixes in Image conventions — for example
https://wsrv.nl/?url=https://simkl.in/posters/{poster}_m.webp&q=90. Type 4 null when no poster is on file; fall back to https://simkl.in/poster_no_pic.png (see fallbacks).Backdrop image path fragment. Same prefixing rules as
poster. Type 4 null when none is on file — commonly absent on new or regional titles.External and Simkl IDs. Always carries
simkl_id + slug. tmdb is near-universal; imdb / tvdb appear on TV and movies, mal / anidb / anilist / kitsu on anime. Additional IDs (tvdbslug, traktslug, letterboxd, mdlslug, …) appear on titles with those platform links — the object is permissive, so read the keys you need and ignore the rest.The title’s original premiere / release date. Normally a full ISO 8601 UTC timestamp (
1997-01-12T15:30:00Z); a small number of TV records carry a date-only string (2026-07-13). Parse defensively. Type 4 null when unknown.Note this is the title’s first-ever release — the per-episode air date is calendar[].date.Simkl popularity rank. Lower non-zero values = more popular.
0 or Type 4 null for titles that aren’t ranked yet (common on new, upcoming, and regional entries — the majority of movie records are unranked).Percentage of users who started the title and abandoned it, as a display string (
"8.5%"). "-" when there’s not enough data. Parse with a parseFloat-style call if you need it numerically.Number of Simkl users who have the title in Watching or Completed — that is,
watching + completed. The counts refresh independently, so the sum can be off by a few. Type 4 null on unreleased titles.Number of Simkl users with the title in Completed. On a show still airing this is usually small — most of its audience is still in Watching.
Aggregate ratings keyed by source. Simkl is always present; the second source is
imdb on TV and movies, mal on anime. Individual rating / votes values are Type 4 null on titles with no votes yet.Episode or feature runtime as a display string (
"22m", "1h 57m"). Type 4 null when unknown. For a specific episode, calendar[].episode.runtime gives whole minutes as an integer.Release / airing status. Usually
ongoing, ended, premiere or soon; a handful of un-enriched TV records carry another value or Type 4 null. Treat this as an open vocabulary — match the values you care about and fall through gracefully on anything else.TV and anime only. Broadcasting network or streaming service (
Hulu, CBS). Type 4 null when not on file.Movie files only. Physical / digital release date in
MM/DD/YYYY format — note this differs from the ISO 8601 release_date.YouTube video ID (not a full URL) — build the link as
https://www.youtube.com/watch?v={trailer}. Type 4 null when no trailer is on file, which is the majority of entries.