# Movies & TV

Films, television series, seasons, episodes, and the people credited on them. Built on the Wikidata spine (CC0) with IMDb, TMDB, TVmaze, TheTVDB, and EIDR cross-ids, Wikipedia poster pointers, and Wikipedia summaries.

MCP: `lookup_imdb`, `resolve_title`, `search_titles`, `get_title`, `get_person`, `search_people`, `get_person_credits`, `get_episodes`, `get_seasons`, `lookup_wikidata`

## Lookup by IMDb id

```http
GET /v1/imdb/{imdb_id}
```

`tt…` resolves to a title, `nm…` to a person. Full IMDb URLs are accepted. Response is `{ "entity_type": "title", "title": {…} }` or `{ "entity_type": "person", "person": {…} }`. Use this whenever you have an IMDb id. Do not pass an IMDb id as `q`.

Check record: `tt0111161` (The Shawshank Redemption) returns `wikidata_qid: "Q172241"` and a director credit for Frank Darabont.

## Get a title

```http
GET /v1/titles/{id}
```

`id` is `fds_fi_…` (film), `fds_tv_…` (series), `fds_se_…` (season), or `fds_ep_…` (episode). Ids are derived from the Wikidata QID, so they are stable across releases. A retired id **301**s to the survivor (Wikidata redirect / merge).

## Search

```http
GET /v1/titles/search?q=breaking+bad&kind=series
```

| Query | Notes |
|---|---|
| `q` | Title prefix first, then trigram. Required unless `kind` or a year filter is set |
| `kind` | `film` · `series` · `season` · `episode` |
| `year` | Exact release year |
| `year_from` / `year_to` | Inclusive range |
| `limit` | Default 20, max 50 |
| `cursor` | `next_cursor` from the previous page (browse mode only) |

Ordered by popularity (Wikipedia sitelink count plus cross-id presence). Episodes rank low; pass `kind=episode` to browse them.

## Resolve a title

```http
POST /v1/match
{ "title": "Shawshank Redemption", "year": 1994, "dataset": "movies_tv" }
```

Same match route as books and food. Returns films and series only. A valid `imdb_id` short-circuits to one `exact_imdb` candidate. Exact normalized title plus matching year scores `0.98`; fuzzy hits carry `match_method: "fuzzy_title"`. Read `candidates[0]`. `POST /v1/titles/match` is an alias; `dataset` is inferred when `imdb_id` or a film/series `kind` is present.

## Episodes and seasons

```http
GET /v1/titles/{series_or_season_id}/episodes?season=1
GET /v1/titles/{series_id}/seasons
```

Episodes are ordered by `season_number`, `episode_number`, then air date. Episode coverage follows Wikidata: complete for major series, sparse for the long tail. The site lists **seasons under a series** and episodes under a season. Season/episode `image` may be a Wikipedia pageimage or a TVmaze still (`tvmaze_display`, site identify only).

## People

```http
GET /v1/people/{id}
GET /v1/people/search?q=darabont
GET /v1/people/{id}/credits?role=director
GET /v1/people/popular
```

`id` is `fds_pe_…`. `known_for[]` on the person object holds the top titles by popularity; `/credits` returns the full filmography with `role` and `character`.

## Popular

```http
GET /v1/titles/popular?kind=film&limit=24
```

## Title object

