Тайтлы¶

Все пути принимают {type}/{id} — imdb · kp · tmdb · tmdb_tv · kinorium и номер в этом каталоге. Ответ по любому из них для одного тайтла одинаков.

`GET /titles/{type}/{id}`¶

Карточка тайтла: названия, описания, даты, рейтинги по источникам, состав, жанры, компании, доступность, награды.

Параметры¶

имя	тип	обязательный	по умолчанию	описание
`type`	путь	да	—	каталог номера
`id`	путь	да	—	номер в этом каталоге
`lang`	строка	нет	`ru`	язык производных полей и подписей: `ru` · `en`
`fields`	CSV	нет	вся карточка	оставить перечисленные блоки; со знаком `-` — убрать их

Блоки для fields: ids, meta, title, type, synopsis, release, ratings, finance, awards, countries, classification, series, media, genres, companies, akas, tags, watch, parental, credits_top, franchise, counts.

Запрос¶

curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.2/titles/tmdb/27205?fields=title,ratings,release"

Ответ¶

{
  "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",
    "title": "Начало"
  },
  "ratings": {
    "sources": {
      "imdb":       { "value": 8.8, "votes": 2866853, "scale": 10, "url": "https://www.imdb.com/title/tt1375666/" },
      "kp":         { "value": 8.7, "votes": 1127148, "scale": 10, "url": "https://www.kinopoisk.ru/film/447301/" },
      "tmdb":       { "value": 8.4, "votes": 40155,   "scale": 10, "url": "https://www.themoviedb.org/movie/27205" },
      "kinorium":   { "value": 8.6, "votes": 26680,   "scale": 10, "url": "https://ru.kinorium.com/472809/" },
      "letterboxd": { "value": 8.4, "votes": 3604328, "scale": 10 },
      "rt":         { "value": 86.0, "votes": 364, "scale": 100, "kind": "critics" },
      "metacritic": { "value": 74.0, "votes": 42,  "scale": 100, "kind": "critics" },
      "critics":    { "value": 8.4,  "votes": 363, "scale": 10,  "kind": "critics" },
      "cr":         { "value": 92.0, "votes": 13,  "scale": 100 }
    },
    "votes_total": 4034156,
    "distribution": [28, 25, 58, 104, 280, 699, 2000, 4390, 5349, 5714],
    "divergence_kp_imdb": 0.1,
    "popularity": 50.9672
  },
  "release": {
    "year": 2010,
    "runtime": 148,
    "releases": [
      { "region": "world", "dates": [ { "type": "premiere", "date": "2010-07-08" } ] },
      { "region": "usa",   "dates": [ { "type": "premiere", "date": "2010-07-13" } ] },
      { "region": "ru",    "dates": [ { "type": "premiere", "date": "2010-07-22" },
                                      { "type": "digital",  "date": "2012-06-01" } ] }
    ]
  }
}

Ошибки¶

статус	код	когда
`400`	`invalid_request`	неизвестный `type`, `lang` или имя блока в `fields`; смешение режимов в `fields`
`401`	`unauthorized`	ключ отсутствует или недействителен
`404`	`not_found`	такого номера нет в базе

Примечания¶

Блок ids приходит всегда, даже если его не просили: карточка без идентификаторов — это строки, которые не с чем связать.

ratings.sources — объект по источникам, у каждого своя scale. Шкалы 0–10 и 0–100 соседствуют, поэтому она указана явно, а kind: "critics" отличает оценку критиков от зрительской. Единого усреднённого балла нет намеренно: у источников разные аудитории, и среднее это скрывает.

counts — карта навигации: сколько у тайтла каста, изображений, видео, фактов, вопросов, цитат, серий, сезонов и связей. У «Начала» это

{ "cast": 335, "images": 399, "videos": 61, "facts": 37, "faq": 16,
  "quotes": 5, "episodes": 0, "seasons": 0, "relations": 255 }

— по ним видно, за чем идти на подресурсы, а за чем незачем.

Блок franchise есть только у тайтлов, входящих во франшизу: {name, poster_url, size}. Состав франшизы — в связях.

Карточка целиком — около 24 КБ, со сжатием 7 КБ. ?fields= экономит трафик, а не время.

`GET /titles/{type}/{id}/cast`¶

Состав и съёмочная группа, сведённые из источников в одного человека.

Параметры¶

имя	тип	обязательный	по умолчанию	описание
`role`	строка	нет	все роли	одна роль; список — в `/enums`, набор `credit_roles`
`source`	строка	нет	все	оставить кредиты этого источника
`group`	строка	нет	`role`	`role` — секции по ролям; `none` — плоский список
`lang`	строка	нет	`ru`	язык подписей ролей и имён персонажей
`limit`	целое	нет	1000	размер страницы; при секциях — размер секции, максимум 50
`offset`	целое	нет	0	смещение; с секциями отвечает `400`

