# Подборки

> Список подборок: топы Кинопоиска, которые обновляются каждый день, и авторские подборки.

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

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

Подборки двух видов:

- **топы Кинопоиска** — `top-movies`, `top-series`, `popular-titles`, `weekly-trending-titles`, `daily-trending-titles`. Повторяют списки Кинопоиска и обновляются каждый день, `updated_at` показывает когда;
- **авторские** — короткие тематические списки: `light-movies`, `single-location-movies`, `psychological-horror-movies`, `disaster-movies`, `true-story-movies`.

`q` ищет подборку по названию и описанию.

Тайтлы подборки — в [`/collections/{slug}`](https://kinodata.space/ru/docs/collections/items.md).

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

- `q` (string) — Поиск по названию и описанию подборки.
  Пример: `q=фильмы`.
- `lang` (ru | en) — Оставить в ответе один язык. Без него текстовые поля приходят парами `_ru` и `_en`. Подробнее — [Языки ответа](https://kinodata.space/ru/docs/languages.md).
  Пример: `lang=en`.
- `limit` (integer) — Сколько подборок вернуть, целое от 1 до 50.
  По умолчанию: 50.
- `offset` (integer) — Сколько подборок пропустить, целое от 0.
  По умолчанию: 0.

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

- `items` (array) — Подборки.
  - `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.
- `total`, `limit`, `offset`, `has_more` — Пагинация — как в [любом списке](https://kinodata.space/ru/docs/lists.md#форма-списка).

## Ошибки

| статус | код | когда |
|---|---|---|
| 400 | `invalid_request` | `limit` не целое от 1 или `offset` меньше 0; параметр, которого список не понимает (например, `fields`), — в ответе список допустимых. |
| 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" \
  "https://api.kinodata.space/v1.3/collections"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "slug": "top-series",
      "name_ru": "250 лучших сериалов",
      "name_en": "250 Best TV Series",
      "description_ru": "Двести пятьдесят лучших сериалов по оценкам зрителей Кинопоиска.",
      "description_en": "The 250 best TV series as rated by Kinopoisk viewers.",
      "poster_url": "https://api.kinodata.space/uploads/843590034d274b077b035816bb0e7d8e2f15d88755bfe970e45ea0a2372fb365.png",
      "items_count": 250,
      "created_at": "2026-06-24T09:41:15.177186Z",
      "updated_at": "2026-10-12T14:18:59.690163Z"
    },
    {
      "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"
    },
    {
      "slug": "popular-titles",
      "name_ru": "Популярное на Кинопоиске",
      "name_en": "Popular on Kinopoisk",
      "description_ru": "Тысяча фильмов и сериалов, которые сейчас популярнее всего у зрителей Кинопоиска.",
      "description_en": "The thousand films and TV series currently most popular with Kinopoisk viewers.",
      "poster_url": "https://api.kinodata.space/uploads/34686cdc02b2a6e8c2cb387020c4497f5f16d246c3380550e899669f79ad7b97.png",
      "items_count": 1000,
      "created_at": "2026-06-23T19:02:47.25172Z",
      "updated_at": "2026-10-12T14:11:35.633811Z"
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": 10
}
```

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

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "limit=3" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/collections"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "slug": "top-series",
      "name_en": "250 Best TV Series",
      "description_en": "The 250 best TV series as rated by Kinopoisk viewers.",
      "poster_url": "https://api.kinodata.space/uploads/843590034d274b077b035816bb0e7d8e2f15d88755bfe970e45ea0a2372fb365.png",
      "items_count": 250,
      "created_at": "2026-06-24T09:41:15.177186Z",
      "updated_at": "2026-10-12T14:18:59.690163Z"
    },
    {
      "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"
    },
    {
      "slug": "popular-titles",
      "name_en": "Popular on Kinopoisk",
      "description_en": "The thousand films and TV series currently most popular with Kinopoisk viewers.",
      "poster_url": "https://api.kinodata.space/uploads/34686cdc02b2a6e8c2cb387020c4497f5f16d246c3380550e899669f79ad7b97.png",
      "items_count": 1000,
      "created_at": "2026-06-23T19:02:47.25172Z",
      "updated_at": "2026-10-12T14:11:35.633811Z"
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": 10
}
```