# Связи

> Похожие тайтлы, франшиза, отсылки к другим фильмам и упоминания в них.

> Оглавление документации для агентов: https://kinodata.space/ru/llms.txt — вся документация одним файлом: https://kinodata.space/ru/llms-full.txt

Запрос: `GET https://api.kinodata.space/v1.3/titles/{type}/{id}/relations`

Примеры ниже — на «Властелине колец: Братство Кольца» (kp `328`): у него есть и франшиза, и похожие тайтлы, и отсылки. Связи бывают четырёх видов:

- `similar` — похожие тайтлы;
- `related` — франшиза: сиквелы, приквелы, спин-оффы, ремейки. Идут по годам выхода, как хронология;
- `reference` — на какие фильмы ссылается этот тайтл;
- `referenced_in` — где упоминается этот тайтл.

Без параметров приходят четыре раздела, по 10 тайтлов в каждом. `relation=similar` даёт плоский список с пагинацией. Элемент — та же карточка, что в [каталоге](https://kinodata.space/ru/docs/titles.md), и в связях работают те же [фильтры и сортировка](https://kinodata.space/ru/docs/filters.md).

Если у тайтла нет ни одной связи «похожее», `relation=similar` подбирает соседей по его описанию: тот же вид, те же жанры, близкие годы. Такой ответ несёт `basis: "content"`, а `total` у него `null`. Это соседство, а не рекомендация, — отличайте его от обычного списка.

## Параметры пути

- `type` (string, обязательный) — Каталог, из которого ID: IMDb, Кинопоиск, TMDB (фильм или сериал) или Кинориум.
  Значения: `imdb`, `kp`, `tmdb`, `tmdb_tv`, `kinorium`.
- `id` (string, обязательный) — ID в этом каталоге. У IMDb — `tt` и цифры (`tt1375666`), у остальных — цифры (`447301`).

## Параметры запроса

- `relation` (csv) — Виды связей, через запятую. Один вид даёт плоский список с пагинацией.
  Значения: `similar`, `related`, `reference`, `referenced_in`.
  По умолчанию: все четыре. Пример: `relation=related`.
- `subtype` (csv) — Сужает франшизу (`related`) до вида связи.
  Значения: `sequel`, `prequel`, `spinoff`, `parent`, `chronology`, `remake`, `original`, `version`.
  Пример: `subtype=sequel`.
- `source` (enum) — Оставить связи, которые дал этот каталог.
  Значения: `kinorium`, `kp`, `tmdb`.
  Пример: `source=kp`.
- `фильтры и sort` — Фильтры и сортировка каталога: `sort=-rating_imdb`, `votes_imdb.gte=100000`, `year.gte=2000`. Подробно — в [Фильтры и сортировка](https://kinodata.space/ru/docs/filters.md).
- `fields` (csv) — Какие поля элемента вернуть, как в [каталоге](https://kinodata.space/ru/docs/titles.md). ID приходят всегда.
  Пример: `fields=title,year`.
- `group` (enum) — Разбить список на разделы. `none` — плоский список. Как устроены разделы — в [Списки и пагинация](https://kinodata.space/ru/docs/lists.md#разделы).
  Значения: `relation`, `none`.
  По умолчанию: `relation`.
- `lang` (ru | en) — Оставить в ответе один язык. Без него текстовые поля приходят парами `_ru` и `_en`. Подробнее — [Языки ответа](https://kinodata.space/ru/docs/languages.md).
  Пример: `lang=en`.
- `limit` (integer) — Сколько элементов вернуть, целое от 1. В разделах — на каждый раздел, до 50. В плоском списке — до 1000. Больше потолка — не ошибка: API срежет до него и покажет в `limit`.
  По умолчанию: 10 в разделе, 1000 в плоском списке. Пример: `limit=20`.
- `offset` (integer) — Сколько элементов пропустить, целое от 0. Только в плоском списке: с разделами — `400`.
  По умолчанию: 0.

## Поля ответа

- `counts` (object) — Сколько связей каждого вида: `similar`, `related`, `reference`, `referenced_in`. От `relation` не зависит — по нему подписываются вкладки. `source` и `subtype` сужают и числа.
- `basis` (string) — `content`, если похожие подобраны по описанию. У обычного списка поля нет.
- `items` (array) — Тайтлы. В разделах — разделы со своими `relation`, подписями, `total` и `items`.
  - `imdb_id`, `kp_id`, `tmdb_id`, `tmdb_tv_id`, `kinorium_id` (string | null) — ID тайтла в каталогах. Приходят всегда, даже с `fields`.
  - `title_ru`, `title_en`, `title_original` (string | null) — Названия: на русском, на английском и на языке оригинала.
  - `year` (integer | null) — Год выхода.
  - `release_date` (string | null) — Первая дата выхода, `YYYY-MM-DD`.
  - `kind` (enum) — Вид тайтла: `movie`, `series`, `mini_series`, `tv_show`, `anime`, `cartoon`, `short`.
  - `poster_url_ru`, `poster_url_en` (string | null) — Постер для русской и английской витрины.
  - `posters_by_source` (object) — Постер каждого источника: `kp`, `tmdb`, `imdb`, `kinorium`.
  - `rating_kp`, `rating_tmdb`, `rating_imdb`, `rating_kr`, `rating_letterboxd` (number | null) — Оценки Кинопоиска, TMDB, IMDb, Кинориума и Letterboxd, шкала 0–10.
  - `votes_kp`, `votes_tmdb`, `votes_imdb` (integer | null) — Голоса Кинопоиска, TMDB и IMDb.
  - `countries` (array) — Страны: `code`, `name_ru`, `name_en`.
  - `genres` (array) — Жанры: `slug`, `name_ru`, `name_en`.
  - `relation` (enum) — Вид связи.
  - `subtype` (enum | null) — Чем связаны тайтлы франшизы. `null` — источник не указал.
    Значения: `sequel`, `prequel`, `spinoff`, `parent`, `chronology`, `remake`, `original`, `version`.
- `total`, `limit`, `offset`, `has_more` — Пагинация — как в [любом списке](https://kinodata.space/ru/docs/lists.md#форма-списка). С фильтрами `total` — `null`.

## Ошибки

| статус | код | когда |
|---|---|---|
| 400 | `invalid_request` | Неизвестный `relation`, `subtype`, `source` или `group`; неизвестный фильтр или ключ `sort`; параметр другого эндпоинта (например, `role` или `season`); `offset` вместе с разделами. |
| 404 | `not_found` | Тайтл с таким ID не найден. |
| 401 | `unauthorized` | Нет заголовка `X-API-Key`, ключ неизвестен или отозван. |
| 429 | `rate_limited` | Исчерпан предел в секунду или квота на сутки. |

Все коды и что с ними делать — на странице [Ошибки](https://kinodata.space/ru/docs/errors.md).

## Примеры

### Франшиза

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

Ответ `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_ru": "Властелин колец",
      "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_ru": "Хранители",
      "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_ru": "Властелин колец: Две крепости",
      "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_ru": "Властелин колец: Возвращение короля",
      "title_en": "The Lord of the Rings: The Return of the King",
      "year": 2003
    }
  ],
  "limit": 4,
  "offset": 0,
  "total": 11
}
```

### Разделы

```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"
```

Ответ `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
}
```

### Похожие с фильтром

```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"
```

Ответ `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
}
```

### Подбор по описанию

```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"
```

Ответ `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
}
```

### Только английский

```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"
```

Ответ `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
}
```