Запрос¶

curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.2/titles/tmdb/27205/cast?role=director"

Ответ¶

{
  "has_more": false,
  "items": [
    {
      "person": {
        "imdb_id": "nm0634240",
        "kp_id": "41477",
        "tmdb_id": "525",
        "kinorium_id": "476400",
        "name_ru": "Кристофер Нолан",
        "name_en": "Christopher Nolan",
        "name_orig": null,
        "photo_url_kp": "https://st.kp.yandex.net/images/actor_iphone/iphone360_41477.jpg",
        "photo_url_tmdb": null,
        "photo_url_kinorium": "https://images.kinorium.com/persona/300/476400.jpg?20260829201207",
        "gender": "male",
        "birth_year": 1970,
        "professions": ["actor", "cinematographer", "composer", "director", "editor", "producer", "writer"]
      },
      "role": "director",
      "character": null,
      "job": null,
      "dubs": null,
      "ord": 0,
      "sources": ["kinorium", "kp"]
    }
  ],
  "limit": 1000,
  "offset": 0,
  "summary": [
    { "role": "director", "role_ru": "Режиссёры", "count": 1 }
  ],
  "total": 1
}

Ошибки¶

статус	код	когда
`400`	`invalid_request`	неизвестная `role`, `group` или `lang`; `offset` вместе с секциями
`401`	`unauthorized`	ключ отсутствует или недействителен
`404`	`not_found`	такого номера нет в базе

Примечания¶

Без параметров ответ приходит секциями: Режиссёры, Актёры, Сценаристы, Продюсеры и далее в каноническом порядке, по десять человек в каждой. ?role= — это переход внутрь секции: плоский список с полной пагинацией, как в примере выше.

summary описывает весь состав, а не страницу, поэтому подписи вкладок не сдвигаются при пагинации.

У актёра character — объект, а не строка: три написания имени персонажа и кадр из фильма именно с ним.

{
  "role": "actor",
  "character": {
    "ru": "Кобб",
    "en": "Dom Cobb",
    "original": null,
    "photo_url": "https://images.kinorium.com/movie/cast/472809/w300_138.jpg?1614892697"
  },
  "job": null,
  "dubs": null,
  "ord": 0,
  "sources": ["kp", "tmdb", "kinorium"]
}

У съёмочной группы character равен null — играть там нечего, поэтому в примере выше у режиссёра его нет. Лишние написания отбрасываются: если русское имя совпадает с английским или в нём нет кириллицы, приходит только en.

sources показывает, какие каталоги подтвердили кредит. Два источника означают, что человек сведён по совпадению, а не угадан.

ord — место в титрах: у актёров порядок в титульном списке, у съёмочной группы порядок внутри своего цеха.

`GET /titles/{type}/{id}/media`¶

Изображения и видео одним списком: постеры, кадры, логотипы, трейлеры.

Параметры¶

имя	тип	обязательный	по умолчанию	описание
`class`	строка	нет	оба	`image` · `video`
`type`	строка	нет	все	вид: `poster`, `backdrop`, `logo`, `trailer`, `teaser`…; наборы `image_types` и `video_kinds` в `/enums`
`language`	строка	нет	все	ISO-код языка изображения
`group`	строка	нет	плоский список	`type` · `class` · `language` · `none`
`limit`	целое	нет	1000	размер страницы или секции
`offset`	целое	нет	0	смещение; с секциями отвечает `400`

Запрос¶

curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.2/titles/tmdb/27205/media?class=video&type=trailer&limit=1"

Ответ¶

