Skip to main content
No auth required. Trending 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.Free to use. These files don’t count against any rate limit — not your app’s, and not a user’s AUTH V2 daily allowance. Wherever they cover what you show, use them instead of live API calls such as the /genres endpoints, which do count.
Which IDs can I send/expect? All accepted input identifiers and the keys you’ll see echoed back in responses are listed at Standard media objects → Supported ID keys. Send every ID you have on writes — Simkl picks the first that resolves and ignores the rest. Reminder: slug is response-only (never send it on a request).
Attribution required. When you display trending data in your app or website, the section title must include Simkl alongside Trending (or an equivalent like Most Watched / Popular). Any sensible combination works — feel free to invent your own wording, as long as both ideas appear together. A few examples to get you started:For commercial use without attribution, contact us — we’re happy to discuss licensing.

Linking back (websites only)

If your client can render hyperlinks — websites, browser extensions, web apps — link the title to the matching Simkl Most Watched page. TV apps, consoles, CLIs, and other contexts that can’t open external URLs are exempt; the title alone is enough.

Most Watched Movies

simkl.com/movies/best-movies/most-watched

Most Watched TV

simkl.com/tv/best-shows/most-watched

Most Watched Anime

simkl.com/anime/best-anime/most-watched
A row built from a genre file links to the same page for its type. Simkl provides pre-built JSON files with trending data ranked by the number of watchers. These are the same rankings displayed on Simkl’s Most Watched pages for Movies, TV Shows, and Anime. Each file is available in two sizes: top 100 (_100) or top 500 (_500) items. Titles with the most watchers are returned first.

At a glance

Sizes

Top 100 (_100) and Top 500 (_500) per file.

By genre

This month’s most watched in every genre — one genre file each, month only, up to 500 items.

Last-Modified

Each file’s Last-Modified response header tells you exactly when it was generated.

Update frequency

Regeneration is best-effort, not strictly precise. The cadences above are targets — the actual job can take a few extra minutes (and occasionally longer) to finish. If your scheduled refresh hits a 304 Not Modified right at the expected time, the new file just hasn’t reached you yet; back off and retry in a few minutes rather than waiting another full cycle. See SimklTrendingClient — drop-in SDK for the recommended pattern.The CDN adds up to an hour. Cloudflare keeps each file for up to 1 hour (Cache-Control: max-age=3600) and is not cleared when a file is regenerated, so a new version can take up to an hour to replace the old one. An hourly today file can therefore be up to about two hours old when you read it. Last-Modified always tells you which version you have.
The file URLs ignore all query strings. Don’t add ?random=... or ?nocache=... — the CDN treats every variant as the same resource, so client-side cache-busting won’t deliver newer data. It only ever returns the copy Cloudflare is holding.
Append ?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0 to every URL below — the SimklTrendingClient does this for you from CONFIG; if you’re rolling your own, see Without the SDK.

Combined

Movies + TV + anime in a single response. Top-level keys: movies, tv, anime. Best when you want all categories at once and don’t want three round-trips.

By type — Movies, TV, Anime

One category per file. Top-level response is the array directly (no wrapper object). Best when you only render one category, or want to fetch them independently.

By genre (this month)

