# Каталог и поиск

> Поиск тайтлов по названию и выборка по фильтрам из всей базы.

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

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

Главный список API: поиск, витрины и выборки по любым признакам. Фильтры, сортировка и пресеты подробно разобраны в [Фильтры и сортировка](https://kinodata.space/ru/docs/filters.md), пагинация и `fields` — в [Списки и пагинация](https://kinodata.space/ru/docs/lists.md).

Без `sort` каталог идёт по популярности, тайтлы без голосов — в конце. К сортировке по оценке добавляйте порог голосов: оценку ставят и несколько человек.

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

- `q` (string) — Поиск по названию на любом языке. Прощает опечатки: «матрца» и «matrx» найдут «Матрицу». С `q` сортировка по умолчанию — по релевантности.
  Пример: `q=матрица`.
- `фильтры` — Любой фильтр каталога с операторами `.any`, `.all`, `.not`, `.gte`, `.lte`: `kind=anime`, `country=jp`, `year.gte=1990`, `votes_imdb.gte=50000`, `person=kp:41477`. Полный список — в [Фильтры и сортировка](https://kinodata.space/ru/docs/filters.md#что-можно-фильтровать).
- `sort` (string) — Порядок: ключ со знаком, `-` — по убыванию, `+` — по возрастанию. Можно два ключа через запятую: `sort=-rating_imdb,+year`. По умолчанию — по популярности, а с `q` — по релевантности.
  Значения: `popularity`, `relevance`, `release_date`, `year`, `runtime`, `rating`, `rating_imdb`, `rating_kp`, `rating_tmdb`, `rating_kr`, `rating_letterboxd`, `rating_rt`, `rating_metacritic`, `rating_critics`, `votes_imdb`, `votes_kp`, `votes_tmdb`, `votes_kr`, `votes_letterboxd`, `votes_total`, `rating_weighted`, `divergence`, `budget`, `box_office_us`, `revenue_world`, `wins_imdb`, `oscars_won`, `random`.
  По умолчанию: `popularity`, с `q` — `relevance`. Пример: `sort=-rating_imdb`.
- `preset` (enum) — Готовый набор фильтров. Явные параметры его уточняют. Что внутри каждого — в [Фильтры и сортировка](https://kinodata.space/ru/docs/filters.md#готовые-наборы-preset).
  Значения: `top`, `hidden_gems`, `trending`, `new`, `classics`.
  Пример: `preset=top`.
- `limit` (integer) — Сколько тайтлов на странице, от 1 до 50.
  По умолчанию: 50. Пример: `limit=20`.
- `offset` (integer) — Сколько тайтлов пропустить от начала.
  По умолчанию: 0.
- `cursor` (string) — Курсор для глубокой прокрутки. Первый запрос — с пустым `cursor=`, дальше — значение `next_cursor` из ответа. Не работает с `sort=random`. Есть только у каталога.
- `fields` (csv) — Какие поля элемента вернуть: `fields=title,year`. Со знаком `-` — какие убрать: `fields=-genres`. `title` оставляет `title_ru` и `title_en`, `poster_url` — `poster_url_ru` и `poster_url_en`. ID приходят всегда.
  Значения: `title`, `title_original`, `year`, `release_date`, `kind`, `poster_url`, `posters_by_source`, `rating_kp`, `rating_tmdb`, `rating_imdb`, `rating_kr`, `rating_letterboxd`, `votes_kp`, `votes_tmdb`, `votes_imdb`, `countries`, `genres`.
  Пример: `fields=title,year`.
- `lang` (ru | en) — Оставить в ответе один язык.

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

- `items` (array) — Тайтлы.
  - `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` (integer) — Размер страницы и смещение. `offset` нет, когда вы листаете курсором.
- `has_more` (boolean) — Есть ли следующая страница.
- `next_cursor` (string | null) — Курсор следующей страницы, только если в запросе был `cursor`. `null` — дальше ничего нет.

## Ошибки

| статус | код | когда |
|---|---|---|
| 400 | `invalid_request` | Неизвестный фильтр, оператор, ключ `sort` или имя в `fields`; повторённый параметр, кроме `person`; несуществующая подборка в `collection`; параметр другого эндпоинта (например, `role` или `relation`); `limit` не число; `person.role` без `person`; `cursor` или `offset` вместе с `sort=random`; испорченный курсор. |
| 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 "q=матрица" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,rating_imdb" \
  "https://api.kinodata.space/v1.3/titles"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0133093",
      "kp_id": "301",
      "tmdb_id": "603",
      "tmdb_tv_id": null,
      "kinorium_id": "116780",
      "title_ru": "Матрица",
      "title_en": "The Matrix",
      "year": 1999,
      "rating_imdb": 8.7
    },
    {
      "imdb_id": "tt0234215",
      "kp_id": "299",
      "tmdb_id": "604",
      "tmdb_tv_id": null,
      "kinorium_id": "190315",
      "title_ru": "Матрица: Перезагрузка",
      "title_en": "The Matrix Reloaded",
      "year": 2003,
      "rating_imdb": 7.2
    },
    {
      "imdb_id": "tt0242653",
      "kp_id": "316",
      "tmdb_id": "605",
      "tmdb_tv_id": null,
      "kinorium_id": "196883",
      "title_ru": "Матрица: Революция",
      "title_en": "The Matrix Revolutions",
      "year": 2003,
      "rating_imdb": 6.7
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}
```

### С опечаткой

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "q=матрца" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,rating_imdb" \
  "https://api.kinodata.space/v1.3/titles"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0133093",
      "kp_id": "301",
      "tmdb_id": "603",
      "tmdb_tv_id": null,
      "kinorium_id": "116780",
      "title_ru": "Матрица",
      "title_en": "The Matrix",
      "year": 1999,
      "rating_imdb": 8.7
    },
    {
      "imdb_id": "tt0234215",
      "kp_id": "299",
      "tmdb_id": "604",
      "tmdb_tv_id": null,
      "kinorium_id": "190315",
      "title_ru": "Матрица: Перезагрузка",
      "title_en": "The Matrix Reloaded",
      "year": 2003,
      "rating_imdb": 7.2
    },
    {
      "imdb_id": "tt0242653",
      "kp_id": "316",
      "tmdb_id": "605",
      "tmdb_tv_id": null,
      "kinorium_id": "196883",
      "title_ru": "Матрица: Революция",
      "title_en": "The Matrix Revolutions",
      "year": 2003,
      "rating_imdb": 6.7
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}
```

### Фильтры

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "kind=anime" \
  --data-urlencode "country=jp" \
  --data-urlencode "votes_imdb.gte=50000" \
  --data-urlencode "sort=-rating_imdb" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,rating_imdb" \
  "https://api.kinodata.space/v1.3/titles"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt2560140",
      "kp_id": "749374",
      "tmdb_id": null,
      "tmdb_tv_id": "1429",
      "kinorium_id": "678289",
      "title_ru": "Атака титанов",
      "title_en": "Attack on Titan",
      "year": 2013,
      "rating_imdb": 9.1
    },
    {
      "imdb_id": "tt1355642",
      "kp_id": "452838",
      "tmdb_id": null,
      "tmdb_tv_id": "31911",
      "kinorium_id": "468024",
      "title_ru": "Стальной алхимик: Братство",
      "title_en": "Fullmetal Alchemist: Brotherhood",
      "year": 2009,
      "rating_imdb": 9.1
    },
    {
      "imdb_id": "tt14986406",
      "kp_id": "4789626",
      "tmdb_id": null,
      "tmdb_tv_id": "326913",
      "kinorium_id": "2794509",
      "title_ru": "Блич: Тысячелетняя кровавая война",
      "title_en": "Bleach: Thousand-Year Blood War",
      "year": 2022,
      "rating_imdb": 9
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}
```

### Фильмы режиссёра

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "person=kp:41477" \
  --data-urlencode "person.role=director" \
  --data-urlencode "released=true" \
  --data-urlencode "sort=-year" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year" \
  "https://api.kinodata.space/v1.3/titles"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt33764258",
      "kp_id": "6385370",
      "tmdb_id": "1368337",
      "tmdb_tv_id": null,
      "kinorium_id": "11772913",
      "title_ru": "Одиссея",
      "title_en": "The Odyssey",
      "year": 2026
    },
    {
      "imdb_id": "tt15398776",
      "kp_id": "4664634",
      "tmdb_id": "872585",
      "tmdb_tv_id": null,
      "kinorium_id": "2828885",
      "title_ru": "Оппенгеймер",
      "title_en": "Oppenheimer",
      "year": 2023
    },
    {
      "imdb_id": "tt6723592",
      "kp_id": "1236063",
      "tmdb_id": "577922",
      "tmdb_tv_id": null,
      "kinorium_id": "2023303",
      "title_ru": "Довод",
      "title_en": "Tenet",
      "year": 2020
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}
```

### Курсор

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "sort=-rating_imdb" \
  --data-urlencode "votes_imdb.gte=100000" \
  --data-urlencode "limit=2" \
  --data-urlencode "fields=title,rating_imdb" \
  --data-urlencode "cursor=" \
  "https://api.kinodata.space/v1.3/titles"
```

Ответ `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",
      "rating_imdb": 9.5
    },
    {
      "imdb_id": "tt5491994",
      "kp_id": "1007472",
      "tmdb_id": null,
      "tmdb_tv_id": "68595",
      "kinorium_id": "1605088",
      "title_ru": "Планета Земля 2",
      "title_en": "Planet Earth II",
      "rating_imdb": 9.4
    }
  ],
  "limit": 2,
  "next_cursor": "eyJzIjoicmF0aW5nX2ltZGIiLCJkIjp0cnVlLCJ2IjoiOS40MCIsImlkIjoyMjA4MDF9",
  "total": null
}
```

### Неизвестный фильтр

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "status=released" \
  "https://api.kinodata.space/v1.3/titles"
```

Ответ `400`:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "unknown query parameter \"status\"",
    "field": "status",
    "hint": "there is no status filter; the card carries type.status, the catalog filters by released"
  }
}
```

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

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

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0133093",
      "kp_id": "301",
      "tmdb_id": "603",
      "tmdb_tv_id": null,
      "kinorium_id": "116780",
      "title_en": "The Matrix",
      "year": 1999,
      "rating_imdb": 8.7
    },
    {
      "imdb_id": "tt0234215",
      "kp_id": "299",
      "tmdb_id": "604",
      "tmdb_tv_id": null,
      "kinorium_id": "190315",
      "title_en": "The Matrix Reloaded",
      "year": 2003,
      "rating_imdb": 7.2
    },
    {
      "imdb_id": "tt0242653",
      "kp_id": "316",
      "tmdb_id": "605",
      "tmdb_tv_id": null,
      "kinorium_id": "196883",
      "title_en": "The Matrix Revolutions",
      "year": 2003,
      "rating_imdb": 6.7
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}
```