DEV Community

Viktor
Viktor

Posted on

How to Scrape Letterboxd with Python: RSS Diaries, Film Ratings, Watchlists, and a Member-vs-Crowd Report (2026)

Search for "letterboxd api" and you land on a page that says access is by request only. Letterboxd also says it isn't currently granting access for data analysis, visualization, recommendation, LLM, or personal projects. That rules out most of the people searching: film-club newsletters, critics tracking critics, and anyone who wants their friends' ratings next to the crowd's.

This post builds letterboxd.py, a single Python file that uses only the standard library (urllib, xml.etree, sqlite3, re). It covers four things:

  1. feed reads a member's diary from the RSS feed Letterboxd publishes and stores it in SQLite
  2. film parses a film page (average rating, rating count, runtime, genres, TMDB and IMDb IDs)
  3. watchlist reads the part of a public watchlist you can reach without a browser, and shows where that stops
  4. crowd compares several members' ratings with the Letterboxd average for the same films: who's harsher than the crowd, and which films they all logged

Everything below ran on November 18, 2026 on a Linux VM with Python 3.13.5. Every output block is pasted unedited from those runs.

Read this first. Letterboxd's terms prohibit scraping. The Letterboxd Terms of Use (last updated October 2026) say: "Except as explicitly authorized in these Terms, you must not employ any robot, spider, scraper, deep-link, or other automated data gathering or extraction tool, program, or algorithm to access, acquire, copy, or monitor any portion of the Service." They also say you "must not recreate or reproduce platform features that are exclusively included with our paid accounts, either through our API or another means." Read both clauses and think about the legal risk for your use case before you run anything here. The official routes come first: apply for the API, use the per-member RSS feed Letterboxd publishes, use the data export in your own account settings (CSV files for your diary, ratings, and watchlist), and get film metadata from TMDB's API, since Letterboxd sources its film data from TMDB. This tutorial reads public pages only, at one request every 1.5 seconds. It doesn't log in or get around challenges, and it doesn't rebuild Pro stats. When Letterboxd says no (a Cloudflare challenge or a private page), the code stops.

What's open and what isn't

Before writing a parser, I tried each URL once with a normal browser User-Agent:

200  219,975 bytes  /davidehrlich/rss/
200  338,280 bytes  /film/parasite-2019/
200  140,368 bytes  /schaffrillas/watchlist/
403  challenge        /schaffrillas/watchlist/page/2/
200  140,375 bytes  /schaffrillas/watchlist/?page=2
403  challenge        /davidehrlich/films/diary/
403  challenge        /csi/film/parasite-2019/rating-histogram/
403  challenge        /film/parasite-2019/json/
403  private          /gemko/watchlist/
Enter fullscreen mode Exit fullscreen mode

Here's what that means:

  • RSS feeds and film pages are open. They're also the two most useful sources.
  • Watchlist page 1 is open. Page 2 and later get a Cloudflare challenge. So does the diary page (/films/diary/).
  • The internal endpoints the site's JavaScript calls are challenged too. That includes /csi/.../rating-histogram/ and /film/<slug>/json/, which the watchlist HTML even advertises in data-details-endpoint.
  • ?page=2 is the nastiest one. It returns HTTP 200, but with page 1's content. A loop that paginates with query strings will fetch the same 28 films over and over and never fail.
  • A private watchlist also returns 403, but not from Cloudflare. The body is a Letterboxd page titled "Letterboxd - Forbidden". Treat it as "the member said no", not "retry later".

The User-Agent matters. Python's default Python-urllib/3.13 gets a Cloudflare error code: 1010 (banned browser signature) on every URL, even the RSS feed:

https://letterboxd.com/davidehrlich/rss/ HTTP Error 403: Forbidden b'error code: 1010\n'
https://letterboxd.com/film/parasite-2019/ HTTP Error 403: Forbidden b'error code: 1010\n'
Enter fullscreen mode Exit fullscreen mode

Setup and a polite fetch

No dependencies. Save the blocks below in order as letterboxd.py and you'll have the whole script.

#!/usr/bin/env python3
"""Letterboxd in Python (stdlib only): RSS diary feeds, film pages,
watchlist first pages, and a member-vs-crowd rating report.

Read Letterboxd's Terms of Use first: they forbid robots, spiders and
scrapers "except as explicitly authorized", and forbid recreating
paid-account features. Prefer the official API (by application) and
your own CSV export.
"""
import argparse
import json
import os
import re
import sqlite3
import sys
import time
import urllib.error
import urllib.parse
import urllib.request
import xml.etree.ElementTree as ET
from datetime import datetime, timezone
from html import unescape

BASE = "https://letterboxd.com"
UA = ("Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
      "(KHTML, like Gecko) Chrome/131.0 Safari/537.36")
DELAY = 1.5  # seconds between letterboxd.com requests
NS = {"letterboxd": "https://letterboxd.com",
      "tmdb": "https://themoviedb.org",
      "dc": "http://purl.org/dc/elements/1.1/"}