This month’s most watched titles in every genre — one file per genre, per type. Same CDN, same required parameters and User-Agent, same caching and attribution rules as every other file on this page, and just as free: no user token, and no rate limit or AUTH V2 allowance spent. For this month’s most watched in a genre, use these instead of the /genres endpoints, where every call counts. Start from the genre list. Each type has an index.json listing the genres that have a file, sorted A–Z by name:
movies/genre/index.json (first 3 of 20)
name is the display label, slug names the genre’s file, and count is how many items that file holds.
<type> is movies, tv or anime; <slug> comes from that type’s index.json.
Read the slugs from index.json — don’t hardcode them or build them from genre names. The list can change. The same idea can also have a different slug per type: movies and TV use science-fiction, anime uses sci-fi. Show name from index.json as the label.
The slugs are the same as the {genre} values of GET /movies/genres, GET /tv/genres and GET /anime/genres, with two exceptions: TV special-interest has no file, and anime hentai has a file but is not in the /anime/genres list.
The genre lists include adult genres: movies erotica, TV erotica and anime hentai. General-audience apps, and any app distributed through an app store, should skip these slugs.
How genre files differ from the files above:
  1. This month only. No today or week, no _100 size, and no combined file.
  2. _500 means up to 500. Small genres hold fewer — some under 10, such as TV video-game-play and anime yaoi. count in index.json tells you how many before you fetch.
  3. Sorted by watched — this month’s watchers — highest first. Every item has at least 2 watchers.
  4. Same items. Each item has exactly the fields of an item in <type>/month_500.json, so What’s in each item applies as-is.
  5. Each genre file is its own ranking, not a slice of the main file. Filtering the main 500 file by genre — including the SDK’s byGenre and bestOfGenre recipes — only finds titles that made the overall top 500.
  6. Don’t re-check membership against an item’s genres array. In rare cases the file’s genre is missing from it: TV korean-drama items don’t list “Korean Drama”. The file you fetched is the membership.
  7. Updated once a day, in the morning US Eastern time. Treat it like the other daily files: refresh_seconds: 86400, with the same back-off when a refresh returns 304 (Update frequency).
Fetch one genre — read the list, pick a slug, fetch that file:

DVD releases (movies only)

Latest popular DVD releases — mirrors Simkl DVD Releases. No timeframe split; refreshes once a day.

Copy-paste JSON

Drop this object into your app as a constant. Replace YOUR_CLIENT_ID with your registered app’s client_id and my-app-name / 1.0 with your app’s name and version — both the URL params (required_query) AND the matching User-Agent header (user_agent_header) are required on every request, free or paid plan. Each entry has a title (attribution-compliant display label), a url (bare path — append ? + required_query when you fetch), and a refresh_seconds (how often the file is regenerated server-side — set your refresh timer to this value). The structure is category → timeframe → size so you can filter or iterate by any axis. DVD has no timeframe.
  • Titles are pre-composed to satisfy the attribution requirement (every label includes both “Trending” / “Most Watched” and “Simkl”). Use them as-is or adapt the wording — just keep both halves.
  • catalogs is the default row list the SDK renders on a home screen — 58 rows out of the box, all titled and ready to display. Mix of: trending (movies/tv/anime today + DVD), premieres and currently airing, this year / last year, sort variants (mostWatchlisted, highestRated, byRank × 3 types), well-rated and underseen rows (wellRated × 3, underseenGems × 3), bestBoxOffice, marathonWorthy, quickWatches, Best of (Netflix / HBO / Disney+ / Prime Video / Apple TV), Best of for movies (Action / Drama / Comedy / Sci-Fi / Thriller / Horror), TV (Drama / Comedy / Crime / Sci-Fi) and anime (Shounen / Isekai / Romance), Best of , and Anime Movies / Anime OVAs. Edit the JSON to remove rows you don’t want, change titles, or swap recipe opts. Per-app override still works via cfg.catalogs in the SDK config. Every recipe ships in the JavaScript tab below. Python / Swift / Kotlin / Dart ship wellRated and underseenGems; a row that names any other recipe comes back empty in those languages until you port it (see Catalog ideas) or give the row a transform — never the unfiltered feed under a filtered row’s title.
  • refresh_seconds is 3600 (1 hour) for today files and 86400 (1 day) for everything else, matching the Update frequency table. This is the nominal regeneration cadence, not a guarantee — server regeneration can take a few minutes longer. For bandwidth-optimal refresh, pair this with the response’s Last-Modified header and send If-Modified-Since on subsequent requests — the server returns 304 Not Modified when nothing has changed. If a refresh scheduled for refresh_seconds returns 304, back off and retry rather than assuming the cache is final (see SimklTrendingClient — drop-in SDK).
