Random pick
Returns a random title — perfect for “What should I watch?” features, daily-pick widgets, or seeding recommendation flows. Optionally filter by type, genre, year range, rating, popularity rank, or streaming service availability.
Query / body parameters
All filters can be sent as either query parameters or a JSON body — both forms work. When type is omitted, the server picks one of movie / tv / anime at random first, then returns a random item from that domain.
| Param | Notes |
|---|---|
service | simkl (default), netflix, crunchy, hulu. When set to anything but simkl, results are restricted to titles available on that service AND the response includes {service}_id + {service}_url (e.g. netflix_id, netflix_url). |
type | movie, tv, or anime. Omit to let the server pick a random domain first. |
genre | Comma-separated genre slugs (e.g. action,thriller). Genre slugs differ by type — see the per-type lists below. |
country | ISO 3166-1 alpha-2 country code (movies / TV). |
year_from | Default 1990. |
year_to | Optional. |
rank_limit | Maximum rank to consider (lower = more popular). |
rating_from | Floor rating, 0–10. For TV / movies this filters on IMDb; for anime, on MAL. |
rating_to | Ceiling rating, 0–10. |
limit | Number of items, capped at 50. Single object when omitted; array when set. |
Response shapes
| Shape | When |
|---|---|
{ simkl_id, simkl_url } | limit omitted → single random item. |
[{ simkl_id, simkl_url },...] | limit set → array of up to limit items. |
{ error: "not_found" } | Filters matched nothing. Still status 200 (no 404). |
When service != simkl and a matching service link exists, the item gains {service}_id and {service}_url. When no link exists, the item still returns but without those extra keys.
Genre slugs by type
Slugs are lowercase with spaces normalized to hyphens.
Movies (20): action, adventure, animation, comedy, crime, documentary, drama, erotica, family, fantasy, history, horror, music, mystery, romance, science-fiction, thriller, tv-movie, war, western
TV (38): action, adventure, animation, awards-show, children, comedy, crime, documentary, drama, erotica, family, fantasy, food, game-show, history, home-and-garden, horror, indie, korean-drama, martial-arts, mini-series, musical, mystery, news, podcast, reality, romance, science-fiction, soap, special-interest, sport, suspense, talk-show, thriller, travel, video-game-play, war, western
Anime (46): action, adventure, comedy, drama, ecchi, educational, fantasy, gag-humor, gore, harem, historical, horror, idol, isekai, josei, kids, magic, martial-arts, mecha, military, music, mystery, mythology, parody, psychological, racing, reincarnation, romance, samurai, school, sci-fi, seinen, shoujo, shoujo-ai, shounen, shounen-ai, slice-of-life, space, sports, strategy-game, super-power, supernatural, thriller, vampire, yaoi, yuri
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
Query Parameters
TV Shows, Anime and Movies have their own genres.
Movies: action, adventure, animation, comedy, crime, documentary, drama, erotica, family, fantasy, foreign, history, horror, music, mystery, romance, science-fiction, thriller, tv-movie, war, western TV: action, adventure, animation, awards-show, children, comedy, crime, documentary, drama, erotica, family, fantasy, food, game-show, history, home-and-garden, horror, indie, korean-drama, martial-arts, mini-series, musical, mystery, news, podcast, reality, romance, science-fiction, soap, special-interest, sport, suspense, talk-show, thriller, travel, war, western Anime: action, adventure, cars, comedy, dementia, demons, drama, ecchi, fantasy, game, harem, historical, horror, josei, kids, magic, martial-arts, mecha, military, music, mystery, parody, police, psychological, romance, samurai, school, sci-fi, seinen, shoujo, shoujo-ai, shounen, shounen-ai, slice-of-life, space, sports, super-power, supernatural, thriller, vampire, yaoi, yuri
Your client_id from your Simkl developer settings. Required on every request.
Response
OK — single object (when limit omitted), array (when limit set), or not-found object.
- Single item (no limit) · object
- Single item (no limit) · object[]
- No matches · object
Discriminator is shape-based (no type field on this endpoint): object with simkl_id → single item; array → multiple items; object with error → no match.