Skip to main content

Documentation Index

Fetch the complete documentation index at: https://api.simkl.org/llms.txt

Use this file to discover all available pages before exploring further.

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.
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:
Simkl Trending MoviesTrending Movies on SimklWhat's Trending on Simkl
Simkl Trending TV ShowsTrending TV on SimklNow Trending — Simkl
Simkl Trending AnimeTrending Anime on SimklTrending Now · Powered by Simkl
Simkl Trending TodayTrending Today on SimklToday on Simkl
Simkl Trending This WeekTrending This Week on SimklThis Week's Top Picks — Simkl
Simkl Most WatchedMost Watched on SimklPopular on Simkl
Simkl Top 100 MoviesTop 100 on SimklHot Right Now — Simkl
Simkl Top ChartsTop Charts on SimklCharting on Simkl
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
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.

Last-Modified

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

​
Update frequency

DataDescriptionUpdate frequency
TodayMost watched titles over the last 24 hoursEvery hour
WeekMost watched titles over the last 7 daysOnce a day
MonthMost watched titles over the last 30 daysOnce a day
DVD releasesLatest popular DVD releases (Movies only)Once a day
The file URLs ignore all query strings. Don’t add ?random=... or ?nocache=... — the CDN treats every variant as the same resource. Simkl regenerates the files on the schedule above and automatically clears them from the Cloudflare cache, so you’ll always get the latest version on your next request — client-side cache-busting won’t deliver newer data.
Movies, TV Shows, and Anime in a single response — use these to minimize the number of requests when you need all categories at once. The top-level JSON is an object with movies, tv, and anime arrays.
TimeframeTop 100Top 500
Todaytoday_100.jsontoday_500.json
Weekweek_100.jsonweek_500.json
Monthmonth_100.jsonmonth_500.json

​
Fetch it

curl -H 'User-Agent: my-app-name/1.0' \
  "https://data.simkl.in/discover/trending/today_100.json?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
Always send a User-Agent with your app name and version (e.g. myapp/1.0) to avoid accidental blocking.

​
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
{
  "title": "The Drama",
  "url": "/movie/2533163/the-drama",
  "poster": "19/19702715dfee84bd7c",
  "fanart": "19/19840547ea18093f08",
  "ids": {
    "simkl_id": 2533163,
    "slug": "the-drama",
    "imdb": "tt33071426",
    "tmdb": "1148540"
  },
  "release_date": "03/26/2026",
  "rank": 3311,
  "drop_rate": "1.6%",
  "watched": 96,
  "plan_to_watch": 820,
  "ratings": {
    "simkl": { "rating": 7.37, "votes": 136 },
    "imdb":  { "rating": 7.4,  "votes": 42928 }
  },
  "country": "us",
  "runtime": "1h 45m",
  "status": "ended",
  "genres": ["Action", "Comedy", "Drama", "Romance"],
  "trailer": "0ZDzsH3XGFA",
  "overview": "A happily engaged couple is put to the test...",
  "metadata": "March 26, 2026 • Budget $28M • Box office $121M",
  "dvd_date": "05/05/2026",
  "theater": "03/26/2026"
}

​
Field reference

​
title
string
Display title.
​
url
string
Path on simkl.com (e.g. /movie/2533163/the-drama). Prepend https://simkl.com to deep-link.
​
poster
string
Image path fragment. Combine with the prefixes in Image conventions — for example https://simkl.in/posters/{poster}_m.webp. When null, fall back to https://simkl.in/poster_no_pic.png (see fallbacks).
​
fanart
string
Image path fragment for fanart. Same prefixing rules as poster. When null, hide the fanart element — there’s no dedicated fanart placeholder.
​
ids
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 third-party slug variants (letterslug, traktmslug, tvdbslug, trakttvslug, mdlslug, …) may appear on items with those platform links — the response is permissive.
​
rank
integer
Simkl service rank for this media type.
​
watched
integer
Number of users who watched this title in the timeframe.
​
plan_to_watch
integer
Number of users with this title on their Plan-to-Watch watchlist.
​
drop_rate
string
Percentage of users who started and dropped, formatted as a string (e.g. "1.6%").
​
ratings
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 }.
​
release_date
string
Original release date in MM/DD/YYYY format.
​
country
string
ISO-style country code (e.g. us, jp).
​
runtime
string
Human-readable duration (e.g. 1h 45m, 25m).
​
status
string
ended, ongoing, tba, or similar.
​
genres
string[]
Array of genre tags.
​
trailer
string
YouTube video ID.
​
overview
string
Synopsis.
​
metadata
string
Pre-formatted human-readable summary line (release year, budget, box office, network, etc.).
​
dvd_date
string
Movies only. DVD release date (MM/DD/YYYY).
​
theater
string
Movies only. Theatrical release date (MM/DD/YYYY).
​
anime_type
string
Anime only. One of tv, movie, special, ova, ona, music video.
​
total_episodes
integer
TV / anime. Episode count.
​
network
string
TV / anime. Broadcasting network.