# Related titles

> Similar titles, the franchise, references to other films and mentions in them.

> Documentation index for agents: https://kinodata.space/en/llms.txt — the whole documentation in one file: https://kinodata.space/en/llms-full.txt

Request: `GET https://api.kinodata.space/v1.3/titles/{type}/{id}/relations`

The examples below use *The Lord of the Rings: The Fellowship of the Ring* (kp `328`), which has a franchise, similar titles and references. Relations come in four kinds:

- `similar`: similar titles;
- `related`: the franchise, meaning sequels, prequels, spin-offs and remakes. They come by release year, like a timeline;
- `reference`: films this title references;
- `referenced_in`: where this title is mentioned.

Without parameters you get four sections of 10 titles each. `relation=similar` gives a flat, pageable list. An item is the same card as in the [catalog](https://kinodata.space/en/docs/titles.md), and the same [filters and sorting](https://kinodata.space/en/docs/filters.md) work here.

When a title has no “similar” relations at all, `relation=similar` picks neighbours by its description: the same kind, the same genres, nearby years. Such a response carries `basis: "content"` and its `total` is `null`. These are neighbours, not recommendations; tell them apart from a regular list.

## Path parameters

- `type` (string, required) — The catalog the ID comes from: IMDb, Kinopoisk, TMDB (movie or series) or Kinorium.
  Values: `imdb`, `kp`, `tmdb`, `tmdb_tv`, `kinorium`.
- `id` (string, required) — The ID in that catalog. IMDb IDs are `tt` followed by digits (`tt1375666`); the others are digits (`447301`).

## Query parameters

- `relation` (csv) — Kinds of relation, comma-separated. One kind gives a flat, pageable list.
  Values: `similar`, `related`, `reference`, `referenced_in`.
  Default: all four. Example: `relation=related`.
- `subtype` (csv) — Narrows the franchise (`related`) to a kind of link.
  Values: `sequel`, `prequel`, `spinoff`, `parent`, `chronology`, `remake`, `original`, `version`.
  Example: `subtype=sequel`.
- `source` (enum) — Keep the relations this catalog provided.
  Values: `kinorium`, `kp`, `tmdb`.
  Example: `source=kp`.
- `filters and sort` — The catalog’s filters and sorting: `sort=-rating_imdb`, `votes_imdb.gte=100000`, `year.gte=2000`. Details in [Filters and sorting](https://kinodata.space/en/docs/filters.md).
- `fields` (csv) — Which item fields to return, as in the [catalog](https://kinodata.space/en/docs/titles.md). IDs always come back.
  Example: `fields=title,year`.
- `group` (enum) — Split the list into sections. `none` gives a flat list. How sections work is in [Lists and pagination](https://kinodata.space/en/docs/lists.md#sections).
  Values: `relation`, `none`.
  Default: `relation`.
- `lang` (ru | en) — Keep one language in the response. Without it, text fields come in `_ru` and `_en` pairs. More in [Response languages](https://kinodata.space/en/docs/languages.md).
  Example: `lang=en`.
- `limit` (integer) — How many items to return, a whole number from 1. With sections, per section, up to 50. In a flat list, up to 1000. Above the cap isn’t an error: the API lowers it and shows the value in `limit`.
  Default: 10 per section, 1000 in a flat list. Example: `limit=20`.
- `offset` (integer) — How many items to skip, a whole number from 0. Only in a flat list: with sections it returns `400`.
  Default: 0.

## Response fields

- `counts` (object) — How many relations of each kind: `similar`, `related`, `reference`, `referenced_in`. Doesn’t depend on `relation`, so you can label tabs with it. `source` and `subtype` narrow the counts too.
- `basis` (string) — `content` when similar titles were picked by description. A regular list has no such field.
- `items` (array) — Titles. With sections, sections with their own `relation`, labels, `total` and `items`.
  - `imdb_id`, `kp_id`, `tmdb_id`, `tmdb_tv_id`, `kinorium_id` (string | null) — The title’s catalog IDs. Always returned, even with `fields`.
  - `title_ru`, `title_en`, `title_original` (string | null) — Titles: Russian, English and in the original language.
  - `year` (integer | null) — Release year.
  - `release_date` (string | null) — First release date, `YYYY-MM-DD`.
  - `kind` (enum) — Kind of title: `movie`, `series`, `mini_series`, `tv_show`, `anime`, `cartoon`, `short`.
  - `poster_url_ru`, `poster_url_en` (string | null) — Poster for a Russian and an English storefront.
  - `posters_by_source` (object) — Each source’s poster: `kp`, `tmdb`, `imdb`, `kinorium`.
  - `rating_kp`, `rating_tmdb`, `rating_imdb`, `rating_kr`, `rating_letterboxd` (number | null) — Kinopoisk, TMDB, IMDb, Kinorium and Letterboxd ratings, 0–10 scale.
  - `votes_kp`, `votes_tmdb`, `votes_imdb` (integer | null) — Kinopoisk, TMDB and IMDb votes.
  - `countries` (array) — Countries: `code`, `name_ru`, `name_en`.
  - `genres` (array) — Genres: `slug`, `name_ru`, `name_en`.
  - `relation` (enum) — Kind of relation.
  - `subtype` (enum | null) — How two franchise titles are linked. `null` means the source didn’t say.
    Values: `sequel`, `prequel`, `spinoff`, `parent`, `chronology`, `remake`, `original`, `version`.
- `total`, `limit`, `offset`, `has_more` — Paging, as in [every list](https://kinodata.space/en/docs/lists.md#the-shape-of-a-list). With filters, `total` is `null`.

## Errors

| status | code | when |
|---|---|---|
| 400 | `invalid_request` | An unknown `relation`, `subtype`, `source` or `group`; an unknown filter or `sort` key; a parameter of another endpoint (such as `role` or `season`); `offset` together with sections. |
| 404 | `not_found` | No title found for this ID. |
| 401 | `unauthorized` | The `X-API-Key` header is missing, or the key is unknown or revoked. |
| 429 | `rate_limited` | The per-second rate limit or the daily quota is used up. |

Every code and what to do about it is on the [Errors](https://kinodata.space/en/docs/errors.md) page.

## Examples

### English only

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "relation=related" \
  --data-urlencode "limit=4" \
  --data-urlencode "fields=title,year" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/titles/kp/328/relations"
```

Response `200`:

```json
{
  "counts": {
    "reference": 3,
    "referenced_in": 555,
    "related": 11,
    "similar": 36
  },
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0077869",
      "kp_id": "5919",
      "tmdb_id": "123",
      "tmdb_tv_id": null,
      "kinorium_id": "71992",
      "title_en": "The Lord of the Rings",
      "year": 1978
    },
    {
      "imdb_id": "tt14358016",
      "kp_id": "4421491",
      "tmdb_id": null,
      "tmdb_tv_id": "123034",
      "kinorium_id": "2736565",
      "title_en": "The Fellowship of the Ring",
      "year": 1991
    },
    {
      "imdb_id": "tt0167261",
      "kp_id": "312",
      "tmdb_id": "121",
      "tmdb_tv_id": null,
      "kinorium_id": "139946",
      "title_en": "The Lord of the Rings: The Two Towers",
      "year": 2002
    },
    {
      "imdb_id": "tt0167260",
      "kp_id": "3498",
      "tmdb_id": "122",
      "tmdb_tv_id": null,
      "kinorium_id": "139945",
      "title_en": "The Lord of the Rings: The Return of the King",
      "year": 2003
    }
  ],
  "limit": 4,
  "offset": 0,
  "total": 11
}
```

### Sections

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "limit=1" \
  --data-urlencode "fields=title" \
  "https://api.kinodata.space/v1.3/titles/kp/328/relations"
```

Response `200`:

```json
{
  "counts": {
    "reference": 3,
    "referenced_in": 555,
    "related": 11,
    "similar": 36
  },
  "has_more": false,
  "items": [
    {
      "has_more": true,
      "items": [
        {
          "imdb_id": "tt0944947",
          "kp_id": "464963",
          "tmdb_id": null,
          "tmdb_tv_id": "1399",
          "kinorium_id": "406384",
          "title_ru": "Игра престолов",
          "title_en": "Game of Thrones"
        }
      ],
      "label_en": "Similar",
      "label_ru": "Похожие",
      "relation": "similar",
      "total": 36
    },
    {
      "has_more": true,
      "items": [
        {
          "imdb_id": "tt0077869",
          "kp_id": "5919",
          "tmdb_id": "123",
          "tmdb_tv_id": null,
          "kinorium_id": "71992",
          "title_ru": "Властелин колец",
          "title_en": "The Lord of the Rings"
        }
      ],
      "label_en": "Related",
      "label_ru": "Связанные",
      "relation": "related",
      "total": 11
    },
    {
      "has_more": true,
      "items": [
        {
          "imdb_id": "tt1375666",
          "kp_id": "447301",
          "tmdb_id": "27205",
          "tmdb_tv_id": null,
          "kinorium_id": "472809",
          "title_ru": "Начало",
          "title_en": "Inception"
        }
      ],
      "label_en": "Referenced in",
      "label_ru": "Упоминается в",
      "relation": "referenced_in",
      "total": 555
    },
    {
      "has_more": true,
      "items": [
        {
          "imdb_id": "tt0060196",
          "kp_id": "349",
          "tmdb_id": "429",
          "tmdb_tv_id": null,
          "kinorium_id": "56474",
          "title_ru": "Хороший, плохой, злой",
          "title_en": "The Good, the Bad and the Ugly"
        }
      ],
      "label_en": "References",
      "label_ru": "Отсылки к",
      "relation": "reference",
      "total": 3
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": 4
}
```

### Similar, filtered

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "relation=similar" \
  --data-urlencode "sort=-rating_imdb" \
  --data-urlencode "votes_imdb.gte=100000" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,rating_imdb" \
  "https://api.kinodata.space/v1.3/titles/kp/328/relations"
```

Response `200`:

```json
{
  "counts": {
    "reference": 3,
    "referenced_in": 555,
    "related": 11,
    "similar": 36
  },
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0944947",
      "kp_id": "464963",
      "tmdb_id": null,
      "tmdb_tv_id": "1399",
      "kinorium_id": "406384",
      "title_ru": "Игра престолов",
      "title_en": "Game of Thrones",
      "rating_imdb": 9.2
    },
    {
      "imdb_id": "tt11198330",
      "kp_id": "1316601",
      "tmdb_id": null,
      "tmdb_tv_id": "94997",
      "kinorium_id": "2241207",
      "title_ru": "Дом Дракона",
      "title_en": "House of the Dragon",
      "rating_imdb": 8.2
    },
    {
      "imdb_id": "tt1201607",
      "kp_id": "407636",
      "tmdb_id": "12445",
      "tmdb_tv_id": null,
      "kinorium_id": "442655",
      "title_ru": "Гарри Поттер и Дары Смерти: Часть II",
      "title_en": "Harry Potter and the Deathly Hallows: Part 2",
      "rating_imdb": 8.1
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}
```

### Picked by description

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "relation=similar" \
  --data-urlencode "limit=2" \
  --data-urlencode "fields=title,year" \
  "https://api.kinodata.space/v1.3/titles/kp/1385769/relations"
```

Response `200`:

```json
{
  "basis": "content",
  "counts": {
    "reference": 0,
    "referenced_in": 0,
    "related": 0,
    "similar": 0
  },
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt16968450",
      "kp_id": "4830353",
      "tmdb_id": "923939",
      "tmdb_tv_id": null,
      "kinorium_id": "7997366",
      "title_ru": "Чудесная история Генри Шугара",
      "title_en": "The Wonderful Story of Henry Sugar",
      "year": 2023
    },
    {
      "imdb_id": "tt1710308",
      "kp_id": "669362",
      "tmdb_id": null,
      "tmdb_tv_id": "31132",
      "kinorium_id": "543983",
      "title_ru": "Обычный мультик",
      "title_en": "Regular Show",
      "year": 2010
    }
  ],
  "limit": 2,
  "offset": 0,
  "total": null
}
```