# Filter values

> Which genres, countries, platforms, tags and companies the database holds and how many titles each has, for dropdowns.

> Documentation index for agents: https://kinodata.space/en/llms.txt — the whole documentation in one file: https://kinodata.space/en/llms-full.txt

Request: `GET https://api.kinodata.space/v1.3/filters`

Values for the catalog’s filters and how many titles each has, largest first. Build dropdowns and type-ahead hints from it.

Every facet row has one shape: `value`, exactly what you pass to the filter; the labels `label_ru` and `label_en`; and the title count `count`. Tags add `kind`, platforms add `country` and `poster_url`.

| facet | catalog filter |
|---|---|
| `genres` | `genre` |
| `countries` | `country` |
| `regions` | `region` |
| `kinds` | `kind` |
| `platforms` | `platform` |
| `tags` | `tag` |
| `companies` | `companies` |

Each facet holds its first 50 values by default, and `{facet}_total` says how many there are in all. `facet` keeps the facets you need, `limit` changes the cap, and `limit=0` lifts it. `q` searches the labels in both languages, and for tags and companies it searches the whole dictionary, not just the values shown: `q=steampunk` finds the “Steampunk” tag, `q=A24` the A24 studio, `q=США` the US platforms. Companies stop at 5,000 rows even with `limit=0`; the full number is in `companies_total`.

`presets` expands the [presets](https://kinodata.space/en/docs/filters.md#ready-made-sets-preset) into ordinary filters: start from one and adjust it.

## Query parameters

- `facet` (csv) — Which facets to return, comma-separated. `country_decades`, the number of titles per country by decade, comes only when you name it.
  Values: `genres`, `countries`, `kinds`, `regions`, `platforms`, `tags`, `companies`, `country_decades`.
  Default: all but `country_decades`. Example: `facet=genres,countries`.
- `q` (string) — Keep the values whose label contains this string, in any language: `q=net` finds Netflix. For tags and companies it searches the whole dictionary.
  Example: `q=net`.
- `limit` (integer) — How many values to return per facet. `0` means no cap.
  Default: 50. Example: `limit=0`.
- `lang` (ru | en) — Keep one language in the response. Without it, text fields come in `_ru` and `_en` pairs. More in [Response languages](https://kinodata.space/en/docs/languages.md).
  Example: `lang=en`.

## Response fields

- `{facet}` (array) — A facet’s values: `genres`, `countries`, `kinds`, `regions`, `platforms`, `tags`, `companies`.
  - `value` (string) — What to pass to the catalog filter: `drama`, `us`, `netflix`.
  - `label_ru`, `label_en` (string | null) — The label in Russian and in English.
  - `count` (integer) — How many titles have this value.
  - `kind` (enum) — Tags only: a subgenre, keyword or mood, from the `tag_kinds` set.
  - `country`, `poster_url` (string | null) — Platforms only: the country as an ISO 3166-1 code (`us` for ABC) and the logo.
- `{facet}_total` (integer) — How many values the facet holds with `q` applied, before the `limit` cap.
- `year_range` (object) — The earliest and latest year in the database: `min`, `max`.
- `presets` (array) — The catalog’s presets: the same row as the `presets` set in `/enums` (`value`, `label_ru`, `label_en`), plus `filters`, what the preset expands to.
- `country_decades` (array) — On request only: a row like a country’s, plus `decades`, titles by decade, `decade` and `count`.

## Errors

| status | code | when |
|---|---|---|
| 400 | `invalid_request` | An unknown facet in `facet`, with the allowed ones in the response; `limit` is not a whole number from 0; a parameter the facets don’t take (such as `genre`), with the allowed ones in the response. |
| 401 | `unauthorized` | The `X-API-Key` header is missing, or the key is unknown or revoked. |
| 429 | `rate_limited` | The per-second rate limit or the daily quota is used up. |

Every code and what to do about it is on the [Errors](https://kinodata.space/en/docs/errors.md) page.

## Examples

### English only

```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"
```

Response `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"
      ]
    }
  ]
}
```

### Both languages

```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"
```

Response `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"
      ]
    }
  ]
}
```

### Find a platform

```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"
```

Response `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"
      ]
    }
  ]
}
```

### Countries by decade

```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"
```

Response `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"
      ]
    }
  ]
}
```

### Unknown facet

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

Response `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\"?"
  }
}
```