# Календарь релизов

> Что выходит в кино, в онлайне и какие сезоны стартуют — по датам и регионам.

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

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

Строка календаря — один выход: тайтл и в `release` — когда, где и как он выходит. Фильм, который выходит в цифре в России, США и мире в один день, даёт три строки.

Без параметров календарь показывает 30 дней с сегодняшнего, ближайшие даты — первыми; внутри дня анонсы без голосов идут по популярности на TMDB. Окно задают `from` и `to`, не длиннее 400 дней. Прошедшие выходы в окне оставляет `released=true`, предстоящие — `released=false`; «вышло за неделю, новое первым» — `from` неделю назад, `released=true&sort=-date`.

Для витрины «Скоро в кино» возьмите кинопрокат в России и отсортируйте по известности: `type=cinema&region=ru&sort=-votes_total`. Работают фильтры каталога — `kind`, `genre`, `country`, `required=poster` — и `fields`.

У премьер сезонов и у выходов `release` региона нет, поэтому `region` с ними даёт `400`: спрашивайте `type=cinema,digital&region=ru` и `type=series` отдельно. Тайтлы без русского и английского названия календарь прячет; показать их — `include_obscure=true`.

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

- `type` (csv) — Виды выхода, через запятую. Подписи — в `/enums`, набор `release_types`.
  Значения: `cinema`, `digital`, `series`, `release`.
  По умолчанию: все. Пример: `type=cinema`.
- `region` (csv) — Регионы, через запятую. Только для `cinema` и `digital`.
  Значения: `ru`, `us`, `world`.
  По умолчанию: все. Пример: `region=ru`.
- `from · to` (date) — Окно календаря, `YYYY-MM-DD`, обе даты включительно. Не длиннее 400 дней.
  По умолчанию: с сегодняшнего дня на 30 дней. Пример: `from=2026-11-01&to=2026-11-30`.
- `released` (boolean) — `true` — только прошедшие выходы, `false` — только предстоящие.
  По умолчанию: оба.
- `sort` (enum) — `date` или `+date` — ранние даты первыми, `-date` — поздние первыми, `-votes_total` — сначала тайтлы, за которые проголосовало больше всего людей.
  Значения: `date`, `-date`, `-votes_total`.
  По умолчанию: `date`. Пример: `sort=-votes_total`.
- `include_obscure` (boolean) — `true` — показать и тайтлы без русского и английского названия, а также без постера и 50 голосов.
  По умолчанию: `false`.