Using the SDK below? Save this whole object as simkl-trending-urls.json in your project — the SDK class loads it back into a SIMKL_TRENDING_URLS symbol. Each language tab’s top comment shows the runtime-appropriate one-liner.

SimklTrendingClient — drop-in SDK

Two-step setup before pasting the SDK class below. First, save the Copy-paste JSON block above as simkl-trending-urls.json in your project (or as an asset your runtime can load). Second, load it back into a SIMKL_TRENDING_URLS symbol — each tab’s top comment shows the runtime-appropriate one-liner (import / require / fetch for JS, open() for Python, Bundle.main for Swift, context.assets for Android, rootBundle for Flutter). The constructor throws if neither this symbol nor an explicit urls argument is in scope.
A single class that wires up the entire data flow. Tune the CONFIG block at the top of each tab — everything else is plumbing you should not need to edit. What’s built in:
  • Auto-picks the Combined endpoint when you ask for 2+ of movies/tv/anime — one HTTP call per timeframe instead of two or three.
  • Persistent cache keyed on the URL — relaunch can paint the UI instantly from the last persisted snapshot before any network call fires. JS auto-detects the host (browser → localStorage[storageKey], Node → file at persistPath); other languages use platform-native paths. Cache entries older than persistMaxAgeSeconds are dropped on restore. client.clearCache() wipes both in-memory and persistent state (and notifies subscribers so the UI repaints empty). For server-side runtimes with many processes, swap the _persist / _restorePersisted / clearCache trio for a Redis / KV adapter.
  • Conditional revalidation with If-Modified-Since so refreshes hit the CDN with a cheap 304 when nothing has changed.
  • Regen-lag backoff — when the server hasn’t regenerated by the time refresh_seconds elapses, the client backs off via a [5min, 15min, 30min] ladder instead of hammering on the nominal cadence.
  • Jitter — ±5% random jitter on every refresh + ±10% on retry delays, so all clients don’t hit the CDN at exactly :00 and don’t retry-storm in lockstep.
  • Retry with exponential backoff + per-request timeout + Retry-After honored for network blips and 429s.
  • Permanent-error classification — 404 / 400 / 401 / 403 are not retried (they’d waste the backoff schedule on a request that will never succeed); the entry’s loop halts and you see the error in the log.
  • Process-wide minIntervalMs floor — N entries refreshing at the same tick are serialized through a 250 ms (configurable) gate so you never burst N parallel requests at the CDN.
  • Concurrent fetch dedup — two callers asking for the same URL fold into one in-flight request.
  • Cancellation — client.stop() aborts every in-flight request and clears every timer.
  • Subscribe / get — your UI subscribes to a type and receives the current cached items immediately, plus a callback on every successful refresh. get(type) is synchronous — paginate the returned array locally for UI pages instead of refetching.
  • client.tick() for background schedulers — call from a BGTaskScheduler / WorkManager / workmanager / cron periodic task to perform a single revalidate-and-persist pass.
  • Namespace-safe — every public symbol is prefixed Simkl… (SimklTrendingClient, SimklTrendingConfig, SimklTrendingError, SIMKL_TRENDING_URLS, etc.) so dropping the class into an existing app doesn’t collide with your own Config / Client / Entry types.
The only thing left to wire up per-platform is background scheduling (the OS-level periodic task that keeps the cache warm while your app is suspended) — see the comment at the bottom of each tab. The SDK doesn’t load the genre files yet — they aren’t in the Copy-paste JSON or the catalogs, so fetch them directly for now.

Try it live

A self-contained vanilla-JS demo of the SDK runs in CodePen below, with two live fetches against data.simkl.in: trending/today_500.json (combined movies/TV/anime in one round-trip) and dvd/releases_500.json. Click Result to see the rendered home screen; JS / HTML / CSS tabs show the wiring.

Open & fork in CodePen