```json
{
  "id": "fds_fi_…",
  "schema_version": "movies_tv.v1",
  "kind": "film",
  "title": "The Shawshank Redemption",
  "original_title": null,
  "aliases": ["Shawshank Redemption"],
  "description": "1994 film directed by Frank Darabont",
  "year": 1994,
  "release_date": "1994-09-23",
  "runtime_minutes": 142,
  "genres": ["drama film", "prison film"],
  "countries": ["United States of America"],
  "languages": ["English"],
  "production_companies": ["Castle Rock Entertainment"],
  "credits": [
    { "person_id": "fds_pe_…", "qid": "Q295445", "name": "Frank Darabont", "role": "director", "character": null, "ord": 0 },
    { "person_id": "fds_pe_…", "qid": "Q95048", "name": "Tim Robbins", "role": "cast", "character": "Andy Dufresne", "ord": 0 }
  ],
  "imdb_id": "tt0111161",
  "wikidata_qid": "Q172241",
  "identifiers": [
    { "namespace": "wikidata", "value": "Q172241" },
    { "namespace": "imdb", "value": "tt0111161" },
    { "namespace": "tmdb_movie", "value": "278" }
  ],
  "image": {
    "url": "/media/titles/fds_fi_…/poster.400.jpg",
    "large_url": "/media/titles/fds_fi_…/poster.1080.jpg",
    "source": "wikipedia",
    "license": "page_image",
    "attribution_url": "https://en.wikipedia.org/wiki/File:ShawshankRedemptionMoviePoster.jpg"
  },
  "summary": {
    "text": "Two imprisoned men bond over a number of years, finding solace and eventual redemption through acts of common decency.",
    "license": "CC-BY-SA-4.0",
    "source": "wikipedia",
    "attribution_url": "https://en.wikipedia.org/wiki/The_Shawshank_Redemption",
    "revision": "123"
  },
  "wikipedia": { "title": "The Shawshank Redemption", "url": "https://en.wikipedia.org/wiki/The_Shawshank_Redemption" },
  "popularity_score": 112,
  "provenance": { "source": "wikidata", "license": "CC0", "snapshot": "2026-09-01", "modified_at": "2026-08-30T12:01:44Z" },
  "release": "2026-10.1"
}
```

Series add `counts: { "seasons": 5, "episodes": 62 }` and `broadcasters[]`. Seasons and episodes add `series: { id, qid, title }`, and episodes add `season: { id, qid, number }`, `season_number`, and `episode_number`.

Credit roles: `director`, `creator`, `writer`, `cast` (first 40, with `character`), `producer`, `composer`, `cinematographer`, `editor`.

## Summaries

`summary` is the English Wikipedia REST extract. License is **CC BY-SA 4.0**. If you show `summary.text`, attribute Wikipedia and share-alike; `attribution_url` is the article. `wikipedia` is the sitelink even when no extract was stored.

## Images

Title `image` is a pointer. Popular film/series posters we already chose are copied to `GET /media/titles/{id}/poster.400.jpg` (and `.1080.jpg` when the source is wide enough). `image.url` is the 400; `image.large_url` is the 1080 when it exists. Prefix `/media/` with `https://api.fulldatasets.com`. Preference order: Wikidata **P3383** (film poster on Commons), then the English Wikipedia infobox image (`pageimages` with `pilicense=any`). Generic Commons **P18** stills and logos are dropped — those are not posters. `page_image` and `tmdb_display` bytes stay site-only and out of dumps.

- `source: "wikimedia_commons"` / `license: "per_file"` — Commons file. Read the license on `attribution_url` before reuse.
- `source: "wikipedia"` / `license: "page_image"` — Wikipedia infobox art, often a fair-use theatrical poster. **Display and identify only.** Do not put these in a dump or other product.
- `source: "posterflix"` / `license: "tmdb_display"` — TMDB poster via Posterflix when Commons and Wikipedia have no poster. **Identify on the site only.** Do not dump or redistribute.
- `source: "tvmaze"` / `license: "tvmaze_display"` — TVmaze season poster or episode still. **Identify on the site only.**

`image` is still `null` when no poster-shaped Wikipedia image, TVmaze still, or Posterflix match is found. Person portraits stay on Commons P18.

## Sources

| Data | Source | License |
|---|---|---|
| Titles, people, credits, cross-ids, dates | Wikidata | CC0 |
| Poster pointers | Wikidata P3383 (Commons), Wikipedia page image, Posterflix/TMDB, or TVmaze | Per file, `page_image`, `tmdb_display`, or `tvmaze_display` (identify only) |
| Article links | Wikipedia (English) | CC BY-SA 4.0 (sitelink) |
| Short extracts | Wikipedia REST summary | CC BY-SA 4.0 (`summary.license` + `summary.attribution_url` per row) |

Only allowlisted Wikidata properties are ingested. Wikidata items are refreshed daily from RecentChanges; deleted items are dropped at the next release.