# Карточка тайтла

> Всё о фильме или сериале одним запросом: названия, описания, оценки, даты, награды, медиа и состав.

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

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

Карточка открывается по ID любого из пяти каталогов: `/titles/kp/447301` и `/titles/imdb/tt1375666` возвращают одно и то же.

Целиком карточка — до 22 блоков и около 26 КБ, со сжатием около 8 КБ. Если нужна часть, перечислите блоки в `fields`: так ответ меньше, а разбирать его проще. Блок `ids` приходит всегда.

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

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

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

- `fields` (csv) — Какие блоки вернуть: `fields=title,ratings`. Со знаком `-` — какие убрать: `fields=-akas,-tags`. Смешивать нельзя. По умолчанию — все блоки.
  Значения: `ids`, `meta`, `title`, `type`, `synopsis`, `release`, `ratings`, `finance`, `awards`, `countries`, `classification`, `series`, `media`, `genres`, `companies`, `akas`, `tags`, `watch`, `parental`, `credits_top`, `franchise`, `counts`.
  Пример: `fields=title,ratings`.
- `lang` (ru | en) — Оставить в ответе один язык. Без него текстовые поля приходят парами `_ru` и `_en`. Подробнее — [Языки ответа](https://kinodata.space/ru/docs/languages.md).

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

- `ids` (object) — ID тайтла во всех каталогах и ссылки на его страницы. Приходит всегда, даже если его нет в `fields`.
  - `imdb_id` (string | null) — ID в IMDb.
  - `kp_id` (string | null) — ID на Кинопоиске.
  - `tmdb_id` (string | null) — ID фильма в TMDB.
  - `tmdb_tv_id` (string | null) — ID сериала в TMDB. Заполнено не больше одного из `tmdb_id` и `tmdb_tv_id`.
  - `kinorium_id` (string | null) — ID на Кинориуме.
  - `urls` (object) — Ссылки на страницы тайтла: `imdb`, `kp`, `tmdb`, `kinorium`. С `lang=en` ссылка на Кинориум ведёт на `en.kinorium.com`.
- `meta` (object) — Служебные сведения о карточке.
  - `updated_at` (string) — Когда данные тайтла последний раз обновлялись, ISO 8601 в UTC.
- `title` (object) — Названия.
  - `title_ru` (string | null) — Название на русском.
  - `title_en` (string | null) — Английское название. Только настоящее: оригинальное название неанглоязычного фильма или транслитерация сюда не попадают, тогда `null`.
  - `title_original` (string | null) — Название на языке оригинала.
- `type` (object) — Вид и статус тайтла.
  - `kind` (enum) — Вид тайтла.
    Значения: `movie`, `series`, `mini_series`, `tv_show`, `anime`, `cartoon`, `short`.
  - `is_series` (boolean) — Многосерийный ли тайтл.
  - `status` (enum) — Статус выхода. Все значения — в `/enums`, набор `statuses`.
    Значения: `released`, `ended`, `returning_series`, `in_production`, `post_production`, `in_development`, `planned`, `canceled`.
  - `kind_label_ru`, `kind_label_en` (string) — Подпись вида: «Фильм» / «Movie».
  - `status_label_ru`, `status_label_en` (string) — Подпись статуса: «Вышел» / «Released».
- `synopsis` (object) — Описания и слоганы. Каждый текст — из своего источника, а не перевод соседнего.
  - `overview_ru`, `overview_en` (string | null) — Описание сюжета.
  - `short_overview_ru`, `short_overview_en` (string | null) — Описание в одну-две фразы.
  - `tagline_ru`, `tagline_en` (string | null) — Слоган.
  - `overview_alter_ru`, `overview_alter_en` (string | null) — Второе описание из другого источника, если оно отличается от первого.
- `release` (object) — Год, длительность и даты выхода.
  - `year` (integer | null) — Год выхода.
  - `runtime` (integer | null) — Длительность в минутах.
  - `releases` (array) — Даты выхода по регионам. Каждая дата стоит один раз: если цифровой релиз в США совпал с мировым, он только в `world`.
    - `region` (string) — Регион: `world` — самая ранняя дата в мире, `us` — США, `ru` — Россия.
    - `dates` (array) — Даты в регионе: `type` и `date`. Типы: `premiere` — премьера, `release` — выход в прокат, `digital` — цифровой релиз; подписи — в `/enums`, набор `title_release_types`. Дата — `YYYY-MM-DD`.
- `ratings` (object) — Оценки по источникам. Общего балла нет намеренно: у источников разные шкалы и аудитории.
  - `sources` (object) — Оценки по источникам: ключ — источник (`imdb`, `kp`, `tmdb`, `kinorium`, `letterboxd`, `rt`, `metacritic`, `critics`, `cr`), значение — `value`, `votes`, `scale` (10 или 100), `kind: "critics"` у оценок критиков и `url` страницы. У Кинориума ещё `distribution` — сколько зрителей поставили каждую оценку от 1 до 10; Кинориум считает её отдельно, поэтому сумма не совпадает с `votes`. Подписи источников — в `/enums`, набор `rating_sources`. Источника нет — нет ключа.
  - `votes_total` (integer | null) — Голоса Кинопоиска, IMDb и TMDB вместе.
  - `divergence_kp_imdb` (number | null) — На сколько расходятся оценки Кинопоиска и IMDb, по модулю.
  - `popularity` (number | null) — Индекс популярности TMDB. Это не сумма голосов.
- `finance` (object) — Деньги, в долларах США.
  - `budget` (integer | null) — Бюджет.
  - `box_office_us` (integer | null) — Сборы в США.
  - `revenue_world` (integer | null) — Сборы в мире.
- `awards` (object) — Награды: итоги и разбор по церемониям.
  - `wins_imdb`, `nominations_imdb` (integer | null) — Победы и все номинации, включая выигранные, по данным IMDb, по всем премиям мира.
  - `oscars_won`, `oscars_nominated` (integer | null) — «Оскары»: победы и все номинации, включая выигранные.
  - `wins_ceremonies`, `nominations_ceremonies` (integer) — Победы и все номинации по церемониям из `ceremonies`.
  - `summary_kinorium_ru` (string | null) — Сводка Кинориума по церемониям: «Оскар: 4/8; Британская академия: 5/10…».
  - `summary_imdb_en` (string | null) — Сводка IMDb: «Won 4 Oscars. 160 wins & 220 nominations total». Это другой текст, а не перевод сводки Кинориума.
  - `ceremonies` (array) — Церемонии по престижу, «Оскар» первым.
    - `slug` (string | null) — Код церемонии: `oscar`, `bafta`, `golden_globe`…
    - `ceremony_ru`, `ceremony_en` (string) — Название церемонии.
    - `icon` (string | null) — Путь к иконке церемонии на `api.kinodata.space`: золотая при победе, серая при номинации.
    - `won` (boolean) — Есть ли хоть одна победа.
    - `wins`, `nominations` (integer) — Победы и все номинации, включая выигранные.
    - `years` (array) — Годы церемоний.
    - `items` (array) — Категории: `category_ru`, `category_en`, `won`, `year`.
- `countries` (array) — Страны производства: `code` (ISO 3166-1, строчными), `name_ru`, `name_en`.
- `classification` (object) — Возраст и язык.
  - `age_limit` (integer | null) — Российский возрастной ценз: 0, 6, 12, 16 или 18.
  - `mpaa` (string | null) — Американский сертификат: `G`, `PG`, `PG-13`, `R`, `NC-17` или `TV-*`.
  - `original_language` (string | null) — Язык оригинала, ISO 639-1.
  - `is_adult` (boolean) — Контент для взрослых.
- `series` (object) — Сериал. У фильма все поля `null`.
  - `seasons_total`, `episodes_total` (integer | null) — Сезонов и серий.
  - `start_year`, `end_year` (integer | null) — Годы выхода. У идущего сериала `end_year` — `null`.
- `media` (object) — Постеры, задник, трейлеры и саундтрек. Остальные кадры и видео — в `/titles/{type}/{id}/media`.
  - `poster_url_ru`, `poster_url_en` (string | null) — Постер для русской и английской витрины. Английский — с надписями на английском, нет такого — `null`.
  - `poster_source_ru`, `poster_source_en` (string | null) — Откуда постер: `kp`, `tmdb`, `imdb`, `kinorium`.
  - `posters_by_source` (object) — Постер каждого источника: `kp`, `tmdb`, `imdb`, `kinorium`.
  - `backdrop_url` (string | null) — Широкий кадр для фона.
  - `poster_animated` (string) — Анимированный постер Кинориума — ролик mp4 до 7 МБ. Есть примерно у каждого десятого популярного тайтла; когда его нет, нет и ключа. Показывайте в `<video autoplay muted loop playsinline>` и грузите по требованию.
  - `trailers` (array) — Трейлеры: `url` и `youtube_id`, `language`, `runtime_sec`, `thumbnail_url`, `preview_url`, `kind` с подписями. Все видео — в `/media`.
  - `soundtrack` (object | null) — Альбом саундтрека: `name` и `url` в Apple Music.
- `genres` (array) — Жанры: `slug`, `name_ru`, `name_en`.
- `companies` (array) — Компании: `name`, `slug` и роль `kind` — `production`, `studio`, `network`, `special_effects`, `distributor_theatrical`, `distributor_online`, `dubbing`.
- `akas` (array) — Альтернативные названия: `title`, `regions` (коды стран), `source` и `language`, если язык известен.
- `tags` (array) — Метки Кинориума: `kind` (`adjective` — настроение, `keyword` — ключевое слово, `subgenre` — поджанр) с подписями, `tag_ru`, `tag_en`.
- `watch` (array) — Где смотреть и что почитать, по возрастанию `rank`: `url`, `host` и вид сайта `kind` с подписями — онлайн-кинотеатр, рейтинг, официальный сайт, энциклопедия… Все виды — в `/enums`, набор `site_kinds`.
- `parental` (array) — Родительский гид по категориям: `category`, `severity` (`mild`, `moderate`, `severe`), подписи и `source`.
- `credits_top` (array) — Режиссёры и главные актёры, готовые к показу. Полный состав — в `/titles/{type}/{id}/cast`.
  - `imdb_id` (string | null) — ID в IMDb.
  - `kp_id` (string | null) — ID на Кинопоиске.
  - `tmdb_id` (string | null) — ID человека в TMDB.
  - `kinorium_id` (string | null) — ID на Кинориуме.
  - `name_ru`, `name_en` (string | null) — Имя.
  - `photo_url` (string | null) — Фото.
  - `role` (enum) — Роль. Все значения — в `/enums`, набор `credit_roles`.
  - `role_label_ru`, `role_label_en` (string) — Подпись роли: «Режиссёр» / «Director».
  - `character_ru`, `character_en` (string | null) — Персонаж у актёра.
- `franchise` (object) — Франшиза: `name`, `poster_url` и `size` — сколько в ней тайтлов. Блок есть только у тайтлов из франшизы. Состав франшизы — в `/titles/{type}/{id}/relations?relation=related`.
- `counts` (object) — Сколько чего на подресурсах: `cast`, `images`, `videos`, `facts`, `faq`, `quotes`, `episodes`, `seasons`, `relations`. По ним видно, за чем стоит идти отдельным запросом.

## Ошибки

| статус | код | когда |
|---|---|---|
| 400 | `invalid_request` | Неизвестный `type`, ID не в формате каталога, неизвестный блок в `fields` или смешаны оба режима `fields`, `lang` не `ru` и не `en`; другой параметр (например, `limit`) — карточка принимает только `fields` и `lang`. |
| 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 "fields=title,synopsis" \
  "https://api.kinodata.space/v1.3/titles/kp/447301"
```

Ответ `200`:

```json
{
  "ids": {
    "imdb_id": "tt1375666",
    "kp_id": "447301",
    "tmdb_id": "27205",
    "tmdb_tv_id": null,
    "kinorium_id": "472809",
    "urls": {
      "imdb": "https://www.imdb.com/title/tt1375666/",
      "kinorium": "https://ru.kinorium.com/472809/",
      "kp": "https://www.kinopoisk.ru/film/447301/",
      "tmdb": "https://www.themoviedb.org/movie/27205"
    }
  },
  "title": {
    "title_ru": "Начало",
    "title_en": "Inception",
    "title_original": "Inception"
  },
  "synopsis": {
    "tagline_ru": "Твой разум – место преступления",
    "tagline_en": "Your mind is the scene of the crime.",
    "overview_ru": "Кобб — талантливый вор, лучший из лучших в опасном искусстве извлечения: он крадет ценные секреты из глубин подсознания во время сна, когда человеческий разум наиболее уязвим. Редкие способности Кобба сделали его ценным игроком в привычном к предательству мире промышленного шпионажа, но они же превратили его в извечного беглеца и лишили всего, что он когда-либо любил. И вот у Кобба появляется шанс исправить ошибки. Его последнее дело может вернуть все назад, но для этого ему нужно совершить невозможное — инициацию. Вместо идеальной кражи Кобб и его команда спецов должны будут провернуть обратное. Теперь их задача — не украсть идею, а внедрить ее. Если у них получится, это и станет идеальным преступлением. Но никакое планирование или мастерство не могут подготовить команду к встрече с опасным противником, который, кажется, предугадывает каждый их ход. Врагом, увидеть которого мог бы лишь Кобб.",
    "overview_en": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is offered a chance to regain his old life as payment for a task considered to be impossible: \"inception\", the implantation of another person's idea into a target's subconscious.",
    "short_overview_en": "A thief who steals corporate secrets through the use of dream-sharing technology is given the inverse task of planting an idea into the mind of a CEO, but his tragic past may doom the project and his team to disaster.",
    "overview_alter_ru": "Мы привыкли, что в нашем понимании вор – это человек способный украсть какие-то ценности или деньги. Сюжет картины рассказывает о ворах, способных украсть идею прямо у человека из подсознания. Одним из таких является главный герой фильма Доминик Кобб. После того, как его жена умерла, он вынужден скрываться, и не может даже вернуться в страну, чтобы повидать детей. Как-то раз Кобб получает очень неординарный заказ: ему нужно не украсть, а наоборот внедрить новую идею в подсознание человека. Доминику не очень хочется браться за это дело, но заказчик в обмен предлагает возможность вернуться домой. Заручившись поддержкой профессионалов этого дела, Кобб начинает разрабатывать план, как все провернуть. Все нужно очень хорошо продумать, ведь ворам предстоит воссоздать многослойную реальность в подсознании объекта, в результате чего грани могут начать стираться.",
    "overview_alter_en": null,
    "short_overview_ru": "Профессиональные воры внедряются в сон наследника огромной империи. Фантастический боевик Кристофера Нолана"
  }
}
```

### Оценки

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

Ответ `200`:

```json
{
  "ids": {
    "imdb_id": "tt1375666",
    "kp_id": "447301",
    "tmdb_id": "27205",
    "tmdb_tv_id": null,
    "kinorium_id": "472809",
    "urls": {
      "imdb": "https://www.imdb.com/title/tt1375666/",
      "kinorium": "https://ru.kinorium.com/472809/",
      "kp": "https://www.kinopoisk.ru/film/447301/",
      "tmdb": "https://www.themoviedb.org/movie/27205"
    }
  },
  "ratings": {
    "sources": {
      "cr": {
        "value": 92,
        "votes": 13,
        "scale": 100
      },
      "critics": {
        "value": 8.4,
        "votes": 363,
        "scale": 10,
        "kind": "critics"
      },
      "imdb": {
        "value": 8.8,
        "votes": 2877173,
        "scale": 10,
        "url": "https://www.imdb.com/title/tt1375666/"
      },
      "kinorium": {
        "value": 8.6,
        "votes": 27048,
        "scale": 10,
        "url": "https://ru.kinorium.com/472809/",
        "distribution": [
          27,
          26,
          59,
          104,
          280,
          695,
          2003,
          4409,
          5332,
          5577
        ]
      },
      "kp": {
        "value": 8.7,
        "votes": 1132562,
        "scale": 10,
        "url": "https://www.kinopoisk.ru/film/447301/"
      },
      "letterboxd": {
        "value": 8.4,
        "votes": 3604328,
        "scale": 10
      },
      "metacritic": {
        "value": 74,
        "votes": 42,
        "scale": 100,
        "kind": "critics"
      },
      "rt": {
        "value": 86,
        "votes": 364,
        "scale": 100,
        "kind": "critics"
      },
      "tmdb": {
        "value": 8.4,
        "votes": 40402,
        "scale": 10,
        "url": "https://www.themoviedb.org/movie/27205"
      }
    },
    "votes_total": 4050137,
    "divergence_kp_imdb": 0.1,
    "popularity": 50.947
  }
}
```

### Сериал

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "fields=title,type,series" \
  "https://api.kinodata.space/v1.3/titles/tmdb_tv/1396"
```

Ответ `200`:

```json
{
  "ids": {
    "imdb_id": "tt0903747",
    "kp_id": "404900",
    "tmdb_id": null,
    "tmdb_tv_id": "1396",
    "kinorium_id": "400796",
    "urls": {
      "imdb": "https://www.imdb.com/title/tt0903747/",
      "kinorium": "https://ru.kinorium.com/400796/",
      "kp": "https://www.kinopoisk.ru/film/404900/",
      "tmdb": "https://www.themoviedb.org/tv/1396"
    }
  },
  "title": {
    "title_ru": "Во все тяжкие",
    "title_en": "Breaking Bad",
    "title_original": "Breaking Bad"
  },
  "type": {
    "kind": "series",
    "is_series": true,
    "status": "ended",
    "kind_label_ru": "Сериал",
    "kind_label_en": "TV series",
    "status_label_ru": "Завершён",
    "status_label_en": "Ended"
  },
  "series": {
    "seasons_total": 5,
    "episodes_total": 62,
    "start_year": 2008,
    "end_year": 2013
  }
}
```

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

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "fields=title,type,synopsis" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/titles/kp/447301"
```

Ответ `200`:

```json
{
  "ids": {
    "imdb_id": "tt1375666",
    "kp_id": "447301",
    "tmdb_id": "27205",
    "tmdb_tv_id": null,
    "kinorium_id": "472809",
    "urls": {
      "imdb": "https://www.imdb.com/title/tt1375666/",
      "kinorium": "https://en.kinorium.com/472809/",
      "kp": "https://www.kinopoisk.ru/film/447301/",
      "tmdb": "https://www.themoviedb.org/movie/27205"
    }
  },
  "title": {
    "title_en": "Inception",
    "title_original": "Inception"
  },
  "type": {
    "kind": "movie",
    "is_series": false,
    "status": "released",
    "kind_label_en": "Movie",
    "status_label_en": "Released"
  },
  "synopsis": {
    "tagline_en": "Your mind is the scene of the crime.",
    "overview_en": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is offered a chance to regain his old life as payment for a task considered to be impossible: \"inception\", the implantation of another person's idea into a target's subconscious.",
    "short_overview_en": "A thief who steals corporate secrets through the use of dream-sharing technology is given the inverse task of planting an idea into the mind of a CEO, but his tragic past may doom the project and his team to disaster.",
    "overview_alter_en": null
  }
}
```

### Неизвестный ID

```bash
curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.3/titles/kp/999999999"
```

Ответ `404`:

```json
{
  "error": {
    "code": "not_found",
    "message": "title not found: kp 999999999"
  }
}
```