Витрины¶

Четыре готовых среза базы. Каждый возвращает карточку тайтла в общем конверте списка и принимает поверх своих настроек фильтры каталога — см. Соглашения → Фильтры.

`GET /charts/top`¶

Лучшее по рейтингу среди тайтлов, набравших достаточно голосов.

Параметры¶

имя	тип	обязательный	по умолчанию	описание
`votes_imdb.gte`	целое	нет	`100000`	порог голосов IMDb
`sort`	строка	нет	`-rating`	ключ со знаком, как в каталоге
`limit`	целое	нет	50	размер страницы, максимум 50
`offset`	целое	нет	0	смещение

Плюс фильтры каталога: ?kind=, ?genre=, ?country=, ?year.gte=.

Запрос¶

curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.2/charts/top?limit=1"

Ответ¶

{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0903747",
      "kp_id": "404900",
      "tmdb_id": null,
      "tmdb_tv_id": "1396",
      "title_ru": "Во все тяжкие",
      "title_en": "Breaking Bad",
      "title_original": "Breaking Bad",
      "year": 2008,
      "release_date": "2008-01-20",
      "kind": "series",
      "poster_kp": "https://avatars.mds.yandex.net/get-kinopoisk-image/1900788/fb35416f-3b0d-4b96-bc65-cf6923f9e329/600x900",
      "poster_tmdb": "https://image.tmdb.org/t/p/original/gwB6E7Zi5L3J9WA2y0zLeKuc3ul.jpg",
      "poster_imdb": null,
      "rating_kp": 8.9,
      "rating_tmdb": 8.9,
      "rating_imdb": 9.5,
      "votes_kp": 856364,
      "votes_tmdb": 18589,
      "votes_imdb": 2673881,
      "countries": [ { "code": "us", "name_ru": "США", "name_en": "United States" } ],
      "genres": ["crime", "drama", "thriller"],
      "rating_kr": 9.0,
      "rating_letterboxd": null,
      "kinorium_id": "400796"
    }
  ],
  "limit": 1,
  "offset": 0
}

Ошибки¶

статус	код	когда
`400`	`invalid_request`	неизвестное значение фильтра или ключа сортировки
`401`	`unauthorized`	ключ отсутствует или недействителен
`429`	`rate_limited`	превышен предел ключа

Примечания¶

Порог голосов — часть чарта, а не косметика: без него верх занимают тайтлы с одинокой десяткой от десятка человек. Порог сдвигается своим ?votes_imdb.gte=, вплоть до нуля.

Единого усреднённого балла нет. sort=-rating берёт первую известную оценку — IMDb, затем Кинопоиск, затем TMDB — и ставит выше тех, у кого набралось хотя бы 50 голосов, чтобы десятка от одного человека не обошла девятку от миллиона. Нужна конкретная шкала — sort=-rating_imdb или -rating_kp.

Конверт приходит без total: чарт бесконечен по построению, и has_more отвечает на единственный практический вопрос.

`GET /releases`¶

Календарь выхода: что выходит в заданном окне дат.

Параметры¶

имя	тип	обязательный	по умолчанию	описание
`from`	дата	нет	сегодня	начало окна, `YYYY-MM-DD`
`to`	дата	нет	+30 дней	конец окна, `YYYY-MM-DD`
`region`	строка	нет	любой	`ru` · `world` · `digital`
`released`	булево	нет	все	`true` — уже вышедшие; `false` — предстоящие
`include_obscure`	булево	нет	`false`	включить тайтлы без постера и почти без голосов
`limit`	целое	нет	50	размер страницы, максимум 50
`offset`	целое	нет	0	смещение

Плюс фильтры каталога: ?kind=, ?genre=, ?country=, ?votes_imdb.gte=.

Запрос¶

curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.2/releases?from=2026-09-01&to=2026-09-30&region=ru&votes_imdb.gte=10000&limit=2"

Ответ¶

