FilmAffinity APIfilmaffinity.com ↗
Access FilmAffinity's movie database: search titles, get ratings with vote distribution, user reviews, credits, box office rankings, and streaming releases via 11 endpoints.
What is the FilmAffinity API?
The FilmAffinity API exposes 11 endpoints covering the full FilmAffinity movie database — from title search and detailed metadata to critic and user reviews, vote distribution, and US box office rankings. The get_movie_details endpoint alone returns over a dozen fields including synopsis, critics_reviews, cast, and rating. get_person_filmography lets you pull a director or actor's complete career list filtered by role.
curl -X GET 'https://api.parse.bot/scraper/aa17d4b1-0343-48ea-9b8c-4cdad91e1ed6/search_movies?query=inception' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace filmaffinity-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: FilmAffinity SDK — search, drill into details, explore credits and reviews."""
from parse_apis.filmaffinity_api import FilmAffinity, Role, MediaType, FilmNotFound
client = FilmAffinity()
# Search for films by title — single-page results, capped at 5
for film in client.films.search(query="inception", limit=5):
print(film.title, film.year, film.film_id)
# Drill into the first result's full details
summary = client.films.search(query="inception", limit=1).first()
if summary:
detail = summary.details()
print(detail.title, detail.rating, detail.synopsis[:100])
# Get a film directly by ID and explore sub-resources
film = client.films.get(film_id="971380")
print(film.title, film.year, film.rating)
# Credits for an instance — organized by role
creds = film.credits()
for person in creds.cast[:3]:
print(person.name, person.url)
# User reviews via sub-resource pagination
for review in film.reviews.list(limit=3):
print(review.author, review.rating, review.title)
# Filmography lookup with the Role enum
filmography = client.films.filmography(name="Christopher Nolan", role=Role.DIRECTOR)
print(filmography.person, filmography.total)
for item in filmography.items[:3]:
print(item.title, item.year)
# Box office — current US weekly rankings
for entry in client.films.box_office(limit=3):
print(entry.rank, entry.title, entry.weekend_gross)
# Releases filtered by platform enum
for release in client.films.releases(media_type=MediaType.NETFLIX, limit=3):
print(release.title, release.release_date)
# Typed error handling — catch FilmNotFound on a bad ID
try:
client.films.get(film_id="0000000")
except FilmNotFound as exc:
print(f"not found: {exc.film_id}")
print("exercised: films.search / films.get / summary.details / film.credits / film.reviews.list / films.filmography / films.box_office / films.releases")Full-text search for movies and TV shows by title. Returns a list of matching results with basic metadata (film_id, title, year, director, cast). Rating and votes are not populated in search results — use get_movie_details or get_movie_rating for those. Pagination is not supported; all matching results are returned in a single page.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search keyword or phrase (e.g. 'inception', 'the godfather') |
{
"type": "object",
"fields": {
"items": "array of movie summary objects with film_id, title, year, director, cast, rating, votes, url",
"total": "integer count of results returned"
}
}About the FilmAffinity API
Search and Discovery
The search_movies endpoint accepts a free-text query and returns an array of matching films, each with film_id, title, year, director, cast, rating, and votes. For more targeted lookups, advanced_search adds genre, country, from_year, to_year, and a types parameter that lets you scope the query to title, director, or both simultaneously. get_movies_by_year narrows results to a single calendar year, returning FilmAffinity's top-rated films for that period.
Film Detail and Ratings
get_movie_details returns the canonical record for a film: title, year, synopsis, cast array, director array, rating out of 10, votes, plus a critics_reviews array with individual text, author, and sentiment fields. If you only need rating data, get_movie_rating returns a focused payload that includes a distribution object mapping each score (1–10) to its percentage share of votes — useful for visualizing audience polarization without fetching the full detail record.
Credits, Reviews, and Filmographies
get_movie_credits returns a structured credits object organized by role — director, screenwriter, cast, music, cinematography, and producer — as separate arrays under each key. User opinions are available through get_user_reviews, which returns paginated review objects with title, text, author, rating, date, and helpfulness. get_person_filmography takes a person name and optional role filter and resolves to the matched person's full list of films.
Charts, Box Office, and Releases
get_top_films supports ranked list retrieval with filters for genre, country, from_year, to_year, and platform, paginated via from_offset. get_box_office returns the current US weekly chart with rank, genre, weeks, weekend_gross, and total_gross per entry. get_us_releases lists recent and upcoming US theatrical and streaming titles, accepting a media_type parameter to filter by service — netflix, hbo, amazon, disney, apple, or theatrical.
The FilmAffinity API is a managed, monitored endpoint for filmaffinity.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when filmaffinity.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official filmaffinity.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a film recommendation engine seeded by FilmAffinity ratings and vote distribution from
get_movie_rating - Track US box office performance week-over-week using
get_box_officefields likeweekend_grossandtotal_gross - Aggregate critic sentiment across films by parsing the
sentimentfield incritics_reviewsfromget_movie_details - Populate a cast or crew profile page using
get_person_filmographyfiltered by role (director, actor, screenwriter, etc.) - Monitor new streaming arrivals per platform using
get_us_releaseswith themedia_typeparameter - Compare top-rated films across decades by combining
get_top_filmswithfrom_yearandto_yearfilters - Analyze genre-specific audience ratings by cross-referencing
get_top_filmsgenre codes with vote data
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does FilmAffinity have an official public developer API?+
What does `get_movie_credits` return that `get_movie_details` doesn't?+
get_movie_details returns a flat cast array and a director array. get_movie_credits expands this into a structured credits object with separate arrays for screenwriter, music, cinematography, and producer in addition to director and cast, making it the right endpoint when you need full production crew data.Are user reviews available in languages other than Spanish?+
get_user_reviews endpoint sources reviews from the Spanish-language version of FilmAffinity, where user reviews are published. English-language user reviews from other regional versions of the site are not currently returned. You can fork the API on Parse and revise it to target a different regional endpoint if needed.Can I retrieve individual episode data or season listings for TV shows?+
title, year, rating, and synopsis — but episode-level or season-level breakdowns are not exposed by any of the 11 endpoints. You can fork the API on Parse and revise it to add an endpoint targeting series episode data.How does pagination work across endpoints that return lists?+
get_user_reviews uses a page integer parameter. get_top_films uses from_offset — an integer specifying the starting position in the ranked list. Other list endpoints like search_movies and advanced_search return a total count alongside the items array, but do not currently expose a pagination parameter to fetch beyond the first result page.