# Filmaffinity — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search FilmAffinity's film database by title, director, genre, year, and more. Retrieve detailed movie information including cast, crew, synopsis, ratings, and user reviews. Access top-rated lists, box office rankings, theatrical and streaming releases, and full filmographies for cast and crew members.

**Category:** Entertainment | **Website:** [filmaffinity.com/](https://filmaffinity.com/) | **Docs:** [parse.bot/marketplace/3d87e305-0e06-482a-9c71-a7d9748c1915/filmaffinity-com-api](https://parse.bot/marketplace/3d87e305-0e06-482a-9c71-a7d9748c1915/filmaffinity-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-filmaffinity-com-api-3d87e305/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### advanced_search

Perform an advanced search with multiple filters including search type, year range, country, and genre. Supports searching by title or director name. Without a types filter, defaults to title search.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country` | string | No | Country code filter (e.g. 'US') |
| `from_year` | string | No | Filter from year (e.g. '2005') |
| `genre` | string | No | Genre code filter |
| `query` | string | Yes | Search keyword or phrase |
| `to_year` | string | No | Filter to year (e.g. '2015') |
| `types` | string | No | Comma-separated search types to filter by: 'title', 'director', or 'title,director' |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-filmaffinity-com-api-3d87e305/advanced_search \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"<string>","from_year":"<string>","genre":"<string>","query":"<string>","to_year":"<string>","types":"<string>"}'
```

### get_box_office

Get current US weekly box office rankings. Returns rank, title, genre, weeks in theaters, weekend gross, and total gross for each entry. Data is updated weekly.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-filmaffinity-com-api-3d87e305/get_box_office \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_movie_credits

Retrieve the full cast and crew credits for a movie, organized by role category (director, screenwriter, cast, music, cinematography, producer). Each person entry includes name and profile URL.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `film_id` | string | Yes | The numeric film ID from FilmAffinity (e.g. '971380') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-filmaffinity-com-api-3d87e305/get_movie_credits \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"film_id":"<string>"}'
```

### get_movie_details

Retrieve full details of a specific movie or TV show by its FilmAffinity film ID. Includes title, year, cast, director, synopsis, rating, votes, genre, and critics reviews. The film_id is obtainable from search_movies, get_top_films, or advanced_search results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `film_id` | string | Yes | The numeric film ID from FilmAffinity (e.g. '971380') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-filmaffinity-com-api-3d87e305/get_movie_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"film_id":"<string>"}'
```

### get_movie_rating

Get the FilmAffinity rating, vote count, and vote distribution for a movie. The distribution object maps score values (1-10) to percentage strings showing vote breakdown.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `film_id` | string | Yes | The numeric film ID from FilmAffinity (e.g. '971380') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-filmaffinity-com-api-3d87e305/get_movie_rating \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"film_id":"<string>"}'
```

### get_movies_by_year

List top-rated movies released in a specific year. Returns films from FilmAffinity's top-rated list filtered to the given year, ordered by rating descending.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | string | Yes | The year to filter by (e.g. '2023', '1972') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-filmaffinity-com-api-3d87e305/get_movies_by_year \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<string>"}'
```

### get_person_filmography

Retrieve filmography for a specific person by searching their name on FilmAffinity and filtering by role. Returns the list of films the person participated in for the specified role. If the person is not found by name search, falls back to advanced search.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Person name to search for (e.g. 'Tom Hanks', 'Christopher Nolan') |
| `role` | string | No | Role filter for filmography |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-filmaffinity-com-api-3d87e305/get_person_filmography \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"<string>","role":"<string>"}'
```

### get_top_films

Retrieve ranked lists of top-rated movies with optional filters for genre, country, year range, and streaming platform. Returns paginated results using offset. Each page contains up to 30 films.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country` | string | No | Country code filter |
| `from_offset` | integer | No | Starting offset for pagination |
| `from_year` | string | No | Filter from year (e.g. '2000') |
| `genre` | string | No | Genre code filter (e.g. 'TH' for thriller) |
| `list_type` | string | No | List type identifier (e.g. 'top_1000_fa') |
| `platform` | string | No | Streaming platform code filter |
| `to_year` | string | No | Filter to year (e.g. '2023') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-filmaffinity-com-api-3d87e305/get_top_films \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"<string>","from_offset":"<integer>","from_year":"<string>","genre":"<string>","list_type":"<string>","platform":"<string>","to_year":"<string>"}'
```

### get_us_releases

Get theatrical or streaming releases in the US. Lists recently released or upcoming movies for the specified platform type.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `media_type` | string | No | Type of release to retrieve |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-filmaffinity-com-api-3d87e305/get_us_releases \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media_type":"<string>"}'
```

### get_user_reviews

Retrieve user reviews for a movie. Reviews are sourced from the Spanish-language version of FilmAffinity where user reviews are available. Returns paginated results with review title, text, author, rating, date, and helpfulness.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `film_id` | string | Yes | The numeric film ID from FilmAffinity (e.g. '971380') |
| `page` | integer | No | Page number for pagination |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-filmaffinity-com-api-3d87e305/get_user_reviews \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"film_id":"<string>","page":"<integer>"}'
```

### search_movies

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.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword or phrase (e.g. 'inception', 'the godfather') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-filmaffinity-com-api-3d87e305/search_movies \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```