Movies by genre
Browse movies filtered by genre, country, year, and sort order. Path is /movies/genres/{genre}/{type}/{country}/{year}/{sort} — all segments required (use all as the wildcard).
The type segment is reserved — always pass the literal value movies.
| Path param | Values |
|---|---|
genre | all, action, adventure, animation, comedy, crime, documentary, drama, erotica, family, fantasy, history, horror, music, mystery, romance, science-fiction, thriller, tv-movie, war, western |
type | movies (literal) |
country | all or ISO 3166-1 alpha-2 (us, gb, jp, …) |
year | all, single year (2019), or decade (2010s, 2000s) |
sort | popular-this-week, popular-this-month, popular-all-time, rank, release-date, voted, watched |
Items always carry ids.tmdb — the discover query filters out movies without a TMDB-linked record.
Pagination
| Param | Default | Notes |
|---|---|---|
page | 1 | Hard-capped server-side at 20. Higher values clamp silently. |
limit | 60 | Hard-capped server-side at 60. Higher values clamp silently. Returned X-Pagination-Limit reflects the clamped value. |
X-Pagination-* headers on every response — see Pagination.
Silent fallbacks
Bad path segments DO NOT return errors:
| Bad input | What happens |
|---|---|
Unknown genre slug (zzz) | Top-level response is null (NOT []). |
Unknown year (e.g. zzz) | Silently treated as all — full result set. |
Unknown sort (zzzsortzzz) | Silently treated as default sort order. |
Unknown country / network | Silently treated as all. |
Errors
| Status | When |
|---|---|
401 user_token_required | AUTH V2 app called without the user’s token |
412 client_id_failed | Missing or invalid client_id |
500 | Server error |
No 400 or 404 — bad segments fall back silently or return null.
Authorizations
Preferred form: your client_id as a URL query parameter on every request. Self-describing in logs and curl commands. See Headers and required parameters.
Headers
Path Parameters
Response
OK
Premiere year (from the release date). Type 4 null when the catalog has no release date on file. See Null and missing values.
Release / first-air timestamp with the catalog's timezone offset (e.g. 2014-11-05T00:00:00-05:00 for US releases, +09:00 for anime). Type 4 null when no release date is on file. See Null and missing values.
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 on file. See Null and missing values.
Image path fragment for fanart. Combine with the prefixes in Image conventions — for example https://wsrv.nl/?url=https://simkl.in/fanart/{fanart}_medium.webp&q=90. Type 4 null when no fanart on file. See Null and missing values.
Simkl popularity rank. Type 4 null when the item is not yet ranked or the catalog sentinel value (>= 999999) is present. See Null and missing values.