_last = 0.0


class Blocked(Exception):
    pass


class Private(Exception):
    pass
Enter fullscreen mode Exit fullscreen mode

fetch() waits 1.5 seconds between requests and sorts the 403s into two kinds: Blocked for a Cloudflare challenge and Private for a member's privacy setting. It retries 429s and 5xx errors with backoff and returns None for a 404:

def fetch(path, retries=3):
    """GET a letterboxd.com path; tell Cloudflare blocks from private pages."""
    global _last
    url = path if path.startswith("http") else BASE + path
    for attempt in range(retries):
        wait = DELAY - (time.monotonic() - _last)
        if wait > 0:
            time.sleep(wait)
        _last = time.monotonic()
        req = urllib.request.Request(url, headers={
            "User-Agent": UA, "Accept-Language": "en-US,en;q=0.8"})
        try:
            with urllib.request.urlopen(req, timeout=30) as r:
                return r.read().decode("utf-8", "replace")
        except urllib.error.HTTPError as e:
            body = e.read().decode("utf-8", "replace")
            if e.code == 403 and "Just a moment" in body:
                raise Blocked(f"Cloudflare challenge on {url}")
            if e.code == 403 and "Letterboxd - Forbidden" in body:
                raise Private(f"member keeps this page private: {url}")
            if e.code == 404:
                return None
            if e.code in (429, 500, 502, 503) and attempt < retries - 1:
                time.sleep(10 * (attempt + 1))
                continue
            raise
    return None
Enter fullscreen mode Exit fullscreen mode

Step 1: The diary, from RSS

Every member has a feed at letterboxd.com/<username>/rss/. Letterboxd publishes it, so it's the closest thing to an official read API for diaries. Each <item> has a letterboxd: namespace with the watched date, rating, rewatch and like flags, and the film title and year, plus a tmdb:movieId. That TMDB ID is the join key if you want to enrich data through TMDB's official API instead of film pages.

def read_feed(user):
    xml = fetch(f"/{user}/rss/")
    if xml is None:
        raise SystemExit(f"no such member: {user}")
    root = ET.fromstring(xml)
    out = []
    for item in root.iter("item"):
        guid = item.findtext("guid")
        kind = guid.split("-")[1] if guid.count("-") >= 2 else "other"

        def lb(tag):
            return item.findtext(f"letterboxd:{tag}", namespaces=NS)
        rating = lb("memberRating")
        out.append({
            "guid": guid,
            "kind": kind,  # review | watch | list
            "title": item.findtext("title"),
            "link": item.findtext("link"),
            "published": datetime.strptime(
                item.findtext("pubDate"), "%a, %d %b %Y %H:%M:%S %z"
            ).astimezone(timezone.utc).isoformat(),
            "watched_date": lb("watchedDate"),
            "film": lb("filmTitle"),
            "year": int(lb("filmYear")) if lb("filmYear") else None,
            "rating": float(rating) if rating else None,
            "rewatch": lb("rewatch") == "Yes",
            "liked": lb("memberLike") == "Yes",
            "tmdb_id": item.findtext("tmdb:movieId", namespaces=NS),
        })
    return out
Enter fullscreen mode Exit fullscreen mode

Things I found out from real feeds:

  • The feed holds up to 50 diary entries plus up to 50 lists, in one stream. The guid prefix tells them apart: letterboxd-review-…, letterboxd-watch-… (logged without a review), and letterboxd-list-…. If you don't filter lists out, half of your "films" are lists. For one member the feed went back to September 4, for another to March 2025, depending on how much they log.
  • pubDate is in New Zealand time. (Letterboxd is based in Aotearoa.) A critic in New York who logged a film on November 17 has pubDate Wed, 18 Nov 2026 07:20:41 +1300. Use watchedDate for "when did they watch it", and convert pubDate to UTC before comparing.
  • Unrated entries have no memberRating. Don't treat a missing rating as zero.
  • Rewatches get a numbered URL. The second log of the same film is /davidehrlich/film/paper-tiger-2026/1/. That's why step 4 pulls the film slug out of the link with a regex instead of splitting on /.

Storing the feed lets you see what's new on the next run. guid is the primary key, so INSERT OR IGNORE does the deduping:

def db_open(path):
    db = sqlite3.connect(path)
    db.executescript("""
    CREATE TABLE IF NOT EXISTS diary (
      guid TEXT PRIMARY KEY, user TEXT, kind TEXT, film TEXT, year INT,
      watched_date TEXT, rating REAL, rewatch INT, liked INT, tmdb_id TEXT,
      link TEXT, published TEXT, first_seen TEXT);
    CREATE TABLE IF NOT EXISTS films (
      slug TEXT PRIMARY KEY, data TEXT, fetched_at TEXT);
    """)
    return db


