# Расхождения оценок

> Тайтлы, которые на Кинопоиске и IMDb оценили по-разному.

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

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

`divergence` — оценка Кинопоиска минус оценка IMDb. Больше нуля — Кинопоиск ставит выше: турецкий сериал «Последний император» там 8.0, на IMDb 5.1. Меньше нуля — выше IMDb: «Анна Болейн» на Кинопоиске 1.6, на IMDb 5.6.

По умолчанию берутся тайтлы с 10 000 голосов на обоих сайтах и расхождением от 1 балла, сильные расхождения — первыми. `direction=ru` оставляет те, что выше на Кинопоиске, `direction=west` — выше на IMDb.

Фильтры, `sort` и `fields` — как в [каталоге](https://kinodata.space/ru/docs/titles.md), и `total` их учитывает. Отсортировать по расхождению можно и в самом каталоге: `/titles?sort=-divergence`.

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

- `direction` (enum) — `ru` — выше на Кинопоиске, `west` — выше на IMDb.
  Значения: `ru`, `west`.
  По умолчанию: оба направления. Пример: `direction=ru`.
- `min_votes` (integer) — Сколько голосов нужно на каждом из двух сайтов.
  По умолчанию: 10000. Пример: `min_votes=100000`.
- `min_delta` (number) — Наименьшее расхождение в баллах, от 0 до 10.
  По умолчанию: 1.0. Пример: `min_delta=2`.
- `фильтры, sort и fields` — Фильтры, сортировка и выбор полей каталога, как в [Фильтры и сортировка](https://kinodata.space/ru/docs/filters.md). Поле расхождения в `fields` — `divergence`.
  По умолчанию: сильные расхождения первыми. Пример: `kind=movie&sort=-year`.
- `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.

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

- `direction` (enum | null) — `direction` из запроса. `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`.
  - `divergence` (number) — Оценка Кинопоиска минус оценка IMDb.
- `total` (integer) — Сколько тайтлов подходит под запрос, с фильтрами.
- `limit`, `offset`, `has_more` — Пагинация — как в [любом списке](https://kinodata.space/ru/docs/lists.md#форма-списка).

## Ошибки

| статус | код | когда |
|---|---|---|
| 400 | `invalid_request` | Неизвестный `direction`; `min_delta` не число от 0 до 10; неизвестный фильтр, ключ `sort` или поле в `fields`; параметр другого эндпоинта (например, `role` или `relation`); `limit` не целое от 1 или `offset` меньше 0; `cursor` — витрина листается `offset`. |
| 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_kp,rating_imdb,divergence" \
  "https://api.kinodata.space/v1.3/discover/divergence"
```

Ответ `200`:

```json
{
  "direction": null,
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt13406036",
      "kp_id": "2000450",
      "tmdb_id": null,
      "tmdb_tv_id": "126400",
      "kinorium_id": "2655539",
      "title_ru": "Анна Болейн",
      "title_en": "Anne Boleyn",
      "year": 2021,
      "rating_kp": 1.6,
      "rating_imdb": 5.6,
      "divergence": -4
    },
    {
      "imdb_id": "tt1486193",
      "kp_id": "479701",
      "tmdb_id": "50601",
      "tmdb_tv_id": null,
      "kinorium_id": "495470",
      "title_ru": "5 дней в августе",
      "title_en": "5 Days of War",
      "year": 2011,
      "rating_kp": 1.6,
      "rating_imdb": 5.6,
      "divergence": -4
    },
    {
      "imdb_id": "tt6536562",
      "kp_id": "1045683",
      "tmdb_id": null,
      "tmdb_tv_id": "70788",
      "kinorium_id": "1622848",
      "title_ru": "Последний император",
      "title_en": "The Last Emperor: Abdul Hamid II",
      "year": 2017,
      "rating_kp": 8,
      "rating_imdb": 5.1,
      "divergence": 2.9
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": 780
}
```

### Выше на Кинопоиске

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

Ответ `200`:

```json
{
  "direction": "ru",
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt4877122",
      "kp_id": "957805",
      "tmdb_id": "378236",
      "tmdb_tv_id": null,
      "kinorium_id": "1555483",
      "title_ru": "Эмоджи фильм",
      "title_en": "The Emoji Movie",
      "year": 2017,
      "rating_kp": 5.9,
      "rating_imdb": 3.5,
      "divergence": 2.4
    },
    {
      "imdb_id": "tt0327554",
      "kp_id": "3523",
      "tmdb_id": "314",
      "tmdb_tv_id": null,
      "kinorium_id": "258070",
      "title_ru": "Женщина-кошка",
      "title_en": "Catwoman",
      "year": 2004,
      "rating_kp": 5.8,
      "rating_imdb": 3.5,
      "divergence": 2.3
    },
    {
      "imdb_id": "tt0810913",
      "kp_id": "462883",
      "tmdb_id": "71880",
      "tmdb_tv_id": null,
      "kinorium_id": "382922",
      "title_ru": "Такие разные близнецы",
      "title_en": "Jack and Jill",
      "year": 2011,
      "rating_kp": 5.2,
      "rating_imdb": 3.3,
      "divergence": 1.9
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": 197
}
```

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

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

Ответ `200`:

```json
{
  "direction": null,
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt13406036",
      "kp_id": "2000450",
      "tmdb_id": null,
      "tmdb_tv_id": "126400",
      "kinorium_id": "2655539",
      "title_en": "Anne Boleyn",
      "year": 2021,
      "rating_kp": 1.6,
      "rating_imdb": 5.6,
      "divergence": -4
    },
    {
      "imdb_id": "tt1486193",
      "kp_id": "479701",
      "tmdb_id": "50601",
      "tmdb_tv_id": null,
      "kinorium_id": "495470",
      "title_en": "5 Days of War",
      "year": 2011,
      "rating_kp": 1.6,
      "rating_imdb": 5.6,
      "divergence": -4
    },
    {
      "imdb_id": "tt6536562",
      "kp_id": "1045683",
      "tmdb_id": null,
      "tmdb_tv_id": "70788",
      "kinorium_id": "1622848",
      "title_en": "The Last Emperor: Abdul Hamid II",
      "year": 2017,
      "rating_kp": 8,
      "rating_imdb": 5.1,
      "divergence": 2.9
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": 780
}
```