# Серии

> Серии сериала: названия, описания, даты выхода, длительность и оценки.

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

Запрос: `GET https://api.kinodata.space/v1.3/titles/{type}/{id}/episodes`

Серии приходят по порядку: сезон, затем номер серии. `season` оставляет один сезон.

`group=season` отдаёт не серии, а сводку — строку на сезон с числом серий, датами и оценкой. По ней рисуется список сезонов без загрузки всех серий.

Спецвыпуски идут сезоном `0` и помечены `special: true`. У фильма серий нет: ответ `total: 0` и пустой `items` — это не ошибка.

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

- `type` (string, обязательный) — Каталог, из которого ID: IMDb, Кинопоиск, TMDB (фильм или сериал) или Кинориум.
  Значения: `imdb`, `kp`, `tmdb`, `tmdb_tv`, `kinorium`.
- `id` (string, обязательный) — ID в этом каталоге. У IMDb — `tt` и цифры (`tt1375666`), у остальных — цифры (`447301`).

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

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

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

- `items` (array) — Серии.
  - `season`, `episode` (integer) — Номер сезона и серии.
  - `special` (boolean) — Спецвыпуск.
  - `imdb_id` (string | null) — ID серии в IMDb.
  - `air_date` (string | null) — Дата выхода, `YYYY-MM-DD`.
  - `name_ru`, `name_en` (string | null) — Название серии.
  - `name_original` (string | null) — Название на языке оригинала, если он не русский и не английский.
  - `overview_ru`, `overview_en` (string | null) — Описание серии.
  - `short_overview_ru`, `short_overview_en` (string | null) — Короткое описание в одну-две фразы. Английское — с IMDb.
  - `runtime` (integer | null) — Длительность в минутах.
  - `rating_imdb`, `votes_imdb` (number | null) — Оценка IMDb и число голосов.
  - `rating_kr` (number | null) — Оценка Кинориума.
  - `still_url` (string | null) — Кадр из серии.
- `items при group=season` (array) — Сводка по сезонам.
  - `season` (integer) — Номер сезона.
  - `episodes` (integer) — Сколько в нём серий.
  - `first_air`, `last_air` (string | null) — Даты выхода первой и последней серии.
  - `rating_imdb` (number | null) — Средняя оценка IMDb по сериям сезона.
  - `votes_imdb` (integer | null) — Сумма голосов IMDb по сериям сезона.
  - `specials` (boolean) — Это сезон спецвыпусков.
- `total`, `limit`, `offset`, `has_more` — Пагинация — как в [любом списке](https://kinodata.space/ru/docs/lists.md#форма-списка).

## Ошибки

| статус | код | когда |
|---|---|---|
| 400 | `invalid_request` | `season` не число или меньше нуля; неизвестный `group`; параметр, которого этот список не понимает (например, `sort` или `fields`) — в ответе список допустимых. |
| 404 | `not_found` | Тайтл с таким ID не найден. |
| 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 "season=1" \
  --data-urlencode "limit=2" \
  "https://api.kinodata.space/v1.3/titles/tmdb_tv/1399/episodes"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "season": 1,
      "episode": 1,
      "special": false,
      "imdb_id": "tt1480055",
      "air_date": "2011-04-17",
      "name_ru": "Зима близко",
      "name_en": "Winter Is Coming",
      "name_original": null,
      "overview_ru": "Отправленный на поиски одичалых отряд воинов сталкивается с куда более пугающим злом, чем племя диких людей. Винтерфелл. Лорд Эддард Старк узнает о поимке дезертира, утверждающего о возвращении белых ходоков, а дети лорда заводят домашних питомцев. Из Королевской гавани приходит известие о смерти советника короля, а также новость о намечающемся визите королевской семьи. Король Роберт Баратеон предлагает Старку не только новую должность, но и объединение семей. Пентос. Ради достижения власти Визерис Таргариен принуждает сестру Дейнерис заключить брачный союз с кхалом Дрого.",
      "overview_en": "Jon Arryn, the Hand of the King, is dead. King Robert Baratheon plans to ask his oldest friend, Eddard Stark, to take Jon's place. Across the sea, Viserys Targaryen plans to wed his sister to a nomadic warlord in exchange for an army.",
      "short_overview_ru": null,
      "short_overview_en": null,
      "runtime": 62,
      "rating_imdb": 8.9,
      "votes_imdb": 82456,
      "rating_kr": 8.4,
      "still_url": "https://image.tmdb.org/t/p/original/o4IX9Mm0kpLITVANJMx7inyEUaY.jpg"
    },
    {
      "season": 1,
      "episode": 2,
      "special": false,
      "imdb_id": "tt1668746",
      "air_date": "2011-04-24",
      "name_ru": "Королевский Тракт",
      "name_en": "The Kingsroad",
      "name_original": null,
      "overview_ru": "Тирион заставляет Джоффри выразить супруге Старк слова сочувствия по поводу случившейся трагедии. Желая подержать Кейтилин, Серсея делится с ней давними переживаниями, в то время как Джон дарит сводной сестре необычный подарок. Сноу готов вступить в ночной дозор, но прежде он пытается разузнать у Старка о своей матери. Несмотря на непрерывную опеку, на Брана совершается покушение, что подтверждает подозрения Сансы о преднамеренности случившегося накануне. Дейнерис знакомится со своими служанками, одна из которых готова поделиться с хозяйкой полезными умениями, а дерзость Арьи навлекает на семью Старков неприятности.",
      "overview_en": "While Bran recovers from his fall, Ned takes only his daughters to Kings Landing. Jon Snow goes with his uncle Benjen to The Wall. Tyrion joins them.",
      "short_overview_ru": null,
      "short_overview_en": null,
      "runtime": 56,
      "rating_imdb": 8.6,
      "votes_imdb": 62610,
      "rating_kr": 8.6,
      "still_url": "https://image.tmdb.org/t/p/original/l0GJx3IR8YasbztTJi5uK0XqkEo.jpg"
    }
  ],
  "limit": 2,
  "offset": 0,
  "total": 10
}
```

### Сводка по сезонам

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "group=season" \
  --data-urlencode "limit=3" \
  "https://api.kinodata.space/v1.3/titles/tmdb_tv/1399/episodes"
```