def save_feed(db, user, entries):
    now = datetime.now(timezone.utc).isoformat(timespec="seconds")
    new = []
    for e in entries:
        cur = db.execute(
            "INSERT OR IGNORE INTO diary VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)",
            (e["guid"], user, e["kind"], e["film"], e["year"],
             e["watched_date"], e["rating"], int(e["rewatch"]),
             int(e["liked"]), e["tmdb_id"], e["link"], e["published"], now))
        if cur.rowcount:
            new.append(e)
    db.commit()
    return new
Enter fullscreen mode Exit fullscreen mode

First run, then a second run seconds later:

$ python3 letterboxd.py feed davidehrlich --db runs/demo.db
100 feed items {'review': 31, 'watch': 19, 'list': 50}; 100 new
  2026-11-17     3.5  American Theater (2025)  tmdb:1405753
  2026-11-16     1.0  Hershey (2026)  tmdb:1461490
  2026-11-15     3.5  The Rivals of Amziah King (2025)  tmdb:1124142
  2026-11-15     1.5  The Cat in the Hat (2026)  tmdb:1117898
  2026-11-14     4.0  Mouse (2026)  tmdb:1241052
  2026-11-13     2.0  Heartland (2026)  tmdb:1543469
  2026-11-12     1.5  Ebenezer (2026)  tmdb:1567605
  2026-11-11     2.5  How to Rob a Bank (2026)  tmdb:1437511
  2026-11-05     3.0  Hen (2025)  tmdb:1382513
  2026-11-03       -  Klara and the Sun (2026)  tmdb:858035
  2026-10-30     3.0  Who Killed Alex Odeh? (2026)  tmdb:1162823
  2026-10-28  ♥    -  Queen at Sea (2026)  tmdb:1021848
  2026-10-27     2.0  The Mosquito Bowl (2026)  tmdb:1458300
  2026-10-26 R   4.5  Paper Tiger (2026)  tmdb:1381273
  2026-10-25 R   3.5  Closure (2026)  tmdb:1596319
$ python3 letterboxd.py feed davidehrlich --db runs/demo.db
100 feed items {'review': 31, 'watch': 19, 'list': 50}; 0 new
Enter fullscreen mode Exit fullscreen mode

R marks a rewatch and ♥ a like. The feed is the full 100 items: 31 reviews, 19 plain logs, and 50 lists. Run it from cron every few hours and you have a "new diary entries" alert with no HTML parsing at all.

Step 2: Film pages, through JSON-LD

The film page has a schema.org/Movie JSON-LD block with the average rating, rating and review counts, directors, genres, countries, and runtime. There's one catch: Letterboxd wraps the JSON in a CDATA comment (/* <![CDATA[ */ … /* ]]> */), so json.loads on the raw <script> contents fails. The regex below captures only what's between the markers. The TMDB ID sits on <body data-tmdb-id="…">, and the IMDb ID is in an outbound link:

LDJSON = re.compile(
    r'<script type="application/ld\+json">\s*/\* <!\[CDATA\[ \*/(.*?)'
    r'/\* \]\]> \*/\s*</script>', re.S)


def iso_minutes(d):
    m = re.fullmatch(r"PT(?:(\d+)H)?(?:(\d+)M)?", d or "")
    return int(m.group(1) or 0) * 60 + int(m.group(2) or 0) if m else None


def parse_film(slug, html):
    m = LDJSON.search(html)
    if not m:
        raise ValueError(f"no JSON-LD on /film/{slug}/ (layout change?)")
    ld = json.loads(m.group(1))
    agg = ld.get("aggregateRating") or {}
    tmdb = re.search(r'data-tmdb-id="(\d+)"', html)
    imdb = re.search(r'imdb\.com/title/(tt\d+)', html)
    year = re.search(r'"releaseYear"[^>]*>\s*<a[^>]*>(\d{4})<', html)
    return {
        "slug": slug,
        "name": unescape(ld.get("name", "")),
        "year": int(year.group(1)) if year else
        int(ld["dateCreated"][:4]) if ld.get("dateCreated") else None,
        "directors": [p["name"] for p in ld.get("director", [])],
        "genres": ld.get("genre", []),
        "countries": [c["name"] for c in ld.get("countryOfOrigin", [])],
        "runtime": iso_minutes(ld.get("duration")),
        "rating": agg.get("ratingValue"),        # None if too few ratings
        "ratings": agg.get("ratingCount"),
        "reviews": agg.get("reviewCount"),
        "tmdb_id": tmdb.group(1) if tmdb else None,
        "imdb_id": imdb.group(1) if imdb else None,
    }
Enter fullscreen mode Exit fullscreen mode

get_film() caches each parsed film in SQLite for a week. Ratings change slowly, and step 4 asks for the same film once per member who logged it:

def get_film(slug, db=None, max_age_days=7):
    if db is not None:
        row = db.execute("SELECT data, fetched_at FROM films WHERE slug=?",
                         (slug,)).fetchone()
        if row:
            age = datetime.now(timezone.utc) - datetime.fromisoformat(row[1])
            if age.days < max_age_days:
                return json.loads(row[0])
    html = fetch(f"/film/{slug}/")
    if html is None:
        return None
    film = parse_film(slug, html)
    if db is not None:
        db.execute("INSERT OR REPLACE INTO films VALUES (?,?,?)",
                   (slug, json.dumps(film),
                    datetime.now(timezone.utc).isoformat(timespec="seconds")))
        db.commit()
    return film
Enter fullscreen mode Exit fullscreen mode
$ python3 letterboxd.py film parasite-2019
{
  "slug": "parasite-2019",
  "name": "Parasite",
  "year": 2019,
  "directors": [
    "Bong Joon Ho"
  ],
  "genres": [
    "Thriller",
    "Comedy",
    "Drama"
  ],
  "countries": [
    "South Korea"
  ],
  "runtime": 133,
  "rating": 4.51,
  "ratings": 6043385,
  "reviews": 815307,
  "tmdb_id": "496243",
  "imdb_id": "tt6751668"
}
$ python3 letterboxd.py film this-film-does-not-exist-xyz
not found: this-film-does-not-exist-xyz
Enter fullscreen mode Exit fullscreen mode

The average is Letterboxd's own weighted rating, not a plain mean of what the counts suggest. JSON-LD's aggregateRating describes it as "a weighted average score for a movie based on all ratings cast to date by our members". The parser returns None if a film has no aggregateRating. All 148 films in my run had one, and the smallest had 313 ratings.

Step 3: Watchlists (page 1 only)

Watchlist pages render 28 posters per page as data-item-slug / data-item-full-display-name attributes, and data-num-entries holds the total:

POSTER = re.compile(
    r'data-item-slug="([^"]+)"[^>]*?data-item-full-display-name="([^"]*)"')


def read_watchlist(user):
    html = fetch(f"/{user}/watchlist/")
    if html is None:
        raise SystemExit(f"no such member: {user}")
    n = re.search(r'data-num-entries="(\d+)"', html)
    films = {slug: unescape(name) for slug, name in POSTER.findall(html)}
    return films, int(n.group(1)) if n else None
Enter fullscreen mode Exit fullscreen mode
$ python3 letterboxd.py watchlist schaffrillas
28 of 194 watchlist films on page 1
  blue-heron                               Blue Heron (2025)
  cameron-winter-at-carnegie-hall          Cameron Winter at Carnegie Hall (2026)
  we-are-aliens-2026                       We Are Aliens (2026)
  rider-2026                               Rider (2026)
  nuisance-bear-2026                       Nuisance Bear (2026)
deeper pages answer with a Cloudflare challenge; use the member's own CSV export for the rest
$ python3 letterboxd.py watchlist gemko
private: member keeps this page private: https://letterboxd.com/gemko/watchlist/
Enter fullscreen mode Exit fullscreen mode

I first wrote a paginating version for a "what's on both our watchlists" picker. It died on page 2 with a Cloudflare challenge, every time and at any speed. I'm not going to fight that challenge, so the function reads page 1 (the 28 most recently added films) and says how many it couldn't reach. For your own watchlist, or a friend's who agrees, the account data export includes a full watchlist.csv. That's the right input for a picker.

Step 4: Members vs. the crowd

Here's the actual project. Take a few members' recent diaries (from RSS), look up each rated film's Letterboxd average (from the film page, cached), and compute member rating - crowd average. Per member it reports the mean and median gap, the share of films they rated below the crowd, and their biggest disagreements in each direction. Across members it lists films more than one of them logged.

FILM_IN_LINK = re.compile(r"/film/([^/]+)/")


def crowd_report(db, users, days=60, min_ratings=500):
    since = (datetime.now(timezone.utc).date()
             .toordinal() - days)
    rows = db.execute(
        "SELECT user, film, year, rating, link, watched_date FROM diary "
        "WHERE kind != 'list' AND rating IS NOT NULL AND user IN (%s)"
        % ",".join("?" * len(users)), users).fetchall()
    per_user, by_film = {}, {}
    for user, film, year, rating, link, watched in rows:
        if datetime.fromisoformat(watched).toordinal() < since:
            continue
        slug = FILM_IN_LINK.search(link).group(1)
        f = get_film(slug, db)
        if not f or f["rating"] is None or (f["ratings"] or 0) < min_ratings:
            continue
        gap = round(rating - f["rating"], 2)
        per_user.setdefault(user, []).append((gap, rating, f))
        by_film.setdefault(slug, {"film": f, "users": {}})["users"][user] = rating
    return per_user, by_film