- `фильтры каталога` — Фильтры каталога: `kind=movie`, `genre=horror`, `country=ru`, `required=poster`. Подробно — в [Фильтры и сортировка](https://kinodata.space/ru/docs/filters.md).
- `fields` (csv) — Какие поля элемента вернуть, как в [каталоге](https://kinodata.space/ru/docs/titles.md), плюс `release`. ID приходят всегда.
  Пример: `fields=title,poster_url,release`.
- `lang` (ru | en) — Оставить в ответе один язык. Без него текстовые поля приходят парами `_ru` и `_en`. Подробнее — [Языки ответа](https://kinodata.space/ru/docs/languages.md).
  Пример: `lang=en`.
- `limit` (integer) — Сколько строк вернуть, целое от 1 до 50.
  По умолчанию: 50. Пример: `limit=20`.
- `offset` (integer) — Сколько строк пропустить, целое от 0.
  По умолчанию: 0.

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

- `from`, `to` (string) — Окно календаря, которое API применил.
- `type`, `region` (array | null) — `type` и `region` из запроса. `null` — без отбора.
- `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`.
  - `release` (object) — Событие выхода.
    - `type` (enum) — `cinema` — в кинотеатрах, `digital` — в онлайн-кинотеатрах и магазинах, `series` — премьера сезона, `release` — выход, у которого источник не указал ни вида, ни региона.
      Значения: `cinema`, `digital`, `series`, `release`.
    - `region` (enum | null) — `ru` — Россия, `us` — США, `world` — выход в мире без привязки к стране. У `series` и `release` — `null`.
      Значения: `ru`, `us`, `world`.
    - `date` (string) — Дата выхода, `YYYY-MM-DD`.
    - `rerelease` (boolean) — Повторный прокат: «Сумерки» снова в кино.
    - `season` (integer | null) — Номер сезона у `series`.
- `total` (integer) — Сколько строк в окне с учётом фильтров.
- `limit`, `offset`, `has_more` — Пагинация — как в [любом списке](https://kinodata.space/ru/docs/lists.md#форма-списка).

## Ошибки

| статус | код | когда |
|---|---|---|
| 400 | `invalid_request` | Неизвестный `type` или `region`; `region` вместе с `series` или `release`; дата не в формате `YYYY-MM-DD`; `to` раньше `from` или окно длиннее 400 дней; `sort` не `date`, `-date` или `-votes_total`; `q`, `preset` или `cursor` — к календарю они не применяются; неизвестный фильтр или поле в `fields`; параметр другого эндпоинта (например, `role` или `relation`); `limit` не целое от 1 или `offset` меньше 0. |
| 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 "type=cinema" \
  --data-urlencode "region=ru" \
  --data-urlencode "sort=-votes_total" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,poster_url,release" \
  "https://api.kinodata.space/v1.3/releases"
```

Ответ `200`:

```json
{
  "from": "2026-10-12",
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt1325004",
      "kp_id": "432423",
      "tmdb_id": "24021",
      "tmdb_tv_id": null,
      "kinorium_id": "461497",
      "title_ru": "Сумерки. Сага. Затмение",
      "title_en": "The Twilight Saga: Eclipse",
      "year": 2010,
      "poster_url_ru": "https://avatars.mds.yandex.net/get-kinopoisk-image/10703859/47c6c237-15e3-42f8-8cce-9d9d08902d76/600x900",
      "poster_url_en": "https://image.tmdb.org/t/p/original/dK4Gi1UdMiHzHc7r7CZQG4IQ9Sr.jpg",
      "release": {
        "type": "cinema",
        "region": "ru",
        "date": "2026-11-05",
        "rerelease": true,
        "season": null
      }
    },
    {
      "imdb_id": "tt33296751",
      "kp_id": "7518867",
      "tmdb_id": "1340206",
      "tmdb_tv_id": null,
      "kinorium_id": "12220331",
      "title_ru": "Настройщик",
      "title_en": "Tuner",
      "year": 2025,
      "poster_url_ru": "https://avatars.mds.yandex.net/get-kinopoisk-image/10703859/a1b23635-40fe-406b-8e54-a7104d654820/600x900",
      "poster_url_en": "https://image.tmdb.org/t/p/original/kyM60vcgf7lfofmZB4F5Rj7OrHW.jpg",
      "release": {
        "type": "cinema",
        "region": "ru",
        "date": "2026-11-05",
        "rerelease": false,
        "season": null
      }
    },
    {
      "imdb_id": "tt36733027",
      "kp_id": "7783722",
      "tmdb_id": "1304434",
      "tmdb_tv_id": null,
      "kinorium_id": "12255198",
      "title_ru": "Маленькие демоны путешествуют на Запад",
      "title_en": "Nobody",
      "year": 2025,
      "poster_url_ru": "https://avatars.mds.yandex.net/get-kinopoisk-image/10703959/611d17a7-e219-4310-90de-81d1fbf92d3e/600x900",
      "poster_url_en": "https://image.tmdb.org/t/p/original/mCa8Pb4L0X56gxV1sIQkLJ2RKz0.jpg",
      "release": {
        "type": "cinema",
        "region": "ru",
        "date": "2026-10-29",
        "rerelease": false,
        "season": null
      }
    }
  ],
  "limit": 3,
  "offset": 0,
  "region": [
    "ru"
  ],
  "to": "2026-11-11",
  "total": 45,
  "type": [
    "cinema"
  ]
}
```

### В онлайне

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "type=digital" \
  --data-urlencode "region=ru" \
  --data-urlencode "sort=-votes_total" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,release" \
  "https://api.kinodata.space/v1.3/releases"
```

Ответ `200`:

```json
{
  "from": "2026-10-12",
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt1756855",
      "kp_id": "572477",
      "tmdb_id": "1204680",
      "tmdb_tv_id": null,
      "kinorium_id": "553192",
      "title_ru": "Хитрый койот",
      "title_en": "Coyote vs. Acme",
      "year": 2026,
      "release": {
        "type": "digital",
        "region": "ru",
        "date": "2026-10-22",
        "rerelease": false,
        "season": null
      }
    },
    {
      "imdb_id": "tt33253232",
      "kp_id": "8261895",
      "tmdb_id": "1336928",
      "tmdb_tv_id": null,
      "kinorium_id": "11534696",
      "title_ru": "Незваные гости",
      "title_en": "McMANSION",
      "year": 2025,
      "release": {
        "type": "digital",
        "region": "ru",
        "date": "2026-10-14",
        "rerelease": false,
        "season": null
      }
    },
    {
      "imdb_id": "tt32268691",
      "kp_id": "5595288",
      "tmdb_id": "1284046",
      "tmdb_tv_id": null,
      "kinorium_id": "11252404",
      "title_ru": "Натиск",
      "title_en": "Onslaught",
      "year": 2026,
      "release": {
        "type": "digital",
        "region": "ru",
        "date": "2026-10-22",
        "rerelease": false,
        "season": null
      }
    }
  ],
  "limit": 3,
  "offset": 0,
  "region": [
    "ru"
  ],
  "to": "2026-11-11",
  "total": 65,
  "type": [
    "digital"
  ]
}
```

### Сезоны

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "type=series" \
  --data-urlencode "sort=-votes_total" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,release" \
  "https://api.kinodata.space/v1.3/releases"
```

Ответ `200`:

```json
{
  "from": "2026-10-12",
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt28751684",
      "kp_id": "5249042",
      "tmdb_id": null,
      "tmdb_tv_id": "234291",
      "kinorium_id": "11997917",
      "title_ru": "Папины дочки. Новые",
      "title_en": "Daddy's Daughters. New",
      "year": 2023,
      "release": {
        "type": "series",
        "region": null,
        "date": "2026-10-19",
        "rerelease": false,
        "season": 6
      }
    },
    {
      "imdb_id": "tt7631058",
      "kp_id": "1112513",
      "tmdb_id": null,
      "tmdb_tv_id": "84773",
      "kinorium_id": "1659219",
      "title_ru": "Властелин колец: Кольца власти",
      "title_en": "The Lord of the Rings: The Rings of Power",
      "year": 2022,
      "release": {
        "type": "series",
        "region": null,
        "date": "2026-11-11",
        "rerelease": false,
        "season": 3
      }
    },
    {
      "imdb_id": "tt12590266",
      "kp_id": "2000102",
      "tmdb_id": null,
      "tmdb_tv_id": "105248",
      "kinorium_id": "2402738",
      "title_ru": "Киберпанк: Бегущие по краю",
      "title_en": null,
      "year": 2022,
      "release": {
        "type": "series",
        "region": null,
        "date": "2026-10-20",
        "rerelease": false,
        "season": 2
      }
    }
  ],
  "limit": 3,
  "offset": 0,
  "region": null,
  "to": "2026-11-11",
  "total": 148,
  "type": [
    "series"
  ]
}
```

### Вышло за неделю

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "from=2026-10-03" \
  --data-urlencode "released=true" \
  --data-urlencode "sort=-date" \
  --data-urlencode "type=cinema,digital" \
  --data-urlencode "region=ru" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,release" \
  "https://api.kinodata.space/v1.3/releases"
```

