# CineFilter

> CineFilter (https://cinefilter.app) is a movie discovery service: a filterable, sortable catalog of the ~27,000 most popular films on Letterboxd. Films can be filtered by any combination of director, actor, writer, cinematographer, composer, production designer, studio, genres, country, language, year range and title, and sorted by popularity or rating.

Data snapshot: April 2026 (film data is scraped from Letterboxd periodically, roughly once a year; ratings and the film list reflect the snapshot date, not real time). 27,363 films, years 1920–present.

## Filter parameters

These parameters define a filtered view. They are used identically in two places: as query parameters of the website itself (`https://cinefilter.app/?<params>` — all UI state lives in the URL, so any filtered view has a shareable address) and in the JSON API below. Values must be URL-encoded.

- `sort` — 0 = popularity, 1 = weighted rating (Bayesian, default), 2 = pure average rating, 3 = newest first (year desc, then popularity)
- `year_from`, `year_to` — release year range, e.g. `year_from=1970&year_to=1979`
- `title` — case-insensitive substring match on the film title
- `director`, `actor`, `writer`, `cinematographer`, `composer`, `prodDesigner`, `studio` — exact full name as spelled on Letterboxd, one value each, e.g. `director=Andrei%20Tarkovsky`. If unsure of the exact spelling, resolve it first via the search endpoints below.
- `req_genres` — genres the film must have (all of them), joined with `_`, e.g. `req_genres=Horror_Comedy`
- `skip_genres` — genres the film must NOT have (none of them), same format
- `country` — exact country name, e.g. `country=Japan` (production country, a film can have several)
- `language` — exact primary language name, e.g. `language=French`

Genres (exact values): Action, Adventure, Animation, Comedy, Crime, Documentary, Drama, Family, Fantasy, History, Horror, Music, Mystery, Romance, Science Fiction, TV Movie, Thriller, War, Western.

In website URLs every parameter is optional. Examples:

- https://cinefilter.app/?year_from=1970&year_to=1979&req_genres=Horror&country=Italy
- https://cinefilter.app/?sort=3&cinematographer=Roger%20Deakins
- https://cinefilter.app/?sort=0&req_genres=Comedy&skip_genres=Romance&language=French

## JSON API: film list

`GET https://cinefilter.app/lb_movies` returns filtered films as JSON: `{ films: [...], hasMore: boolean }`.

Important: this endpoint requires ALL of the following query parameters to be present on every request — use an empty value for filters you don't need: `sort`, `offset`, `init`, `title`, `year_from`, `year_to`, `director`, `actor`, `writer`, `prodDesigner`, `composer`, `cinematographer`, `studio`, `req_genres`, `skip_genres`, `country`, `language`.

- `offset` — pagination offset in films (pages are 30 films; pass 0, 30, 60, …). `hasMore` tells you whether another page exists.
- `init` — pass `false`; `init=true` additionally returns the full lists of genres, countries and languages available in the catalog.
- All other parameters as described in "Filter parameters".

Each film has: `id` (Letterboxd slug), `title`, `year`, `rating` (Letterboxd average, 0–5), `ratingCnt` (number of ratings), `directors`, `actors`, `writers`, `cinematographers`, `composers`, `prodDesigners`, `genres`, `studios`, `countries`, `language`, `poster` (image URL), `url` (the film's Letterboxd page), `num` (rank in the current sort). Note: `directors`, `cinematographers`, `studios`, `countries` and `actors` are truncated display lists (top 3 / top 2 entries); boolean flags `moreDirectors`, `moreCinematographers`, `moreStudios`, `moreCountries` indicate truncation. Filtering still matches against the full lists.

Example:

https://cinefilter.app/lb_movies?sort=1&offset=0&init=false&title=&year_from=1970&year_to=1979&director=&actor=&writer=&prodDesigner=&composer=&cinematographer=&studio=&req_genres=Horror&skip_genres=&country=Italy&language=

## JSON API: name search

Person and studio filters need the exact Letterboxd spelling. Resolve free-text input with these endpoints — each takes a `search` query parameter and returns a JSON array of up to 10 matching names (case-insensitive substring match):

- https://cinefilter.app/directors?search=tarkov
- https://cinefilter.app/actors?search=mifune
- https://cinefilter.app/writers?search=kaufman
- https://cinefilter.app/cinematographers?search=deakins
- https://cinefilter.app/composers?search=morricone
- https://cinefilter.app/prod-designers?search=ferretti
- https://cinefilter.app/studios?search=a24

## Notes

- The catalog covers Letterboxd's most popular ~27k films — a niche film's absence means it didn't make the popularity cut, not that it doesn't exist.
- Sort 1 (default) is a Bayesian weighted rating that discounts films with few votes; sort 2 is the raw average.