Подборки

Подборка — именованный список тайтлов в заданном редактором порядке.

GET /collections

Перечисляет доступные подборки.

Параметры

имя	тип	обязательный	по умолчанию	описание
limit	целое	нет	50	размер страницы, максимум 50
offset	целое	нет	0	смещение

Запрос

curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.2/collections"

Ответ

{
  "has_more": false,
  "items": [
    {
      "slug": "series-best250",
      "name": "Топ-250 сериалов",
      "description": "Топ-250 сериалов Кинопоиска",
      "poster_url": "https://api.kinodata.space/uploads/843590034d274b077b035816bb0e7d8e2f15d88755bfe970e45ea0a2372fb365.png",
      "language": "ru",
      "items_count": 250,
      "created_at": "2026-06-24T09:41:15.177186Z",
      "updated_at": "2026-09-12T12:01:05.473757Z"
    },
    {
      "slug": "all-popular1000",
      "name": "Топ-1000 популярных тайтлов",
      "description": "Популярные тайтлы Кинопоиска",
      "poster_url": "https://api.kinodata.space/uploads/34686cdc02b2a6e8c2cb387020c4497f5f16d246c3380550e899669f79ad7b97.png",
      "language": "ru",
      "items_count": 1000,
      "created_at": "2026-06-23T19:02:47.25172Z",
      "updated_at": "2026-09-12T11:53:43.661448Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "total": 5
}

Ошибки

статус	код	когда
400	invalid_request	нечисловой limit или offset
401	unauthorized	ключ отсутствует или недействителен

Примечания

slug — то, что подставляется в путь подборки. Имя и описание меняются, slug — нет.

items_count считает тайтлы, готовые к отдаче, — ровно те, по которым потом страницует эндпоинт подборки, так что число совпадает с её total.

updated_at обновляется при каждом пересборе состава: подборки вроде «В тренде за день» переписываются ежедневно.

---

GET /collections/{slug}

Отдаёт подборку и её тайтлы.

Параметры

имя	тип	обязательный	по умолчанию	описание
slug	путь	да	—	идентификатор подборки из списка
sort	строка	нет	порядок редактора	ключ со знаком, как в каталоге
lang	строка	нет	ru	язык производного title
fields	CSV	нет	вся карточка	выбор ключей; доступны ord и note
limit	целое	нет	50	размер страницы, максимум 50
offset	целое	нет	0	смещение

Плюс вся фильтрация каталога: ?kind=, ?genre=, ?year.gte=, ?q=.

Запрос

curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.2/collections/all-popular1000?kind=series&sort=-rating_imdb&limit=1"

Ответ

{
  "collection": {
    "slug": "all-popular1000",
    "name": "Топ-1000 популярных тайтлов",
    "description": "Популярные тайтлы Кинопоиска",
    "poster_url": "https://api.kinodata.space/uploads/34686cdc02b2a6e8c2cb387020c4497f5f16d246c3380550e899669f79ad7b97.png",
    "language": "ru",
    "items_count": 1000,
    "created_at": "2026-06-23T19:02:47.25172Z",
    "updated_at": "2026-09-12T11:53:43.661448Z"
  },
  "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",
      "title": "Во все тяжкие",
      "poster_url": "https://avatars.mds.yandex.net/get-kinopoisk-image/1900788/fb35416f-3b0d-4b96-bc65-cf6923f9e329/600x900",
      "ord": 90,
      "note": null
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": null
}

Ошибки

статус	код	когда
400	invalid_request	неизвестное значение фильтра, ключа сортировки или lang
401	unauthorized	ключ отсутствует или недействителен
404	not_found	подборки с таким slug нет

Примечания

Без параметров тайтлы приходят в порядке редактора, а ord показывает место в нём. Как только появляется фильтр, ?q= или ?sort=, состав подборки становится областью поиска, и работает вся грамматика каталога — при этом ord остаётся при карточке, так что «90-е место из 1000» видно и в отфильтрованной выдаче.

note — комментарий редактора к конкретному тайтлу, чаще всего null.

total приходит числом, пока выдача — вся подборка целиком, и null, когда её сузил фильтр: точное число тогда требует отдельного подсчёта. Размер подборки в любом случае лежит рядом — в collection.items_count.

Хотите только порядок и названия — ?fields=title,ord отдаёт две колонки вместо целой карточки.