Ответ `200`:

```json
{
  "from": "2026-10-03",
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt40385667",
      "kp_id": "11467031",
      "tmdb_id": null,
      "tmdb_tv_id": "333101",
      "kinorium_id": "12822306",
      "title_ru": "Остров сокровищ",
      "title_en": "Treasure Island",
      "year": 2026,
      "release": {
        "type": "digital",
        "region": "ru",
        "date": "2026-10-12",
        "rerelease": false,
        "season": null
      }
    },
    {
      "imdb_id": "tt44120119",
      "kp_id": null,
      "tmdb_id": null,
      "tmdb_tv_id": null,
      "kinorium_id": "13112838",
      "title_ru": "Последний стрим",
      "title_en": "Last Stream",
      "year": 2026,
      "release": {
        "type": "digital",
        "region": "ru",
        "date": "2026-10-12",
        "rerelease": false,
        "season": null
      }
    },
    {
      "imdb_id": "tt32293052",
      "kp_id": "12429497",
      "tmdb_id": "1471672",
      "tmdb_tv_id": null,
      "kinorium_id": "11243111",
      "title_ru": "Падение сэра Дугласа Уитерфорда",
      "title_en": "The Fall of Sir Douglas Weatherford",
      "year": 2026,
      "release": {
        "type": "cinema",
        "region": "ru",
        "date": "2026-10-10",
        "rerelease": false,
        "season": null
      }
    }
  ],
  "limit": 3,
  "offset": 0,
  "region": [
    "ru"
  ],
  "to": "2026-11-02",
  "total": 57,
  "type": [
    "cinema",
    "digital"
  ]
}
```

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

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "type=cinema" \
  --data-urlencode "region=ru" \
  --data-urlencode "sort=-votes_total" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,poster_url,release" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/releases"
