# Подборка

> Тайтлы подборки в порядке редактора — или с фильтрами и сортировкой каталога.

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

Запрос: `GET https://api.kinodata.space/v1.3/collections/{slug}`

Без параметров подборка приходит в порядке редактора: `ord` — место тайтла в ней, с 1. У топов Кинопоиска это место в топе.

Стоит добавить фильтр, поиск `q` или `sort` — и подборка становится областью поиска: ответ собирает движок каталога, а `ord` остаётся исходным местом. С фильтром или `q` `total` равен `null`, как в каталоге. Работают все [фильтры и сортировки](https://kinodata.space/ru/docs/filters.md) и `fields`.

Тайтлы подборки можно выбрать и в каталоге: `/titles?collection=popular-titles`. Там есть курсор, но нет `ord`.

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

- `slug` (string, обязательный) — Имя подборки из [списка подборок](https://kinodata.space/ru/docs/collections.md).
  Пример: `top-movies`.

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

- `фильтры, q и sort` — Фильтры, поиск и сортировка каталога: `kind=movie`, `q=матрица`, `sort=-rating_imdb`. Подробно — в [Фильтры и сортировка](https://kinodata.space/ru/docs/filters.md).
  По умолчанию: порядок редактора.
- `fields` (csv) — Какие поля элемента вернуть, как в [каталоге](https://kinodata.space/ru/docs/titles.md), плюс `ord` и `note`. ID приходят всегда.
  Пример: `fields=title,year,ord`.
- `lang` (ru | en) — Оставить в ответе один язык. Без него текстовые поля приходят парами `_ru` и `_en`. Подробнее — [Языки ответа](https://kinodata.space/ru/docs/languages.md).
  Пример: `lang=en`.
- `limit` (integer) — Сколько тайтлов вернуть, целое от 1 до 50.
  По умолчанию: 50. Пример: `limit=10`.
- `offset` (integer) — Сколько тайтлов пропустить, целое от 0.
  По умолчанию: 0.

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

- `collection` (object) — Сама подборка — тот же объект, что в [списке подборок](https://kinodata.space/ru/docs/collections.md).
  - `slug` (string) — Имя подборки в адресе и в фильтре каталога `collection`.
  - `name_ru`, `name_en` (string | null) — Название.
  - `description_ru`, `description_en` (string | null) — Описание. У авторских подборок его может не быть.
  - `poster_url` (string | null) — Обложка подборки. Если своей нет — постер первого тайтла.
  - `items_count` (integer) — Сколько тайтлов в подборке.
  - `created_at`, `updated_at` (string) — Когда подборку создали и когда в последний раз меняли состав, ISO 8601 в UTC.
- `items` (array) — Тайтлы — та же карточка, что в [каталоге](https://kinodata.space/ru/docs/titles.md).
  - `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`.
  - `ord` (integer) — Место тайтла в подборке, с 1.
  - `note` (string | null) — Комментарий редактора к тайтлу.
- `total` (integer | null) — Сколько тайтлов в подборке. С фильтром или `q` — `null`.
- `limit`, `offset`, `has_more` — Пагинация — как в [любом списке](https://kinodata.space/ru/docs/lists.md#форма-списка).

## Ошибки

| статус | код | когда |
|---|---|---|
| 400 | `invalid_request` | Неизвестный фильтр, ключ `sort` или поле в `fields`; параметр другого эндпоинта (например, `role` или `relation`); `limit` не целое от 1 или `offset` меньше 0; повторённый параметр; `cursor` — подборка листается `offset`. |
| 404 | `not_found` | Подборки с таким `slug` нет. |
| 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 "limit=3" \
  --data-urlencode "fields=title,year,rating_kp,ord" \
  "https://api.kinodata.space/v1.3/collections/top-movies"
```

Ответ `200`:

```json
{
  "collection": {
    "slug": "top-movies",
    "name_ru": "500 лучших фильмов",
    "name_en": "500 Best Movies",
    "description_ru": "Пятьсот лучших фильмов по оценкам зрителей Кинопоиска — классика и новые картины, которые зрители ценят выше всего.",
    "description_en": "The 500 best films as rated by Kinopoisk viewers — the classics and the newer films audiences rate highest.",
    "poster_url": "https://api.kinodata.space/uploads/56c18b27af130ab32118807743318e000bb750fceccfb153dec0bac6df6e7d64.png",
    "items_count": 500,
    "created_at": "2026-06-24T09:41:15.166286Z",
    "updated_at": "2026-10-12T14:15:10.418807Z"
  },
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0816692",
      "kp_id": "258687",
      "tmdb_id": "157336",
      "tmdb_tv_id": null,
      "kinorium_id": "384511",
      "title_ru": "Интерстеллар",
      "title_en": "Interstellar",
      "year": 2014,
      "rating_kp": 8.7,
      "ord": 1
    },
    {
      "imdb_id": "tt0111161",
      "kp_id": "326",
      "tmdb_id": "278",
      "tmdb_tv_id": null,
      "kinorium_id": "101209",
      "title_ru": "Побег из Шоушенка",
      "title_en": "The Shawshank Redemption",
      "year": 1994,
      "rating_kp": 9.1,
      "ord": 2
    },
    {
      "imdb_id": "tt0120689",
      "kp_id": "435",
      "tmdb_id": "497",
      "tmdb_tv_id": null,
      "kinorium_id": "109273",
      "title_ru": "Зелёная миля",
      "title_en": "The Green Mile",
      "year": 1999,
      "rating_kp": 9.1,
      "ord": 3
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": 500
}
```

### С фильтром

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "country=ru" \
  --data-urlencode "sort=-rating_kp" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,rating_kp,ord" \
  "https://api.kinodata.space/v1.3/collections/top-movies"
```

Ответ `200`:

```json
{
  "collection": {
    "slug": "top-movies",
    "name_ru": "500 лучших фильмов",
    "name_en": "500 Best Movies",
    "description_ru": "Пятьсот лучших фильмов по оценкам зрителей Кинопоиска — классика и новые картины, которые зрители ценят выше всего.",
    "description_en": "The 500 best films as rated by Kinopoisk viewers — the classics and the newer films audiences rate highest.",
    "poster_url": "https://api.kinodata.space/uploads/56c18b27af130ab32118807743318e000bb750fceccfb153dec0bac6df6e7d64.png",
    "items_count": 500,
    "created_at": "2026-06-24T09:41:15.166286Z",
    "updated_at": "2026-10-12T14:15:10.418807Z"
  },
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt12073988",
      "kp_id": "1234939",
      "tmdb_id": "644612",
      "tmdb_tv_id": null,
      "kinorium_id": "2368311",
      "title_ru": "Счастье в конверте",
      "title_en": "Letters Of Happiness",
      "year": 2020,
      "rating_kp": 8.5,
      "ord": 185
    },
    {
      "imdb_id": "tt36683785",
      "kp_id": "7605663",
      "tmdb_id": "1424967",
      "tmdb_tv_id": null,
      "kinorium_id": "12222872",
      "title_ru": "Диодорова. Против течения",
      "title_en": "Diodorova. Against the Current",
      "year": 2025,
      "rating_kp": 8.5,
      "ord": 270
    },
    {
      "imdb_id": "tt38504885",
      "kp_id": "7525290",
      "tmdb_id": "1458240",
      "tmdb_tv_id": null,
      "kinorium_id": "12221529",
      "title_ru": "Двое в одной жизни, не считая собаки",
      "title_en": "Two People in One Life and a Dog",
      "year": 2025,
      "rating_kp": 8.4,
      "ord": 168
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}
```

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

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,rating_kp,ord" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/collections/top-movies"
```

Ответ `200`:

```json
{
  "collection": {
    "slug": "top-movies",
    "name_en": "500 Best Movies",
    "description_en": "The 500 best films as rated by Kinopoisk viewers — the classics and the newer films audiences rate highest.",
    "poster_url": "https://api.kinodata.space/uploads/56c18b27af130ab32118807743318e000bb750fceccfb153dec0bac6df6e7d64.png",
    "items_count": 500,
    "created_at": "2026-06-24T09:41:15.166286Z",
    "updated_at": "2026-10-12T14:15:10.418807Z"
  },
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0816692",
      "kp_id": "258687",
      "tmdb_id": "157336",
      "tmdb_tv_id": null,
      "kinorium_id": null,
      "title_en": "Interstellar",
      "year": 2014,
      "rating_kp": 8.7,
      "ord": 1
    },
    {
      "imdb_id": "tt0111161",
      "kp_id": "326",
      "tmdb_id": "278",
      "tmdb_tv_id": null,
      "kinorium_id": null,
      "title_en": "The Shawshank Redemption",
      "year": 1994,
      "rating_kp": 9.1,
      "ord": 2
    },
    {
      "imdb_id": "tt0120689",
      "kp_id": "435",
      "tmdb_id": "497",
      "tmdb_tv_id": null,
      "kinorium_id": null,
      "title_en": "The Green Mile",
      "year": 1999,
      "rating_kp": 9.1,
      "ord": 3
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": 500
}
```

### Нет такой подборки

```bash
curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.3/collections/best-films"
```

Ответ `404`:

```json
{
  "error": {
    "code": "not_found",
    "message": "collection not found: best-films"
  }
}
```