Edit the catalog config, try other recipes, swap the test client_id for your own.
Node 22+, Deno, Bun, React Native, Cloudflare Workers, and other fetch-based JS runtimes — the JavaScript tab above (the SDK file) is universal: save it verbatim as simkl-trending-client.js, then wire it up from your app entry point in ~6 lines. The Browser tab right above it is the HTML+DOM wrapper you’d skip in a headless runtime; here’s the non-browser equivalent:
app.mjs (or index.js App.tsx)
Bundle simkl-trending-urls.json with your app (or fetch + cache it once at startup) so the catalog is in scope when SimklTrendingClient runs. For Cloudflare Workers / Lambda / GitHub Actions etc., call await client.tick() from your scheduler instead of client.start() — see the “Background scheduling” comment at the bottom of the JavaScript tab.
What you still need to do per-platform. The SimklTrendingClient samples above wire up everything that’s host-agnostic — auto-pick combined, persistent cache, conditional revalidation, regen-lag backoff, jitter, retry with exponential backoff + timeout, in-flight dedup, cancellation, and subscribe/get. Two things are left to you because they depend on your platform:
  • Background scheduling that survives app lifecycle. In-process timers stop firing when an iOS app is backgrounded or after Android process death. Hook your platform’s periodic task system to client.tick() — BGTaskScheduler (iOS), WorkManager.PeriodicWorkRequest (Android), the workmanager package (Flutter), or node-cron / Cloudflare Cron / AWS EventBridge for server-side runtimes. Each tab’s trailing comment shows the wireup.
  • Attribution back-link. Websites must link the rendered section title to the matching simkl.com/<type>/best-*/most-watched/ page — see Attribution required and Linking back.
If you want stronger typing on the per-item shape, the Field reference below shows the JSON, ready to bind to a TypeScript interface, Swift Codable, Kotlin @Serializable, or Dart json_serializable.

Catalogs — the rows on your home screen

Think of a TV-style discovery UI: rows of poster carousels stacked vertically, each row with a title at the top-left. The SDK exposes that as client.catalogs() → [{id, title, items}, ...] and client.subscribeCatalogs(cb) — available in all 5 languages above. Each row has a stable id, an attribution-compliant title, and an items array. You iterate and render. Three places rows can come from, in priority order:
  1. cfg.catalogs in your SDK config — explicit, wins if set. Use this to mix trending + derived rows with custom transform closures (see below).
  2. catalogs[] in the Copy-paste JSON above — the default list of rows. Already populated with 58 rows: the four trending rows (movies_today, tv_today, anime_today, dvd) and 54 derived ones. Add, remove, or reorder entries in the JSON to change defaults across your whole app — no code change.
  3. Auto-built fallback — if neither of the above is set, the SDK builds one row per supportedType × timeframes[0] from your CONFIG.
So with the JSON catalogs already populated, new SimklTrendingClient() immediately gives you all 58 rows — no extra config needed. Override only when you want custom rows. Adding derived rows in code — when you want filter/sort logic that’s not in the JSON (a stricter underseen row, say), pass cfg.catalogs with a transform function on each entry:
Need the rows synchronously (e.g. inside a render function)? client.catalogs() returns the resolved list on demand. Same {id, title, items} shape in every language. Available recipe transforms (drop into transform: to derive a row). Each has tunable opts as the 2nd arg — underseenGems(items, { type, minRating, maxVotes, … }), bestOfNetwork(items, { network }), etc. Dial them to your taste without forking.
A derived row is a filtered subset of one trending file, so a short or empty row is a valid result. How many titles a row gets depends on its filter and on what is trending right now — some rows hold a handful, some hold none. Show a short row as it is, or hide an empty one, but never pad it with titles from the unfiltered feed. Load size: 500 once you render derived rows: every filter then has the top 500 to choose from instead of the top 100, on the same fetch schedule.
Adding / reordering rows costs nothing. Catalog rows are resolved at read time off the cached items. Changing cfg.catalogs and recomputing produces a new row list in microseconds. The SDK refreshes the underlying cache on its own cadence (~1h for today, 1d for week/month), independent of how many rows you render.