```

Ответ `200`:

```json
{
  "from": "2026-10-12",
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt1325004",
      "kp_id": "432423",
      "tmdb_id": "24021",
      "tmdb_tv_id": null,
      "kinorium_id": "461497",
      "title_en": "The Twilight Saga: Eclipse",
      "year": 2010,
      "poster_url_en": "https://image.tmdb.org/t/p/original/dK4Gi1UdMiHzHc7r7CZQG4IQ9Sr.jpg",
      "release": {
        "type": "cinema",
        "region": "ru",
        "date": "2026-11-05",
        "rerelease": true,
        "season": null
      }
    },
    {
      "imdb_id": "tt33296751",
      "kp_id": "7518867",
      "tmdb_id": "1340206",
      "tmdb_tv_id": null,
      "kinorium_id": "12220331",
      "title_en": "Tuner",
      "year": 2025,
      "poster_url_en": "https://image.tmdb.org/t/p/original/kyM60vcgf7lfofmZB4F5Rj7OrHW.jpg",
      "release": {
        "type": "cinema",
        "region": "ru",
        "date": "2026-11-05",
        "rerelease": false,
        "season": null
      }
    },
    {
      "imdb_id": "tt36733027",
      "kp_id": "7783722",
      "tmdb_id": "1304434",
      "tmdb_tv_id": null,
      "kinorium_id": "12255198",
      "title_en": "Nobody",
      "year": 2025,
      "poster_url_en": "https://image.tmdb.org/t/p/original/mCa8Pb4L0X56gxV1sIQkLJ2RKz0.jpg",
      "release": {
        "type": "cinema",
        "region": "ru",
        "date": "2026-10-29",
        "rerelease": false,
        "season": null
      }
    }
  ],
  "limit": 3,
  "offset": 0,
  "region": [
    "ru"
  ],
  "to": "2026-11-11",
  "total": 45,
  "type": [
    "cinema"
  ]
}
```

### Окно длиннее 400 дней

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "from=2026-01-01" \
  --data-urlencode "to=2027-12-31" \
  "https://api.kinodata.space/v1.3/releases"
```

Ответ `400`:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "a release window spans at most 400 days",
    "field": "to"
  }
}
```