# Значения фильтров

> Какие жанры, страны, площадки, метки и компании есть в базе и сколько у каждого тайтлов — для выпадающих списков.

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

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

Значения для фильтров каталога и число тайтлов у каждого, от большего к меньшему. Отсюда берутся пункты выпадающих списков и подсказки при вводе.

Строка фасета везде одна: `value` — ровно то, что передаётся в фильтр, подписи `label_ru` и `label_en`, число тайтлов `count`. У меток к ним добавляется `kind`, у площадок — `country` и `poster_url`.

| фасет | фильтр каталога |
|---|---|
| `genres` | `genre` |
| `countries` | `country` |
| `regions` | `region` |
| `kinds` | `kind` |
| `platforms` | `platform` |
| `tags` | `tag` |
| `companies` | `companies` |

В каждом фасете по умолчанию 50 первых значений, а `{фасет}_total` говорит, сколько их всего. `facet` оставляет нужные фасеты, `limit` меняет предел, `limit=0` снимает его. `q` ищет по подписям на обоих языках, а у меток и компаний — по всему словарю, а не только по показанным: `q=steampunk` находит метку «Стимпанк» по английской подписи, `q=A24` — студию A24, `q=США` — площадки США. Компаний в ответе не больше 5 000 даже с `limit=0`, полное число — в `companies_total`.

