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/ 

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' 

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 

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 

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 

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 

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 

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, } 

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 
$ 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 

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 
$ 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/ 

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, Source:https://dev.to/viktorhendelmann/how-to-scrape-letterboxd-with-python-rss-diaries-film-ratings-watchlists-and-a-member-vs-crowd-5d98

Related posts