Ответ `200`:

```json
{
  "has_more": false,
  "items": [
    {
      "episodes": 10,
      "first_air": "2011-04-17",
      "last_air": "2011-06-19",
      "rating_imdb": 9,
      "season": 1,
      "specials": false,
      "votes_imdb": 643460
    },
    {
      "episodes": 10,
      "first_air": "2012-04-01",
      "last_air": "2012-06-03",
      "rating_imdb": 8.8,
      "season": 2,
      "specials": false,
      "votes_imdb": 531339
    },
    {
      "episodes": 10,
      "first_air": "2013-03-31",
      "last_air": "2013-06-09",
      "rating_imdb": 8.9,
      "season": 3,
      "specials": false,
      "votes_imdb": 636474
    },
    {
      "episodes": 10,
      "first_air": "2014-04-06",
      "last_air": "2014-06-15",
      "rating_imdb": 9.3,
      "season": 4,
      "specials": false,
      "votes_imdb": 697072
    },
    {
      "episodes": 10,
      "first_air": "2015-04-12",
      "last_air": "2015-06-14",
      "rating_imdb": 8.7,
      "season": 5,
      "specials": false,
      "votes_imdb": 607701
    },
    {
      "episodes": 10,
      "first_air": "2016-04-24",
      "last_air": "2016-06-26",
      "rating_imdb": 9,
      "season": 6,
      "specials": false,
      "votes_imdb": 1058322
    },
    {
      "episodes": 7,
      "first_air": "2017-07-16",
      "last_air": "2017-08-27",
      "rating_imdb": 9,
      "season": 7,
      "specials": false,
      "votes_imdb": 572719
    },
    {
      "episodes": 6,
      "first_air": "2019-04-14",
      "last_air": "2019-05-19",
      "rating_imdb": 6.4,
      "season": 8,
      "specials": false,
      "votes_imdb": 1317209
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": 8
}
```

### У фильма

```bash
curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.3/titles/kp/447301/episodes"
```

Ответ `200`:

```json
{
  "has_more": false,
  "items": [],
  "limit": 1000,
  "offset": 0,
  "total": 0
}
```

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

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

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "season": 1,
      "episode": 1,
      "special": false,
      "imdb_id": "tt1480055",
      "air_date": "2011-04-17",
      "name_en": "Winter Is Coming",
      "name_original": null,
      "overview_en": "Jon Arryn, the Hand of the King, is dead. King Robert Baratheon plans to ask his oldest friend, Eddard Stark, to take Jon's place. Across the sea, Viserys Targaryen plans to wed his sister to a nomadic warlord in exchange for an army.",
      "short_overview_en": null,
      "runtime": 62,
      "rating_imdb": 8.9,
      "votes_imdb": 82456,
      "rating_kr": 8.4,
      "still_url": "https://image.tmdb.org/t/p/original/o4IX9Mm0kpLITVANJMx7inyEUaY.jpg"
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": 10
}
```