# Скрытые жемчужины

> Высоко оценённые фильмы и сериалы, о которых знает не так много людей.

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

Запрос: `GET https://api.kinodata.space/v1.3/discover/hidden-gems`

Жемчужины — это каталог с пресетом `hidden_gems`: тот же ответ даёт `/titles?preset=hidden_gems`. Жемчужина — тайтл, у которого 1 000–50 000 голосов на Кинопоиске и 1 000–25 000 на IMDb: его оценили всерьёз, но знают его немногие. Короткий метр, ТВ-шоу, концерты, стендапы, записи спектаклей (жанр `theatre`), музыка и документальное кино не попадают.

Идут по `rating_weighted` — средней оценке Кинопоиска, IMDb и TMDB, взвешенной по числу голосов. По умолчанию наверху много сериалов, среди них азиатские; `kind=movie` даёт фильмы: «День Доктора», «Кто там поёт», «Марафонцы бегут круг почета», «Красивые деревни красиво горят».

Работает всё, что понимает каталог: фильтры, `q`, `sort`, `fields` и курсор.

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

- `фильтры, 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=hidden_gems`. |
| 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 "kind=movie" \
  --data-urlencode "limit=4" \
  --data-urlencode "fields=title,year,rating_kp,rating_imdb,votes_kp,votes_imdb" \
  "https://api.kinodata.space/v1.3/discover/hidden-gems"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt2779318",
      "kp_id": "807086",
      "tmdb_id": "313106",
      "tmdb_tv_id": null,
      "kinorium_id": "742468",
      "title_ru": "День Доктора",
      "title_en": "The Day of the Doctor",
      "year": 2013,
      "rating_kp": 8.1,
      "rating_imdb": 9.3,
      "votes_kp": 20240,
      "votes_imdb": 21122
    },
    {
      "imdb_id": "tt0076276",
      "kp_id": "56709",
      "tmdb_id": "17909",
      "tmdb_tv_id": null,
      "kinorium_id": "70591",
      "title_ru": "Кто там поёт",
      "title_en": "Who's Singin' Over There?",
      "year": 1980,
      "rating_kp": 7.7,
      "rating_imdb": 8.7,
      "votes_kp": 1028,
      "votes_imdb": 18000
    },
    {
      "imdb_id": "tt0084302",
      "kp_id": "84473",
      "tmdb_id": "29450",
      "tmdb_tv_id": null,
      "kinorium_id": "77675",
      "title_ru": "Марафонцы бегут круг почета",
      "title_en": "The Marathon Family",
      "year": 1982,
      "rating_kp": 7,
      "rating_imdb": 8.8,
      "votes_kp": 2127,
      "votes_imdb": 18202
    },
    {
      "imdb_id": "tt0116860",
      "kp_id": "70816",
      "tmdb_id": "29927",
      "tmdb_tv_id": null,
      "kinorium_id": "106040",
      "title_ru": "Красивые деревни красиво горят",
      "title_en": "Pretty Village, Pretty Flame",
      "year": 1996,
      "rating_kp": 7.7,
      "rating_imdb": 8.6,
      "votes_kp": 2954,
      "votes_imdb": 19026
    }
  ],
  "limit": 4,
  "offset": 0,
  "total": null
}
```

### Без фильтров

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,kind,rating_kp,rating_imdb" \
  "https://api.kinodata.space/v1.3/discover/hidden-gems"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt18224728",
      "kp_id": "4860668",
      "tmdb_id": null,
      "tmdb_tv_id": "157242",
      "kinorium_id": "8540771",
      "title_ru": "Святой Паисий: От Фарасы на небеса",
      "title_en": "Saint Paisios: From Farasa to Heaven",
      "year": 2022,
      "kind": "series",
      "rating_kp": 9.4,
      "rating_imdb": 8.9
    },
    {
      "imdb_id": "tt0809488",
      "kp_id": "260992",
      "tmdb_id": null,
      "tmdb_tv_id": "39651",
      "kinorium_id": "382558",
      "title_ru": "Крестный отец: Новелла для телевидения",
      "title_en": "The Godfather: A Novel for Television",
      "year": 1977,
      "kind": "series",
      "rating_kp": 8.7,
      "rating_imdb": 9.5
    },
    {
      "imdb_id": "tt5182866",
      "kp_id": "944829",
      "tmdb_id": null,
      "tmdb_tv_id": "64010",
      "kinorium_id": "1448428",
      "title_ru": "Вернуться в 1988",
      "title_en": "Reply 1988",
      "year": 2015,
      "kind": "series",
      "rating_kp": 8.9,
      "rating_imdb": 9
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}
```

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

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "kind=movie" \
  --data-urlencode "limit=4" \
  --data-urlencode "fields=title,year,rating_kp,rating_imdb,votes_kp,votes_imdb" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/discover/hidden-gems"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt2779318",
      "kp_id": "807086",
      "tmdb_id": "313106",
      "tmdb_tv_id": null,
      "kinorium_id": "742468",
      "title_en": "The Day of the Doctor",
      "year": 2013,
      "rating_kp": 8.1,
      "rating_imdb": 9.3,
      "votes_kp": 20240,
      "votes_imdb": 21122
    },
    {
      "imdb_id": "tt0076276",
      "kp_id": "56709",
      "tmdb_id": "17909",
      "tmdb_tv_id": null,
      "kinorium_id": "70591",
      "title_en": "Who's Singin' Over There?",
      "year": 1980,
      "rating_kp": 7.7,
      "rating_imdb": 8.7,
      "votes_kp": 1028,
      "votes_imdb": 18000
    },
    {
      "imdb_id": "tt0084302",
      "kp_id": "84473",
      "tmdb_id": "29450",
      "tmdb_tv_id": null,
      "kinorium_id": "77675",
      "title_en": "The Marathon Family",
      "year": 1982,
      "rating_kp": 7,
      "rating_imdb": 8.8,
      "votes_kp": 2127,
      "votes_imdb": 18202
    },
    {
      "imdb_id": "tt0116860",
      "kp_id": "70816",
      "tmdb_id": "29927",
      "tmdb_tv_id": null,
      "kinorium_id": "106040",
      "title_en": "Pretty Village, Pretty Flame",
      "year": 1996,
      "rating_kp": 7.7,
      "rating_imdb": 8.6,
      "votes_kp": 2954,
      "votes_imdb": 19026
    }
  ],
  "limit": 4,
  "offset": 0,
  "total": null
}
```