{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0086066",
      "kp_id": "2001",
      "tmdb_id": "227",
      "tmdb_tv_id": null,
      "title_ru": "Изгои",
      "title_en": "The Outsiders",
      "title_original": "The Outsiders",
      "year": 1983,
      "release_date": "1983-03-25",
      "kind": "movie",
      "poster_kp": "https://avatars.mds.yandex.net/get-kinopoisk-image/1773646/a041ae51-192e-4bd4-a458-ef879619e3a3/600x900",
      "poster_tmdb": "https://image.tmdb.org/t/p/original/68XmLIWfSBdDcyxsXc1hDBZevQB.jpg",
      "poster_imdb": "https://m.media-amazon.com/images/M/MV5BODlmMzZjZDEtOTUwOS00OTAwLTg2YzAtYTA4ZTk3ZWNjMTgxXkEyXkFqcGc@._V1_SX300.jpg",
      "rating_kp": 7.1,
      "rating_tmdb": 7.2,
      "rating_imdb": 7.0,
      "votes_kp": 16230,
      "votes_tmdb": 1551,
      "votes_imdb": 109817,
      "countries": [
        { "code": "us", "name_ru": "США", "name_en": "United States" },
        { "code": "fr", "name_ru": "Франция", "name_en": "France" }
      ],
      "genres": ["crime", "drama"],
      "date": "2026-09-03",
      "rating_kr": 6.8,
      "rating_letterboxd": 7.3,
      "kinorium_id": "79221"
    }
  ],
  "limit": 2,
  "offset": 0,
  "region": "ru",
  "total": 55
}

Ошибки¶

статус	код	когда
`400`	`invalid_request`	неизвестный `region`; `released` не `true`/`false`
`401`	`unauthorized`	ключ отсутствует или недействителен
`429`	`rate_limited`	превышен предел ключа

Примечания¶

У карточки здесь есть лишнее поле — date, дата этого события в окне. release_date остаётся первой датой тайтла вообще, поэтому у переиздания 1983 года в сентябрьском календаре они разные.

region выбирает, какая дата считается датой события: ru — российская премьера, world — мировая, digital — цифровой релиз. Без него подходит любая.

Фильтры карточки (kind, genre, votes_imdb.gte) сужают уже набранную страницу, а не запрос к окну. Поэтому в примере при limit=2 вернулась одна строка, а total (55) остался размером окна. Со строгим фильтром берите страницы крупнее.

`GET /discover/hidden-gems`¶

Высоко оценённое при небольшой известности.

Параметры¶

имя	тип	обязательный	по умолчанию	описание
`votes_total.gte`	целое	нет	`200`	нижний порог известности
`votes_total.lte`	целое	нет	`5000`	верхний порог известности
`rating_imdb.gte`	число	нет	`7.5`	порог оценки
`sort`	строка	нет	`-rating`	ключ со знаком, как в каталоге
`limit`	целое	нет	50	размер страницы, максимум 50
`offset`	целое	нет	0	смещение

Плюс фильтры каталога: ?kind=, ?genre=, ?country=, ?year.gte=.

Запрос¶

curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.2/discover/hidden-gems?country=jp&votes_total.gte=3000&limit=1"

Ответ¶

{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0364843",
      "kp_id": null,
      "tmdb_id": null,
      "tmdb_tv_id": "2995",
      "title_ru": "Самое экстремальное испытание на выбывание",
      "title_en": "Most Extreme Elimination Challenge",
      "title_original": "MXC",
      "year": 2003,
      "release_date": "2011-05-16",
      "kind": "series",
      "poster_kp": null,
      "poster_tmdb": "https://image.tmdb.org/t/p/original/132ZYuUqZ26Hw7LNMVfJ44RQotO.jpg",
      "poster_imdb": "https://m.media-amazon.com/images/M/MV5BMTcxMDUxMDg3OV5BMl5BanBnXkFtZTcwMDAxMzYzMQ@@._V1_SX300.jpg",
      "rating_kp": null,
      "rating_tmdb": 7.0,
      "rating_imdb": 8.8,
      "votes_kp": null,
      "votes_tmdb": 30,
      "votes_imdb": 3909,
      "countries": [
        { "code": "us", "name_ru": "США", "name_en": "United States" },
        { "code": "jp", "name_ru": "Япония", "name_en": "Japan" }
      ],
      "genres": ["action", "adventure", "comedy", "game_show"],
      "rating_kr": null,
      "rating_letterboxd": null,
      "kinorium_id": "1697196"
    }
  ],
  "limit": 1,
  "offset": 0
}