def print_report(per_user, by_film):
    print(f"{'member':14} {'n':>3} {'mean gap':>8} {'median':>7} "
          f"{'harsher':>7}  lowest vs crowd / highest vs crowd")
    for user, items in sorted(per_user.items()):
        gaps = sorted(g for g, _, _ in items)
        mid = len(gaps) // 2
        median = gaps[mid] if len(gaps) % 2 else (gaps[mid - 1] + gaps[mid]) / 2
        harsh = sum(g < 0 for g in gaps) / len(gaps)
        lo = min(items, key=lambda x: x[0])
        hi = max(items, key=lambda x: x[0])
        print(f"{user:14} {len(items):>3} {sum(gaps) / len(gaps):>+8.2f} "
              f"{median:>+7.2f} {harsh:>7.0%}  "
              f"{lo[2]['name']} {lo[1]} vs {lo[2]['rating']} / "
              f"{hi[2]['name']} {hi[1]} vs {hi[2]['rating']}")
    shared = [v for v in by_film.values() if len(v["users"]) > 1]
    if shared:
        print("\nlogged by more than one member:")
        for v in sorted(shared, key=lambda v: -len(v["users"])):
            f = v["film"]
            who = ", ".join(f"{u} {r}" for u, r in sorted(v["users"].items()))
            print(f"  {f['name']} ({f['year']}) crowd {f['rating']}: {who}")
Enter fullscreen mode Exit fullscreen mode

I ran it on four public members: IndieWire's chief film critic David Ehrlich (davidehrlich), YouTube film reviewers Schaffrillas (schaffrillas) and Karsten Runquist (kurstboy), and longtime member Dave Vis (dave). The window is the last 90 days, and films with fewer than 500 ratings are skipped, since a new film's average is still moving:

$ time python3 letterboxd.py crowd davidehrlich schaffrillas kurstboy dave --days 90
davidehrlich: 100 new feed items
schaffrillas: 76 new feed items
kurstboy: 100 new feed items
dave: 100 new feed items
member           n mean gap  median harsher  lowest vs crowd / highest vs crowd
dave            46    +0.02   +0.05     48%  Clayface 3.0 vs 3.71 / The Rivals of Amziah King 4.5 vs 3.41
davidehrlich    37    -0.45   -0.50     76%  Hershey 1.0 vs 2.83 / Paper Tiger 4.5 vs 3.38
kurstboy        46    +0.09   +0.11     41%  Digger 2.5 vs 3.91 / Carrie 5.0 vs 3.84
schaffrillas    46    -0.18   -0.12     61%  Hot Rod 1.5 vs 3.55 / Primetime 4.5 vs 3.63

logged by more than one member:
  Wildwood (2026) crowd 4.38: dave 4.5, davidehrlich 3.0, kurstboy 4.0, schaffrillas 4.5
  Digger (2026) crowd 3.91: dave 3.5, davidehrlich 2.5, kurstboy 2.5, schaffrillas 3.5
  Godzilla Minus Zero (2026) crowd 4.01: dave 4.0, davidehrlich 3.5, kurstboy 4.5, schaffrillas 4.0
  Primetime (2026) crowd 3.63: dave 3.0, davidehrlich 4.0, kurstboy 4.5, schaffrillas 4.5
  You Can See Everything (2026) crowd 4.58: davidehrlich 4.5, kurstboy 5.0, schaffrillas 5.0
  Resident Evil (2026) crowd 3.73: davidehrlich 3.5, kurstboy 3.5, schaffrillas 4.5
  The Debut (2026) crowd 4.09: davidehrlich 4.0, kurstboy 4.0, schaffrillas 4.0
  Possible Love (2026) crowd 4.15: dave 4.0, kurstboy 4.5, schaffrillas 4.0
  The Rivals of Amziah King (2025) crowd 3.41: dave 4.5, davidehrlich 3.5
  Mouse (2026) crowd 4.04: davidehrlich 4.0, schaffrillas 4.5
  Ray Gunn (2026) crowd 3.72: davidehrlich 3.0, schaffrillas 3.0
  Godzilla Minus One (2023) crowd 4.08: dave 4.0, davidehrlich 3.0
  Forgotten Island (2026) crowd 3.85: dave 4.0, davidehrlich 3.0
  Your Mother Your Mother Your Mother (2026) crowd 3.85: davidehrlich 4.0, schaffrillas 4.5
  Wild Horse Nine (2026) crowd 4.15: dave 4.0, schaffrillas 4.0
  Carrie (1976) crowd 3.84: kurstboy 5.0, schaffrillas 3.5
  All of a Sudden (2026) crowd 4.22: dave 4.5, schaffrillas 4.0
  Sense and Sensibility (2026) crowd 3.96: dave 4.0, kurstboy 4.0
  Clayface (2026) crowd 3.71: dave 3.0, kurstboy 3.0
  The Social Reckoning (2026) crowd 3.01: dave 3.0, kurstboy 2.0

real    3m46.779s
user    0m0.743s
sys 0m0.206s
Enter fullscreen mode Exit fullscreen mode

That first run fetched 4 feeds and 148 film pages in 3 minutes 46 seconds at 1.5 seconds per request, with no challenges. The second run used the film cache and only fetched the 4 feeds:

davidehrlich: 0 new feed items
schaffrillas: 0 new feed items
kurstboy: 0 new feed items
dave: 0 new feed items
member           n mean gap  median harsher  lowest vs crowd / highest vs crowd
dave            46    +0.02   +0.05     48%  Clayface 3.0 vs 3.71 / The Rivals of Amziah King 4.5 vs 3.41
davidehrlich    37    -0.45   -0.50     76%  Hershey 1.0 vs 2.83 / Paper Tiger 4.5 vs 3.38
kurstboy        46    +0.09   +0.11     41%  Digger 2.5 vs 3.91 / Carrie 5.0 vs 3.84
schaffrillas    46    -0.18   -0.12     61%  Hot Rod 1.5 vs 3.55 / Primetime 4.5 vs 3.63

logged by more than one member:
  Wildwood (2026) crowd 4.38: dave 4.5, davidehrlich 3.0, kurstboy 4.0, schaffrillas 4.5
  Digger (2026) crowd 3.91: dave 3.5, davidehrlich 2.5, kurstboy 2.5, schaffrillas 3.5
  Godzilla Minus Zero (2026) crowd 4.01: dave 4.0, davidehrlich 3.5, kurstboy 4.5, schaffrillas 4.0
  Primetime (2026) crowd 3.63: dave 3.0, davidehrlich 4.0, kurstboy 4.5, schaffrillas 4.5
  You Can See Everything (2026) crowd 4.58: davidehrlich 4.5, kurstboy 5.0, schaffrillas 5.0
  Resident Evil (2026) crowd 3.73: davidehrlich 3.5, kurstboy 3.5, schaffrillas 4.5
  The Debut (2026) crowd 4.09: davidehrlich 4.0, kurstboy 4.0, schaffrillas 4.0
  Possible Love (2026) crowd 4.15: dave 4.0, kurstboy 4.5, schaffrillas 4.0
  The Rivals of Amziah King (2025) crowd 3.41: dave 4.5, davidehrlich 3.5
  Mouse (2026) crowd 4.04: davidehrlich 4.0, schaffrillas 4.5
  Ray Gunn (2026) crowd 3.72: davidehrlich 3.0, schaffrillas 3.0
  Godzilla Minus One (2023) crowd 4.08: dave 4.0, davidehrlich 3.0
  Forgotten Island (2026) crowd 3.85: dave 4.0, davidehrlich 3.0
  Your Mother Your Mother Your Mother (2026) crowd 3.85: davidehrlich 4.0, schaffrillas 4.5
  Wild Horse Nine (2026) crowd 4.15: dave 4.0, schaffrillas 4.0
  Carrie (1976) crowd 3.84: kurstboy 5.0, schaffrillas 3.5
  All of a Sudden (2026) crowd 4.22: dave 4.5, schaffrillas 4.0
  Sense and Sensibility (2026) crowd 3.96: dave 4.0, kurstboy 4.0
  Clayface (2026) crowd 3.71: dave 3.0, kurstboy 3.0
  The Social Reckoning (2026) crowd 3.01: dave 3.0, kurstboy 2.0

real    0m4.877s
user    0m0.091s
sys 0m0.023s
Enter fullscreen mode Exit fullscreen mode

Some things worth noticing in the numbers:

  • The critic is the outlier. Ehrlich rated 76% of his films below the Letterboxd average, with a mean gap of -0.45 stars. The other three are within ±0.2 of the crowd, and two of them are slightly above it. If you're building a "who should I trust" newsletter, that difference matters more than any single rating.
  • Shared films are where the comparison is honest. Wildwood was logged by all four: the crowd gives it 4.38, three of them gave 4.0–4.5, and Ehrlich gave 3.0. Primetime goes the other way: the crowd gives 3.63, and three of the four rated it higher.
  • The biggest single gaps are older or genre films, like Hot Rod at 1.5 vs. 3.55 and Carrie at 5.0 vs. 3.84. A rewatch rated against a 50-year-old consensus is a different signal from a festival-premiere rating.

Caveats I'd put in any write-up: the crowd average includes the member's own rating (negligible at hundreds of thousands of ratings, not at 500). RSS only reaches each member's last 50 diary entries, so "90 days" means "90 days or 50 entries, whichever is shorter". And a mean gap over 37–46 films is a description, not a ranking.

Using an API instead

The DIY version works because RSS and film pages are open. It stops at the walls in the probe table: diary pages, watchlist page 2, and anything behind the site's JavaScript. If you'd rather not maintain HTML parsing at all, ScrapeAtlas* is a scraping API that covers 50 platforms, Letterboxd among them. It has endpoints for films, filmographies, profiles, diaries, watched films, watchlists, reviews, lists, activity, and a member's network. The client is a few lines with an x-api-key header, and it maps the film response to the same dict shape as parse_film():