`presets` раскрывает [пресеты](https://kinodata.space/ru/docs/filters.md#готовые-наборы-preset) в обычные фильтры — их можно взять за основу и поменять.

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

- `facet` (csv) — Какие фасеты вернуть, через запятую. `country_decades` — число тайтлов каждой страны по десятилетиям — приходит, только если его назвать.
  Значения: `genres`, `countries`, `kinds`, `regions`, `platforms`, `tags`, `companies`, `country_decades`.
  По умолчанию: все, кроме `country_decades`. Пример: `facet=genres,countries`.
- `q` (string) — Оставить значения, в подписи которых есть эта строка, на любом языке: `q=net` находит Netflix. У меток и компаний ищет по всему словарю.
  Пример: `q=net`.
- `limit` (integer) — Сколько значений вернуть в каждом фасете. `0` — без предела.
  По умолчанию: 50. Пример: `limit=0`.
- `lang` (ru | en) — Оставить в ответе один язык. Без него текстовые поля приходят парами `_ru` и `_en`. Подробнее — [Языки ответа](https://kinodata.space/ru/docs/languages.md).
  Пример: `lang=en`.

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

- `{фасет}` (array) — Значения фасета: `genres`, `countries`, `kinds`, `regions`, `platforms`, `tags`, `companies`.
  - `value` (string) — Что передать в фильтр каталога: `drama`, `us`, `netflix`.
  - `label_ru`, `label_en` (string | null) — Подпись на русском и на английском.
  - `count` (integer) — Сколько тайтлов с этим значением.
  - `kind` (enum) — Только у меток: поджанр, ключевое слово или настроение — набор `tag_kinds`.
  - `country`, `poster_url` (string | null) — Только у площадок: страна кодом ISO 3166-1 («ABC» — `us`) и логотип.
- `{фасет}_total` (integer) — Сколько значений в фасете с учётом `q`, до предела `limit`.
- `year_range` (object) — Самый ранний и самый поздний год в базе: `min`, `max`.
- `presets` (array) — Пресеты каталога — та же строка, что в наборе `presets` в `/enums` (`value`, `label_ru`, `label_en`), и `filters`: во что пресет раскрывается.
- `country_decades` (array) — Только по запросу: строка как у стран и `decades` — число тайтлов по десятилетиям, `decade` и `count`.

## Ошибки

| статус | код | когда |
|---|---|---|
| 400 | `invalid_request` | Неизвестный фасет в `facet` — в ответе список допустимых; `limit` не целое от 0; параметр, которого фасеты не понимают (например, `genre`), — в ответе список допустимых. |
| 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 "facet=genres,kinds" \
  --data-urlencode "limit=3" \
  "https://api.kinodata.space/v1.3/filters"
```

Ответ `200`:

```json
{
  "genres": [
    {
      "value": "drama",
      "label_ru": "Драма",
      "label_en": "Drama",
      "count": 459723
    },
    {
      "value": "comedy",
      "label_ru": "Комедия",
      "label_en": "Comedy",
      "count": 281187
    },
    {
      "value": "documentary",
      "label_ru": "Документальный",
      "label_en": "Documentary",
      "count": 234004
    }
  ],
  "genres_total": 24,
  "kinds": [
    {
      "value": "movie",
      "label_ru": "Фильмы",
      "label_en": "Movies",
      "count": 713590
    },
    {
      "value": "short",
      "label_ru": "Короткометражки",
      "label_en": "Shorts",
      "count": 517140
    },
    {
      "value": "series",
      "label_ru": "Сериалы",
      "label_en": "Series",
      "count": 172872
    }
  ],
  "kinds_total": 7,
  "year_range": {
    "min": 1888,
    "max": 2031
  },
  "presets": [
    {
      "value": "top",
      "label_ru": "Топ",
      "label_en": "Top rated",
      "filters": [
        "sort=-rating_imdb",
        "votes_imdb.gte=100000",
        "required=rating_kp,poster"
      ]
    },
    {
      "value": "hidden_gems",
      "label_ru": "Скрытые жемчужины",
      "label_en": "Hidden gems",
      "filters": [
        "sort=-rating_weighted",
        "kind=movie,series,mini_series,cartoon,anime",
        "votes_kp.gte=1000",
        "votes_kp.lte=50000",
        "votes_imdb.gte=1000",
        "votes_imdb.lte=25000",
        "genre.not=music,documentary,concert,stand_up,theatre",
        "required=poster"
      ]
    },
    {
      "value": "trending",
      "label_ru": "В тренде",
      "label_en": "Trending",
      "filters": [
        "sort=-popularity",
        "released=true"
      ]
    },
    {
      "value": "new",
      "label_ru": "Новинки",
      "label_en": "New releases",
      "filters": [
        "release_date.gte=<30 days ago>",
        "released=true",
        "sort=-release_date"
      ]
    },
    {
      "value": "classics",
      "label_ru": "Классика",
      "label_en": "Classics",
      "filters": [
        "year.lte=1980",
        "votes_imdb.gte=50000",
        "sort=-rating_imdb"
      ]
    }
  ]
}
```

### Поиск площадки

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "facet=tags,companies" \
  --data-urlencode "q=steampunk" \
  --data-urlencode "limit=3" \
  "https://api.kinodata.space/v1.3/filters"
```

Ответ `200`:

```json
{
  "tags": [
    {
      "value": "стимпанк",
      "label_ru": "Стимпанк",
      "label_en": "Steampunk",
      "count": 114,
      "kind": "subgenre"
    }
  ],
  "tags_total": 1,
  "companies": [
    {
      "value": "Steampunk Lily Films",
      "label_ru": "Steampunk Lily Films",
      "label_en": "Steampunk Lily Films",
      "count": 3
    },
    {
      "value": "Neo-Steampunk",
      "label_ru": "Neo-Steampunk",
      "label_en": "Neo-Steampunk",
      "count": 1
    },
    {
      "value": "Steampunk Molly Productions",
      "label_ru": "Steampunk Molly Productions",
      "label_en": "Steampunk Molly Productions",
      "count": 1
    }
  ],
  "companies_total": 3,
  "year_range": {
    "min": 1888,
    "max": 2031
  },
  "presets": [
    {
      "value": "top",
      "label_ru": "Топ",
      "label_en": "Top rated",
      "filters": [
        "sort=-rating_imdb",
        "votes_imdb.gte=100000",
        "required=rating_kp,poster"
      ]
    },
    {
      "value": "hidden_gems",
      "label_ru": "Скрытые жемчужины",
      "label_en": "Hidden gems",
      "filters": [
        "sort=-rating_weighted",
        "kind=movie,series,mini_series,cartoon,anime",
        "votes_kp.gte=1000",
        "votes_kp.lte=50000",
        "votes_imdb.gte=1000",
        "votes_imdb.lte=25000",
        "genre.not=music,documentary,concert,stand_up,theatre",
        "required=poster"
      ]
    },
    {
      "value": "trending",
      "label_ru": "В тренде",
      "label_en": "Trending",
      "filters": [
        "sort=-popularity",
        "released=true"
      ]
    },
    {
      "value": "new",
      "label_ru": "Новинки",
      "label_en": "New releases",
      "filters": [
        "release_date.gte=<30 days ago>",
        "released=true",
        "sort=-release_date"
      ]
    },
    {
      "value": "classics",
      "label_ru": "Классика",
      "label_en": "Classics",
      "filters": [
        "year.lte=1980",
        "votes_imdb.gte=50000",
        "sort=-rating_imdb"
      ]
    }
  ]
}
```

### Страны по десятилетиям

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "facet=country_decades" \
  --data-urlencode "limit=1" \
  "https://api.kinodata.space/v1.3/filters"
```

Ответ `200`:

```json
{
  "country_decades": [
    {
      "value": "us",
      "label_ru": "США",
      "label_en": "United States",
      "count": 452521,
      "decades": [
        {
          "decade": 1890,
          "count": 363
        },
        {
          "decade": 1900,
          "count": 1584
        },
        {
          "decade": 1910,
          "count": 18750
        },
        {
          "decade": 1920,
          "count": 8777
        },
        {
          "decade": 1930,
          "count": 7985
        },
        {
          "decade": 1940,
          "count": 7490
        },
        {
          "decade": 1950,
          "count": 7086
        },
        {
          "decade": 1960,
          "count": 6933
        },
        {
          "decade": 1970,
          "count": 10986
        },
        {
          "decade": 1980,
          "count": 16600
        },
        {
          "decade": 1990,
          "count": 30642
        },
        {
          "decade": 2000,
          "count": 73017
        },
        {
          "decade": 2010,
          "count": 162910
        },
        {
          "decade": 2020,
          "count": 84936
        },
        {
          "decade": 2030,
          "count": 4
        }
      ]
    }
  ],
  "country_decades_total": 148,
  "year_range": {
    "min": 1888,
    "max": 2031
  },
  "presets": [
    {
      "value": "top",
      "label_ru": "Топ",
      "label_en": "Top rated",
      "filters": [
        "sort=-rating_imdb",
        "votes_imdb.gte=100000",
        "required=rating_kp,poster"
      ]
    },
    {
      "value": "hidden_gems",
      "label_ru": "Скрытые жемчужины",
      "label_en": "Hidden gems",
      "filters": [
        "sort=-rating_weighted",
        "kind=movie,series,mini_series,cartoon,anime",
        "votes_kp.gte=1000",
        "votes_kp.lte=50000",
        "votes_imdb.gte=1000",
        "votes_imdb.lte=25000",
        "genre.not=music,documentary,concert,stand_up,theatre",
        "required=poster"
      ]
    },
    {
      "value": "trending",
      "label_ru": "В тренде",
      "label_en": "Trending",
      "filters": [
        "sort=-popularity",
        "released=true"
      ]
    },
    {
      "value": "new",
      "label_ru": "Новинки",
      "label_en": "New releases",
      "filters": [
        "release_date.gte=<30 days ago>",
        "released=true",
        "sort=-release_date"
      ]
    },
    {
      "value": "classics",
      "label_ru": "Классика",
      "label_en": "Classics",
      "filters": [
        "year.lte=1980",
        "votes_imdb.gte=50000",
        "sort=-rating_imdb"
      ]
    }
  ]
}
```

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

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "facet=genres,kinds" \
  --data-urlencode "limit=3" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/filters"
```

Ответ `200`:

```json
{
  "genres": [
    {
      "value": "drama",
      "label_en": "Drama",
      "count": 459723
    },
    {
      "value": "comedy",
      "label_en": "Comedy",
      "count": 281187
    },
    {
      "value": "documentary",
      "label_en": "Documentary",
      "count": 234004
    }
  ],
  "genres_total": 24,
  "kinds": [
    {
      "value": "movie",
      "label_en": "Movies",
      "count": 713590
    },
    {
      "value": "short",
      "label_en": "Shorts",
      "count": 517140
    },
    {
      "value": "series",
      "label_en": "Series",
      "count": 172872
    }
  ],
  "kinds_total": 7,
  "year_range": {
    "min": 1888,
    "max": 2031
  },
  "presets": [
    {
      "value": "top",
      "label_en": "Top rated",
      "filters": [
        "sort=-rating_imdb",
        "votes_imdb.gte=100000",
        "required=rating_kp,poster"
      ]
    },
    {
      "value": "hidden_gems",
      "label_en": "Hidden gems",
      "filters": [
        "sort=-rating_weighted",
        "kind=movie,series,mini_series,cartoon,anime",
        "votes_kp.gte=1000",
        "votes_kp.lte=50000",
        "votes_imdb.gte=1000",
        "votes_imdb.lte=25000",
        "genre.not=music,documentary,concert,stand_up,theatre",
        "required=poster"
      ]
    },
    {
      "value": "trending",
      "label_en": "Trending",
      "filters": [
        "sort=-popularity",
        "released=true"
      ]
    },
    {
      "value": "new",
      "label_en": "New releases",
      "filters": [
        "release_date.gte=<30 days ago>",
        "released=true",
        "sort=-release_date"
      ]
    },
    {
      "value": "classics",
      "label_en": "Classics",
      "filters": [
        "year.lte=1980",
        "votes_imdb.gte=50000",
        "sort=-rating_imdb"
      ]
    }
  ]
}
```

### Неизвестный фасет

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

Ответ `400`:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "unknown facet \"genre\"",
    "field": "facet",
    "allowed": [
      "genres",
      "countries",
      "kinds",
      "regions",
      "platforms",
      "tags",
      "companies",
      "country_decades"
    ],
    "hint": "did you mean \"genres\"?"
  }
}
```