# Топ

> Лучшие по оценке фильмы и сериалы с порогом голосов — для рейтингов и «топ-100».

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

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

Топ — это каталог с пресетом `top`: тот же ответ даёт `/titles?preset=top`. В него попадают тайтлы, у которых на IMDb не меньше 100 000 голосов, есть оценка Кинопоиска и постер, и идут они по оценке IMDb. Порог отсекает оценки, которые поставили несколько человек.

Работает всё, что понимает каталог: фильтры, `q`, `sort`, `fields` и курсор. `order=asc` переворачивает топ: первой идёт «Белоснежка» 2025 года с 2.2. Порог можно сдвинуть `votes_imdb.gte`. Это нужно для кино, которое мало смотрят за рубежом: «Бригада» и «Остров» набирают на IMDb 10–20 тысяч голосов, и с порогом 100 000 их в топе нет. `country=ru&votes_imdb.gte=10000` даёт «Бригаду», «Дурака», «Возвращение» и «Остров».

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

- `фильтры, q и sort` — Всё, что понимает [каталог](https://kinodata.space/ru/docs/titles.md): фильтры, поиск `q`, `sort` со знаком, `fields` и курсор `cursor`. Подробно — в [Фильтры и сортировка](https://kinodata.space/ru/docs/filters.md).
  Пример: `kind=movie&country=fr`.
- `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.

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

- `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`.
- `total` (null) — Как в каталоге: общее число не считается. Листайте по `has_more` или курсором.
- `limit`, `offset`, `has_more`, `next_cursor` — Пагинация — как в [каталоге](https://kinodata.space/ru/docs/titles.md).

## Ошибки

| статус | код | когда |
|---|---|---|
| 400 | `invalid_request` | Всё, что даёт `400` в каталоге, и свой `preset`: эта витрина — уже `preset=top`. |
| 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_imdb,votes_imdb" \
  "https://api.kinodata.space/v1.3/charts/top"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0903747",
      "kp_id": "404900",
      "tmdb_id": null,
      "tmdb_tv_id": "1396",
      "kinorium_id": "400796",
      "title_ru": "Во все тяжкие",
      "title_en": "Breaking Bad",
      "year": 2008,
      "rating_imdb": 9.5,
      "votes_imdb": 2671962
    },
    {
      "imdb_id": "tt5491994",
      "kp_id": "1007472",
      "tmdb_id": null,
      "tmdb_tv_id": "68595",
      "kinorium_id": "1605088",
      "title_ru": "Планета Земля 2",
      "title_en": "Planet Earth II",
      "year": 2016,
      "rating_imdb": 9.4,
      "votes_imdb": 175688
    },
    {
      "imdb_id": "tt0795176",
      "kp_id": "279548",
      "tmdb_id": null,
      "tmdb_tv_id": "1044",
      "kinorium_id": "379535",
      "title_ru": "Планета Земля",
      "title_en": "Planet Earth",
      "year": 2006,
      "rating_imdb": 9.4,
      "votes_imdb": 235430
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}
```

### Российское кино

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "country=ru" \
  --data-urlencode "votes_imdb.gte=10000" \
  --data-urlencode "limit=4" \
  --data-urlencode "fields=title,year,rating_imdb,votes_imdb" \
  "https://api.kinodata.space/v1.3/charts/top"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0337898",
      "kp_id": "77039",
      "tmdb_id": null,
      "tmdb_tv_id": "30877",
      "kinorium_id": "265889",
      "title_ru": "Бригада",
      "title_en": "Brigada",
      "year": 2002,
      "rating_imdb": 8.3,
      "votes_imdb": 11920
    },
    {
      "imdb_id": "tt3560686",
      "kp_id": "808639",
      "tmdb_id": "285700",
      "tmdb_tv_id": null,
      "kinorium_id": "744021",
      "title_ru": "Дурак",
      "title_en": "The Fool",
      "year": 2014,
      "rating_imdb": 8,
      "votes_imdb": 18872
    },
    {
      "imdb_id": "tt0376968",
      "kp_id": "47040",
      "tmdb_id": "11190",
      "tmdb_tv_id": null,
      "kinorium_id": "294021",
      "title_ru": "Возвращение",
      "title_en": "The Return",
      "year": 2003,
      "rating_imdb": 7.9,
      "votes_imdb": 48111
    },
    {
      "imdb_id": "tt0851577",
      "kp_id": "257337",
      "tmdb_id": "22358",
      "tmdb_tv_id": null,
      "kinorium_id": "392732",
      "title_ru": "Остров",
      "title_en": "The Island",
      "year": 2006,
      "rating_imdb": 7.8,
      "votes_imdb": 13304
    }
  ],
  "limit": 4,
  "offset": 0,
  "total": null
}
```

### Снизу вверх

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "order=asc" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,rating_imdb,votes_imdb" \
  "https://api.kinodata.space/v1.3/charts/top"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt6208148",
      "kp_id": "1009713",
      "tmdb_id": "447273",
      "tmdb_tv_id": null,
      "kinorium_id": "1618157",
      "title_ru": "Белоснежка",
      "title_en": "Snow White",
      "year": 2025,
      "rating_imdb": 2.2,
      "votes_imdb": 396915
    },
    {
      "imdb_id": "tt0799949",
      "kp_id": "260526",
      "tmdb_id": "9760",
      "tmdb_tv_id": null,
      "kinorium_id": "380419",
      "title_ru": "Очень эпическое кино",
      "title_en": "Epic Movie",
      "year": 2006,
      "rating_imdb": 2.5,
      "votes_imdb": 113889
    },
    {
      "imdb_id": "tt12915716",
      "kp_id": "1400400",
      "tmdb_id": "734253",
      "tmdb_tv_id": null,
      "kinorium_id": "2454330",
      "title_ru": "Адипуруш",
      "title_en": "Adipurush",
      "year": 2023,
      "rating_imdb": 2.6,
      "votes_imdb": 137652
    }
  ],
  "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_imdb,votes_imdb" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/charts/top"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0903747",
      "kp_id": "404900",
      "tmdb_id": null,
      "tmdb_tv_id": "1396",
      "kinorium_id": "400796",
      "title_en": "Breaking Bad",
      "year": 2008,
      "rating_imdb": 9.5,
      "votes_imdb": 2671962
    },
    {
      "imdb_id": "tt5491994",
      "kp_id": "1007472",
      "tmdb_id": null,
      "tmdb_tv_id": "68595",
      "kinorium_id": "1605088",
      "title_en": "Planet Earth II",
      "year": 2016,
      "rating_imdb": 9.4,
      "votes_imdb": 175688
    },
    {
      "imdb_id": "tt0795176",
      "kp_id": "279548",
      "tmdb_id": null,
      "tmdb_tv_id": "1044",
      "kinorium_id": "379535",
      "title_en": "Planet Earth",
      "year": 2006,
      "rating_imdb": 9.4,
      "votes_imdb": 235430
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}
```