filmaffinity.com 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.
curl -X GET 'https://api.parse.bot/scraper/aa17d4b1-0343-48ea-9b8c-4cdad91e1ed6/search_movies?query=inception' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for movies and TV shows by title. Returns a list of matching results with basic metadata. Uses URL-encoded query parameters to handle special characters and multi-word queries.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search keyword or phrase (e.g. 'inception', 'the godfather') |
{
"type": "object",
"fields": {
"items": "array of movie objects with film_id, title, year, director, cast, rating, votes, url",
"total": "integer count of results returned"
},
"sample": {
"data": {
"items": [
{
"url": "https://www.filmaffinity.com/us/film971380.html",
"cast": [
"Leonardo DiCaprio",
"Joseph Gordon-Levitt",
"Elliot Page"
],
"year": "2010",
"title": "Inception",
"votes": null,
"rating": null,
"film_id": "971380",
"director": "Christopher Nolan"
}
],
"total": 5
},
"status": "success"
}
}About the filmaffinity.com 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.
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.
- 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 | 250 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.