{
  "has_more": true,
  "items": [
    {
      "class": "video",
      "type": "trailer",
      "url": "https://www.youtube.com/watch?v=85Zz1CCXyDI",
      "language": null,
      "width": null,
      "height": null,
      "youtube_id": "85Zz1CCXyDI",
      "preview_url": "https://images.kinorium.com/movie/shot/472809/original_646411.jpg",
      "runtime_sec": 132
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": 4
}

Ошибки¶

статус	код	когда
`400`	`invalid_request`	неизвестный `class`, `type` или `group`; `offset` с секциями
`401`	`unauthorized`	ключ отсутствует или недействителен
`404`	`not_found`	такого номера нет в базе

Примечания¶

Форма одна на оба вида. У изображений пустуют youtube_id, preview_url и runtime_sec, у видео — width и height. Сетка рисуется по class, склеивать два ответа не нужно.

Одно исключение из этого правила — poster_gif, анимированный постер. У него class равен image, а сам файл отдаётся как video/mp4: в <img> он не покажется, нужен <video autoplay muted loop playsinline>. Размеры и длительность при нём не приходят, а вес доходит до 7 МБ, так что в списке карточек его лучше подгружать по требованию, а не вместе с ними.

Анимированный постер есть примерно у каждого десятого из самых популярных тайтлов и почти никогда — у остальных; когда он есть, он один и идёт первым в ответе. Проверить наличие, не забирая всю медиатеку:

curl -H "X-API-Key: $KINODATA_KEY"   "https://api.kinodata.space/v1.2/titles/tmdb/27205/media?type=poster_gif"

{
  "has_more": false,
  "items": [
    {
      "class": "image",
      "type": "poster_gif",
      "url": "https://images.kinorium.com/movie/aniface/472809/original_1135344.mp4",
      "language": null,
      "width": null,
      "height": null,
      "youtube_id": null,
      "preview_url": null,
      "runtime_sec": null
    }
  ],
  "limit": 1000,
  "offset": 0,
  "total": 1
}

Медиатека бывает большой: у «Начала» 460 файлов. ?type=poster&language=ru сужает до нужного, ?group=type даёт разделы с их размерами.

`GET /titles/{type}/{id}/texts`¶

Тексты о тайтле: факты, вопросы-ответы, цитаты.

Параметры¶

имя	тип	обязательный	по умолчанию	описание
`kind`	CSV	нет	все три	`fact` · `faq` · `quote`
`group`	строка	нет	`kind`	`kind` — секции; `none` — плоский список
`lang`	строка	нет	`ru`	язык подписей секций
`limit`	целое	нет	1000	размер страницы или секции
`offset`	целое	нет	0	смещение; с секциями отвечает `400`

Запрос¶

curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.2/titles/kp/301/texts?kind=quote&limit=2"

Ответ¶

{
  "counts": { "fact": 100, "faq": 14, "quote": 5 },
  "has_more": true,
  "items": [
    {
      "kind": "quote",
      "text": "Ложки не существует.",
      "original": "There is no spoon.",
      "author": "Роуэн Уитт",
      "author_role": "мальчик с ложкой"
    },
    {
      "kind": "quote",
      "text": "Я знаю кунг-фу.",
      "original": "I know kung fu.",
      "author": "Киану Ривз",
      "author_role": "Нео"
    }
  ],
  "limit": 2,
  "offset": 0,
  "total": 5
}

Ошибки¶

статус	код	когда
`400`	`invalid_request`	неизвестный `kind` или `group`; `offset` с секциями
`401`	`unauthorized`	ключ отсутствует или недействителен
`404`	`not_found`	такого номера нет в базе

Примечания¶

counts описывает все три вида независимо от kind, поэтому подписи вкладок рисуются одним запросом.

Набор полей зависит от вида: у цитаты — text, original, author, author_role; у факта — text, fact_kind (fact · trivia · blooper) и is_spoiler; у вопроса — question и answer.

`GET /titles/{type}/{id}/episodes`¶

Серии сериала с датами выхода и рейтингами.

Параметры¶

имя	тип	обязательный	по умолчанию	описание
`season`	целое	нет	все сезоны	номер сезона; `0` — спецвыпуски
`group`	строка	нет	плоский список	`season` — сводка по сезонам; `none` — плоский
`limit`	целое	нет	1000	размер страницы
`offset`	целое	нет	0	смещение

Запрос¶

curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.2/titles/tmdb_tv/1399/episodes?season=1&limit=2"

Ответ¶

{
  "has_more": true,
  "items": [
    {
      "season": 1,
      "episode": 1,
      "name_ru": "Зима близко",
      "name_en": "Winter Is Coming",
      "air_date": "2011-04-17",
      "rating_imdb": null,
      "votes_imdb": null,
      "rating_kr": 8.4,
      "special": false
    },
    {
      "season": 1,
      "episode": 2,
      "name_ru": "Королевский Тракт",
      "name_en": "The Kingsroad",
      "air_date": "2011-04-24",
      "rating_imdb": null,
      "votes_imdb": null,
      "rating_kr": 8.6,
      "special": false
    }
  ],
  "limit": 2,
  "offset": 0,
  "total": 10
}

Ошибки¶

статус	код	когда
`400`	`invalid_request`	отрицательный или нечисловой `season`; неизвестный `group`
`401`	`unauthorized`	ключ отсутствует или недействителен
`404`	`not_found`	такого номера нет в базе

Примечания¶

?group=season даёт не секции, а сводку — строку на сезон:

{ "season": 1, "episodes": 10, "first_air": "2011-04-17",
  "last_air": "2011-06-19", "rating_imdb": null, "votes_imdb": null, "specials": false }

По ней рисуется список сезонов без выгрузки всех серий.

У фильма список пуст: total: 0, items: []. Это не ошибка.

Спецвыпуски идут сезоном 0, стоят первыми и помечены special: true.

`GET /titles/{type}/{id}/relations`¶

Связанные тайтлы: похожие, части франшизы, отсылки и упоминания.

Параметры¶

имя	тип	обязательный	по умолчанию	описание
`relation`	CSV	нет	все виды	`similar` · `related` · `reference` · `referenced_in`
`subtype`	CSV	нет	все	сужает `related`: `sequel` · `prequel` · `spinoff` · `parent` · `chronology` · `remake` · `original` · `version`
`source`	строка	нет	все	оставить связи этого источника
`group`	строка	нет	`relation`	`relation` — секции; `none` — плоский список
`lang`	строка	нет	`ru`	язык подписей секций и производного `title`
`limit`	целое	нет	10 на секцию	размер секции, максимум 50; в плоском виде — до 1000
`offset`	целое	нет	0	смещение; с секциями отвечает `400`

Плюс вся фильтрация и сортировка каталога: ?genre=, ?year.gte=, ?rating_imdb.gte=, ?sort= — см. Соглашения.

Запрос¶

curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.2/titles/kp/328/relations?relation=related&subtype=sequel&limit=1"

Ответ¶

{
  "counts": { "reference": 0, "referenced_in": 0, "related": 5, "similar": 0 },
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0167261",
      "kp_id": "312",
      "tmdb_id": "121",
      "tmdb_tv_id": null,
      "title_ru": "Властелин Колец: Две крепости",
      "title_en": "The Lord of the Rings: The Two Towers",
      "title_original": "The Lord of the Rings: The Two Towers",
      "year": 2002,
      "release_date": "2002-12-18",
      "kind": "movie",
      "poster_kp": "https://avatars.mds.yandex.net/get-kinopoisk-image/6201401/772093e4-7f68-49aa-a805-d654693aee26/600x900",
      "poster_tmdb": "https://image.tmdb.org/t/p/original/fl7QZlAoZ4MLcxvgOaBjeUxlpQt.jpg",
      "poster_imdb": null,
      "rating_kp": 8.6,
      "rating_tmdb": 8.4,
      "rating_imdb": 8.8,
      "votes_kp": 642594,
      "votes_tmdb": 24546,
      "votes_imdb": 1982683,
      "countries": [
        { "code": "nz", "name_ru": "Новая Зеландия", "name_en": "New Zealand" },
        { "code": "us", "name_ru": "США", "name_en": "United States" }
      ],
      "genres": ["adventure", "drama", "fantasy"],
      "rating_kr": 8.6,
      "rating_letterboxd": 8.8,
      "kinorium_id": "139946",
      "title": "Властелин Колец: Две крепости",
      "poster_url": "https://avatars.mds.yandex.net/get-kinopoisk-image/6201401/772093e4-7f68-49aa-a805-d654693aee26/600x900",
      "relation": "related",
      "subtype": "sequel"
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": 5
}

Ошибки¶

статус	код	когда
`400`	`invalid_request`	неизвестный `relation`, `subtype`, `group` или `lang`; `offset` с секциями
`401`	`unauthorized`	ключ отсутствует или недействителен
`404`	`not_found`	такого номера нет в базе

Примечания¶

Без параметров ответ приходит четырьмя секциями с подписями и своими total: у «Матрицы» это «Похожие» (93), «Связанные» (8), «Упоминается в» (673) и «Отсылки к» (86). Так видно, чего сколько, и можно перейти в нужный раздел — ?relation=referenced_in даёт плоский пагинируемый список.

Порядок внутри раздела подобран под сам раздел: франшиза читается как хронология и идёт по годам, остальные открываются узнаваемым.

subtype говорит, чем именно связаны два тайтла. null означает, что источник типа связи не указал: это не отдельная категория, и фильтром его не выбрать.

counts считает все виды независимо от relation, поэтому вкладки подписаны и тогда, когда открыта одна.

Тайтлы¶

GET /titles/{type}/{id}¶

Параметры¶

Запрос¶

Ответ¶

Ошибки¶

Примечания¶

GET /titles/{type}/{id}/cast¶

Параметры¶

Запрос¶

Ответ¶

Ошибки¶

Примечания¶

GET /titles/{type}/{id}/media¶

Параметры¶

Запрос¶

Ответ¶

Ошибки¶

Примечания¶

GET /titles/{type}/{id}/texts¶

Параметры¶

Запрос¶

Ответ¶

Ошибки¶

Примечания¶

GET /titles/{type}/{id}/episodes¶

Параметры¶

Запрос¶

Ответ¶

Ошибки¶

Примечания¶

GET /titles/{type}/{id}/relations¶

Параметры¶

Запрос¶

Ответ¶

Ошибки¶

Примечания¶

`GET /titles/{type}/{id}`¶

`GET /titles/{type}/{id}/cast`¶

`GET /titles/{type}/{id}/media`¶

`GET /titles/{type}/{id}/texts`¶

`GET /titles/{type}/{id}/episodes`¶

`GET /titles/{type}/{id}/relations`¶