def scrapeatlas(endpoint, **params):
    key = os.environ.get("SCRAPEATLAS_API_KEY")
    if not key:
        raise SystemExit("set SCRAPEATLAS_API_KEY first")
    url = (f"https://api.scrapeatlas.com/v1/letterboxd/{endpoint}?"
           + urllib.parse.urlencode(params))
    req = urllib.request.Request(url, headers={"x-api-key": key})
    try:
        with urllib.request.urlopen(req, timeout=60) as r:
            return json.load(r)
    except urllib.error.HTTPError as e:
        return json.loads(e.read() or b"{}")


def film_via_scrapeatlas(slug):
    d = scrapeatlas("film", slug=slug)
    if not d.get("success"):
        return None
    f = d["film"]
    r = f.get("rating") or {}
    return {
        "slug": f["slug"], "name": f["name"], "year": f["year"],
        "directors": [p["name"] for p in f.get("directors", [])],
        "genres": [g["name"] for g in f.get("genres", [])],
        "countries": [c["name"] for c in f.get("countries", [])],
        "runtime": f.get("runtimeMinutes"),
        "rating": r.get("average"), "ratings": r.get("count"),
        "reviews": r.get("reviewCount"),
        "tmdb_id": f.get("tmdbId"), "imdb_id": f.get("imdbId"),
    }
Enter fullscreen mode Exit fullscreen mode
$ python3 letterboxd.py film parasite-2019 --via scrapeatlas
{
  "slug": "parasite-2019",
  "name": "Parasite",
  "year": 2019,
  "directors": [
    "Bong Joon Ho"
  ],
  "genres": [
    "Thriller",
    "Comedy",
    "Drama"
  ],
  "countries": [
    "South Korea"
  ],
  "runtime": 133,
  "rating": 4.51,
  "ratings": 6043378,
  "reviews": 815303,
  "tmdb_id": 496243,
  "imdb_id": "tt6751668"
}
Enter fullscreen mode Exit fullscreen mode

Diff it against the HTML run from step 2 and two things show up. First, tmdb_id is an integer there and a string from my data-tmdb-id regex, so normalize before you join on it. Second, the rating and review counts are a few apart (6,043,385 vs. 6,043,378) because the two requests ran seconds apart and Parasite keeps getting ratings. A missing film comes back as a clean not_found:

{"success":false,"status":"failed","failure":{"code":"not_found","message":"The Letterboxd film, person or member was not found."}}
Enter fullscreen mode Exit fullscreen mode

The member endpoints add what RSS doesn't have: profile and favorites, a per-entry hasReview flag, and review text with a spoiler flag:

def member_via_scrapeatlas(user):
    prof = scrapeatlas("profile", username=user)
    if not prof.get("success"):
        f = prof.get("failure", {})
        raise SystemExit(f"profile: {f.get('code')} {f.get('message')}")
    diary = scrapeatlas("user-diary", username=user)
    reviews = scrapeatlas("user-reviews", username=user)
    return prof["profile"], diary, reviews
Enter fullscreen mode Exit fullscreen mode
$ python3 letterboxd.py member davidehrlich
davidehrlich (New York City): 3,492 films logged
favorites: Marie Antoinette (2006), Linda Linda Linda (2005), The Bad and the Beautiful (1952), Thirst for Love (1966)
diary: 50 items, page 1 of 67, warnings ['first_page_only']
reviews: 12 items, page 1 of 245, warnings ['first_page_only']
latest diary: 31 of 50 entries have a review, 9 unrated, 4 rewatches
latest reviews: 1 flagged as spoilers
$ python3 letterboxd.py member gemko
Mike D'Angelo (Oxnard, CA): 10,061 films logged
favorites: Only Angels Have Wings (1939), Manhattan (1979), Double Indemnity (1944), Exotica (1994)
diary: 50 items, page 1 of 261, warnings ['first_page_only']
reviews: 12 items, page 1 of 553, warnings ['first_page_only']
latest diary: 46 of 50 entries have a review, 0 unrated, 18 rewatches
latest reviews: 0 flagged as spoilers
Enter fullscreen mode Exit fullscreen mode

Be clear about the limit, because the response is: the list endpoints return page one only. The diary response says totalPages: 67 with coverage.warnings: ["first_page_only"], and the watchlist endpoint returned 28 of dave's 611 films with status: "partial". That's the same page-1 wall as the DIY version, but reported in the payload instead of discovered at runtime. It's good for "latest N" monitoring and film or profile lookups, and wrong for full-history exports. For a full history of your own account, the official export is still the answer.

The CLI

The last block wires the commands together:

def main():
    ap = argparse.ArgumentParser()
    sub = ap.add_subparsers(dest="cmd", required=True)
    p = sub.add_parser("feed"); p.add_argument("user")
    p.add_argument("--db", default="letterboxd.db")
    p = sub.add_parser("film"); p.add_argument("slug")
    p.add_argument("--via", choices=["html", "scrapeatlas"], default="html")
    p = sub.add_parser("watchlist"); p.add_argument("user")
    p = sub.add_parser("member"); p.add_argument("user")
    p = sub.add_parser("crowd"); p.add_argument("users", nargs="+")
    p.add_argument("--db", default="letterboxd.db")
    p.add_argument("--days", type=int, default=60)
    p.add_argument("--min-ratings", type=int, default=500)
    args = ap.parse_args()

    try:
        if args.cmd == "feed":
            entries = read_feed(args.user)
            new = save_feed(db_open(args.db), args.user, entries)
            kinds = {}
            for e in entries:
                kinds[e["kind"]] = kinds.get(e["kind"], 0) + 1
            print(f"{len(entries)} feed items {kinds}; {len(new)} new")
            for e in new[:15]:
                if e["kind"] == "list":
                    print(f"  [list]   {e['title']}")
                    continue
                stars = "-" if e["rating"] is None else e["rating"]
                flags = ("R" if e["rewatch"] else " ") + \
                        ("♥" if e["liked"] else " ")
                print(f"  {e['watched_date']} {flags} {stars:>4}  "
                      f"{e['film']} ({e['year']})  tmdb:{e['tmdb_id']}")
        elif args.cmd == "film":
            f = (get_film(args.slug) if args.via == "html"
                 else film_via_scrapeatlas(args.slug))
            print(json.dumps(f, indent=2, ensure_ascii=False)
                  if f else f"not found: {args.slug}")
        elif args.cmd == "watchlist":
            films, total = read_watchlist(args.user)
            print(f"{len(films)} of {total} watchlist films on page 1")
            for slug, name in list(films.items())[:5]:
                print(f"  {slug:40} {name}")
            if total and total > len(films):
                print("deeper pages answer with a Cloudflare challenge; "
                      "use the member's own CSV export for the rest")
        elif args.cmd == "member":
            prof, diary, reviews = member_via_scrapeatlas(args.user)
            print(f"{prof['displayName']} ({prof['location']}): "
                  f"{prof['stats']['films']:,} films logged")
            print("favorites:", ", ".join(
                f"{f['name']} ({f['year']})" for f in prof["favoriteFilms"]))
            for name, d, key in (("diary", diary, "entries"),
                                 ("reviews", reviews, "reviews")):
                if not d.get("success"):
                    print(f"{name}: {d.get('failure')}")
                    continue
                print(f"{name}: {len(d[key])} items, page 1 of "
                      f"{d.get('totalPages')}, warnings "
                      f"{d['coverage']['warnings']}")
            e = diary.get("entries", [])
            print(f"latest diary: {sum(x['hasReview'] for x in e)} of {len(e)}"
                  f" entries have a review, {sum(x['rating'] is None for x in e)}"
                  f" unrated, {sum(x['rewatch'] for x in e)} rewatches")
            spoilers = sum(r["spoiler"] for r in reviews.get("reviews", []))
            print(f"latest reviews: {spoilers} flagged as spoilers")
        elif args.cmd == "crowd":
            db = db_open(args.db)
            for u in args.users:
                new = save_feed(db, u, read_feed(u))
                print(f"{u}: {len(new)} new feed items", file=sys.stderr)
            print_report(*crowd_report(db, args.users, args.days,
                                       args.min_ratings))
    except Blocked as e:
        raise SystemExit(f"blocked: {e}. Slow down, or use the API.")
    except Private as e:
        raise SystemExit(f"private: {e}")


if __name__ == "__main__":
    main()
Enter fullscreen mode Exit fullscreen mode

Pitfalls, in one list

  • Python's default User-Agent gets Cloudflare error code: 1010 on every URL, even RSS.
  • ?page=N returns page 1 with HTTP 200. Paginate with /page/N/ paths and check the content, not the status code.
  • Watchlist page 2+ and /films/diary/ are challenged for non-browser clients. Use RSS (last 50 entries) or the account export.
  • Two different 403s: Cloudflare's "Just a moment..." and Letterboxd's "Forbidden" for private pages. Only the first one might be transient.
  • RSS mixes up to 50 lists in with 50 diary entries. Filter on the guid prefix.
  • pubDate is New Zealand time. watchedDate is the date the member logged.
  • Rewatch URLs end in /1/, /2/, … so extract the slug with a regex.
  • Film JSON-LD is wrapped in a CDATA comment.
  • Don't rebuild Pro features (personal stats pages and the like). The terms single that out.

Wrapping up

  • RSS is the Letterboxd API most people actually get: 50 diary entries with ratings, flags, and a TMDB ID, published by Letterboxd itself.
  • Film pages carry clean JSON-LD. Cache them, because the same film comes up again and again.
  • Everything paginated stops at page 1 without a browser. Plan around it instead of fighting it.
  • Member-vs-crowd gaps make a small, honest comparison: one critic sat at -0.45 stars against the crowd while three enthusiasts stayed within ±0.2.

What would you compare on Letterboxd? Critics against each other, your film club against the crowd, or something I haven't thought of? And if you got API access for a project, I'd like to hear what it was.


*I build it.

Top comments (0)