Catalog ideas — recipe logic at a glance

Every recipe ships in the JavaScript tab. The Python / Swift / Kotlin / Dart tabs ship wellRated and underseenGems; for any other recipe, here’s the logic — drop it into your transform: / client.get(type) pipeline and you have the row.
Tuning a recipe per catalog row. Every recipe accepts an options object as its second arg. In the JSON, set them via recipe_opts. For example, to make tv_underseen stricter — an IMDb rating of at least 8 from no more than 5,000 IMDb ratings, instead of the default 7.5 and 10,000 — override those two knobs:
Same pattern works for any recipe — bestOfDecade with "decade": 1980, bestOfNetwork with "network": "AMC", highestRated with "minVotes": 2000, etc. Stricter options mean shorter rows, and an empty row is a valid result — not something to fill.
Attribution still applies to derived rows. A row labeled “Most Watchlisted Movies” or “Underseen TV” still needs to include “Simkl” or “Most Watched” to satisfy the attribution requirement — e.g. “Most Watchlisted on Simkl”, “Underseen TV on Simkl”, “Trending in Japan — Powered by Simkl”.

Gameplay videos (excludeVideoGamePlay)

Some TV titles are recorded gameplay — Let’s Play videos and playthroughs — and carry the Video Game Play genre. The SDK hides them by default with excludeVideoGamePlay: true (exclude_video_game_play in Python), the same choice Simkl’s app makes.
  • Exact match only. A title is hidden when one of its genres is Video Game Play, compared after normalising case, spaces, - and _. Words in a title, whole networks and other genres — anime’s Strategy Game included — never match, so adaptations such as A Minecraft Movie and Mortal Kombat stay.
  • Everywhere you display. The client applies it whenever it reads items for display, so trending charts, derived rows and a cache restored at launch or offline all show the same selection.
  • The data isn’t changed. The cached and persisted files stay exactly as served. Set the option to false and the titles come back without a refetch.
  • Genre lists too. The SDK doesn’t load the genre files yet. If you list genres from index.json yourself, skip the video-game-play entry — SimklTrendingRecipes.excludeVideoGamePlay(genres) drops it in JavaScript.

What’s in each item

Per-title arrays (movies, tv, anime) all share the same base shape, with a few type-specific fields.
Sample item

Field reference

string
Display title.
object[]
Localized and alternate titles. Always present on every catalog, but often an empty array — check length before reading. Popular titles can carry dozens of entries (60+ on the most widely-released films), so slice before rendering.Each entry has three keys:
  • name (string) — the alternate title.
  • type (string) — official for a localized release title, original for the title in the production’s own language.
  • lang (integer) — Simkl-internal language code. This is not an ISO 639 code and there is currently no public mapping table, so treat it as an opaque grouping key rather than something to render.