Ошибки¶

статус	код	когда
`400`	`invalid_request`	неизвестное значение фильтра или ключа сортировки
`401`	`unauthorized`	ключ отсутствует или недействителен
`429`	`rate_limited`	превышен предел ключа

Примечания¶

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

votes_total — сумма голосов по всем источникам, поэтому потолок известности не обходится тайтлом, популярным на одном из них.

`GET /discover/divergence`¶

Тайтлы, которые Кинопоиск и IMDb оценивают по-разному.

Параметры¶

имя	тип	обязательный	по умолчанию	описание
`direction`	строка	нет	обе	`ru` — Кинопоиск выше; `west` — IMDb выше
`min_delta`	число	нет	`1.0`	минимальный разрыв оценок
`min_votes`	целое	нет	`10000`	порог голосов с обеих сторон
`released`	булево	нет	все	`true` — вышедшие; `false` — предстоящие
`limit`	целое	нет	50	размер страницы, максимум 50
`offset`	целое	нет	0	смещение

Плюс фильтры каталога: ?kind=, ?genre=, ?country=, ?year.gte=.

Запрос¶

curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.2/discover/divergence?direction=ru&min_delta=1.5&min_votes=50000&limit=1"

Ответ¶

{
  "direction": "ru",
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt4877122",
      "kp_id": "957805",
      "tmdb_id": "378236",
      "tmdb_tv_id": null,
      "title_ru": "Эмоджи фильм",
      "title_en": "The Emoji Movie",
      "title_original": "The Emoji Movie",
      "year": 2017,
      "release_date": "2017-07-27",
      "kind": "cartoon",
      "poster_kp": "https://avatars.mds.yandex.net/get-kinopoisk-image/1773646/52c54455-7bee-4cbf-baf0-01a0f9d2624b/600x900",
      "poster_tmdb": "https://image.tmdb.org/t/p/original/bUk7ViYRCWxe0qqyBhnETSAND2y.jpg",
      "poster_imdb": "https://m.media-amazon.com/images/M/MV5BMTkzMzM3OTM2Ml5BMl5BanBnXkFtZTgwMDM0NDU3MjI@._V1_SX300.jpg",
      "rating_kp": 5.9,
      "rating_tmdb": 5.4,
      "rating_imdb": 3.5,
      "votes_kp": 105410,
      "votes_tmdb": 3319,
      "votes_imdb": 79925,
      "countries": [ { "code": "us", "name_ru": "США", "name_en": "United States" } ],
      "genres": ["adventure", "animation", "comedy", "family", "fantasy", "speculative_fiction"],
      "divergence": 2.4,
      "votes_kp_count": 105410,
      "votes_imdb_count": 79925,
      "rating_kr": 5.1,
      "rating_letterboxd": 2.8,
      "kinorium_id": "1555483"
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": 27
}

Ошибки¶

статус	код	когда
`400`	`invalid_request`	неизвестное значение фильтра; `released` не `true`/`false`
`401`	`unauthorized`	ключ отсутствует или недействителен
`429`	`rate_limited`	превышен предел ключа

Примечания¶

divergence — величина разрыва: 2.4 у примера означает, что Кинопоиск оценивает тайтл на 2.4 балла выше IMDb. direction выбирает сторону разрыва, без него подходят обе.

votes_kp_count и votes_imdb_count дублируют votes_kp / votes_imdb карточки — по ним видно, на скольких голосах построен разрыв.

min_votes применяется к обеим сторонам сразу: при десятке голосов на одной из них разрыв случаен.

Как и у календаря, фильтры карточки сужают набранную страницу, а total считает выборку до них.

Витрины¶

GET /charts/top¶

Параметры¶

Запрос¶

Ответ¶

Ошибки¶

Примечания¶

GET /releases¶

Параметры¶

Запрос¶

Ответ¶

Ошибки¶

Примечания¶

GET /discover/hidden-gems¶

Параметры¶

Запрос¶

Ответ¶

Ошибки¶

Примечания¶

GET /discover/divergence¶

Параметры¶

Запрос¶

Ответ¶

Ошибки¶

Примечания¶

`GET /charts/top`¶

`GET /releases`¶

`GET /discover/hidden-gems`¶

`GET /discover/divergence`¶