If you only need one display title per item, use title and ignore this field entirely.
string
Path on simkl.com (e.g. /movie/2533163/the-drama). Prepend https://simkl.com to deep-link.
string
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. When null, fall back to https://simkl.in/poster_no_pic.png (see fallbacks).
string
Image path fragment for fanart. Same prefixing rules as poster. When null, hide the fanart element — there’s no dedicated fanart placeholder.
object
External and Simkl IDs. Always carries simkl_id + slug. tmdb is near-universal; imdb appears on TV / movies, mal / anidb / anilist / kitsu on anime. Additional IDs (tvdb, tvdbslug, traktslug, letterboxd, mdlslug, …) appear on items with those platform links, named as everywhere else in the API — the response is permissive, so read the keys you need and ignore the rest.
integer | null
The title’s place in Simkl’s rank for its type — the order behind the All-Time Best rows, where 1 is the best-rated. It is based on ratings, weighted by how many votes a title has. It is not a count of viewers and doesn’t reliably tell mainstream titles from obscure ones. null when the title has no rank yet.
integer
Number of users who watched this title in the file’s timeframe — today, this week or this month. On the DVD release files, where there is no timeframe, it is instead watching + completed.
integer
Number of users with this title on their Plan-to-Watch watchlist.
integer
Number of users with this title in Watching. All time — not limited to the file’s timeframe.
integer
Number of users with this title in Completed. All time — not limited to the file’s timeframe.
watched is the only count that follows the timeframe. One movie, read from the three files on the same day:Use watched to ask “what is popular right now?” and watching + completed to ask “how many Simkl users have this title in Watching or Completed?”.
string
Percentage of users who started and dropped, formatted as a string (e.g. "1.6%").
object
Aggregate ratings — Simkl and any external sources available for this title (IMDB for movies/TV, MAL for anime, etc.). Each entry is { rating: number, votes: number }, where votes is how many ratings that source has.
string
Original release date in MM/DD/YYYY format.
string
ISO-style country code (e.g. us, jp). Nullable on anime (~28% of the anime feed); always populated on movies, TV, and DVD.
string | null
Lowercase two-letter language code for the production’s original audio (en, ja, zh, ko). Nullable on anime (~33% of the anime feed); always populated on movies, TV, and DVD. Distinct from country, which is the country of origin — a Japanese-language title can be country: "us" on a co-production.
string
Human-readable duration (e.g. 1h 45m, 25m).
string
One of ended (production wrapped), ongoing (TV/anime still airing new episodes), or premiere (very-recently-released, still in the rollout window). The wider Simkl catalog also uses tba for not-yet-dated titles, but those don’t surface in trending.
string[]
Array of genre tags. A TV title tagged Video Game Play is recorded gameplay; the SDK hides those by default — see Gameplay videos.
string
YouTube video ID.
string
Synopsis.
string
Pre-formatted human-readable summary line (release year, budget, box office, network, etc.).
string
Movies only. DVD release date (MM/DD/YYYY).
string | null
Movies only. Theatrical release date (MM/DD/YYYY). Set on every movie with a theatrical release on file — past releases included, so compare it with today before calling a film “in theaters”. null when none is on file.
string | null
Movies only. Director’s name; several are joined with commas. null when none is on file.
string | null
Content rating as the rating body issues it — PG-13, R, TV-MA, TV-14, NR and so on. On movies, TV and anime. null when no rating is on file (common on TV).
object[] | null
Anime only. Animation studios, each { "id": 736, "name": "GoHands" } — id is a Simkl company ID. null when none is on file.
string | null
Anime only. The anime season it premiered in — Winter, Spring, Summer or Fall plus the year, e.g. Fall 2026. null when no premiere date is on file.
string | null
Anime only. Romanized Japanese title (e.g. Mushoku Tensei III: Isekai Ittara Honki Dasu), for apps that display romaji alongside or instead of the English title. null on roughly a quarter of the anime feed — fall back to title.
string
Anime only. One of tv, movie, special, ova, ona, music video.
integer
TV / anime. Episode count.
string
TV / anime. Broadcasting network.

Without the SDK — raw URL and curl

The SimklTrendingClient above is the recommended way to consume trending data — it handles caching, conditional revalidation, retry, dedup, persistence, and the auto-pick combined endpoint logic. The patterns below are the bare-bones alternative for ad-hoc curl probes, server-side cron jobs that handle their own caching, or runtimes where you don’t want to drop a class file.

URL pattern

If you’d rather construct the URL in code:
  • <category> — omit for Combined (movies + tv + anime in one response); use movies, tv, or anime for type-specific.
  • <timeframe> — today, week, or month.
  • <size> — 100 or 500.
DVD releases use a different prefix and no timeframe:
Genre files are this month only, with a list per type — see By genre:

Fetch it

Always send a User-Agent with your app name and version (e.g. myapp/1.0) to avoid accidental blocking.