Фильтры и сортировка

Каталог /titles выбирает тайтлы фильтрами и упорядочивает их параметром sort. Та же грамматика работает в подборке, связях, фильмографии, совместных работах и витринах, а фильтры — ещё и в календаре релизов: выучив её один раз, вы фильтруете любой список тайтлов.

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

{
  "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
}

Где:

kind=anime и country=jp — японское аниме;
votes_imdb.gte=50000 — не меньше 50 000 голосов на IMDb;
sort=-rating_imdb — от высокой оценки IMDb к низкой.

Операторы

К имени фильтра добавляется оператор:

оператор	что значит	пример
без оператора	равно; несколько значений через запятую — любое из них	`kind=movie,series`
`.any`	любое из перечисленных	`genre.any=drama,comedy`
`.all`	все перечисленные сразу	`genre.all=drama,war`
`.not`	кроме перечисленных	`country.not=us`
`.gte`, `.lte`	не меньше, не больше	`year.gte=1990&year.lte=1999`

Число без оператора — точное значение: year=1999 то же, что year.gte=1999&year.lte=1999. Условия разных фильтров складываются через «и».

Что можно фильтровать

группа	фильтры
ID	`imdb_id`, `kp_id`, `tmdb_id`, `tmdb_tv_id`
Вид	`kind`, `is_series`, `adult`
Даты	`year`, `release_date`, `premiere_world`, `premiere_ru`, `digital_release`, `released`, `start_year`, `end_year`
Оценки и голоса	`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`, `popularity`
Содержание	`genre`, `tag`, `country`, `region`, `original_language`, `runtime`
Компании	`companies`, `company.kind`, `platform`
Люди	`person`, `person.role`
Подборки и франшизы	`collection`, `franchise`
Сериалы	`seasons_total`, `episodes_total`
Деньги	`budget`, `box_office_us`, `revenue_world`
Награды	`wins_imdb`, `oscars_won`
Возраст	`age_limit`, `age_limit_max`, `mpaa`
Полнота данных	`required`, `has_poster`

Значения для genre, country, region, platform, tag и companies вместе с числом тайтлов отдаёт GET /filters — в поле value. Подписи всех перечислений, ключи sort и имена fields — GET /enums.

Сортировка

?sort=-rating_imdb          по убыванию
?sort=+year                 по возрастанию
?sort=-rating_imdb,+year    второй ключ решает при равенстве первого

Знак — направление, без знака — по убыванию. Ключи: 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. Имена денег и наград — те же, что в карточке тайтла.

Знак + можно передать как есть: sort=+year и sort=%2Byear работают одинаково.

Без sort каталог идёт по популярности — по сумме голосов всех источников. Тайтлы без голосов, в том числе анонсы, стоят в конце.
С поиском q по умолчанию — по релевантности.
Сортировка по полю оставляет только тайтлы, у которых оно есть. Исключение — подборка, связи и фильмография: там тайтлы без значения остаются в конце.
sort=rating берёт первую известную оценку тайтла — IMDb, затем Кинопоиск, затем TMDB — и ставит тайтлы с 50 и больше голосами выше остальных.
sort=rating_weighted — средняя оценка Кинопоиска, IMDb и TMDB, взвешенная по числу голосов: оценка, за которой больше людей, весит больше.
sort=divergence — по величине расхождения оценок Кинопоиска и IMDb: без знака и с - — сильные расхождения первыми, +divergence — самые близкие оценки первыми. Подробнее — Расхождения оценок.
sort=popularity — по сумме голосов всех источников. Фильтр popularity и поле ratings.popularity в карточке — другое число: индекс популярности TMDB.
sort=random перемешивает выборку. Листать её нельзя — повторите запрос за новой.

Оценки: ставьте порог голосов

Общего балла в карточке нет намеренно: у источников разные шкалы и аудитории, и среднее это скрыло бы. Для сортировки есть rating_weighted — среднее, взвешенное по числу голосов, — но и с ним ставьте порог. Сортировка по одной оценке без порога голосов поднимает наверх тайтлы, которые оценили несколько человек: IMDb и TMDB принимают голоса и до премьеры, поэтому десятку от одного зрителя может получить даже невышедший фильм. Ставьте порог явно:

?rating_imdb.gte=8&votes_imdb.gte=100000&sort=-rating_imdb

Порог есть у каждого источника с голосами: votes_imdb, votes_kp, votes_tmdb, votes_kr (Кинориум), votes_letterboxd.

Окно оценок

Когда важно мнение нескольких аудиторий сразу, используйте окно:

curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "rating_min=8.5" \
  --data-urlencode "rating_sources=imdb,kp" \
  --data-urlencode "rating_match=all" \
  --data-urlencode "votes_imdb.gte=500000" \
  --data-urlencode "sort=-votes_imdb" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,rating_imdb,rating_kp" \
  "https://api.kinodata.space/v1.3/titles"

Ответ200

{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0468569",
      "kp_id": "111543",
      "tmdb_id": "155",
      "tmdb_tv_id": null,
      "kinorium_id": "352641",
      "title_ru": "Тёмный рыцарь",
      "title_en": "The Dark Knight",
      "rating_kp": 8.5,
      "rating_imdb": 9.1
    },
    {
      "imdb_id": "tt0111161",
      "kp_id": "326",
      "tmdb_id": "278",
      "tmdb_tv_id": null,
      "kinorium_id": "101209",
      "title_ru": "Побег из Шоушенка",
      "title_en": "The Shawshank Redemption",
      "rating_kp": 9.1,
      "rating_imdb": 9.3
    },
    {
      "imdb_id": "tt1375666",
      "kp_id": "447301",
      "tmdb_id": "27205",
      "tmdb_tv_id": null,
      "kinorium_id": "472809",
      "title_ru": "Начало",
      "title_en": "Inception",
      "rating_kp": 8.7,
      "rating_imdb": 8.8
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}

параметр	что значит
`rating_min`, `rating_max`	Границы окна.
`rating_sources`	Чьи оценки проверять: `kp`, `imdb`, `tmdb`, `kr` (Кинориум), `letterboxd`. По умолчанию первые три.
`rating_match`	`all` — в окно попадают все названные источники. Без него хватает любого.

Люди и компании

person выбирает тайтлы с участием человека. ID передаётся с каталогом через двоеточие: kp:41477, imdb:nm0634240, tmdb:525, kinorium:476400. Несколько людей через запятую — любой из них, повтор параметра — все сразу: person=kp:37859&person=kp:41477 — тайтлы, где есть и ДиКаприо, и Нолан. person.role уточняет роль и без person даёт 400:

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

{
  "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
}

companies ищет по названию компании, company.kind — по её роли: production, studio, network, special_effects, distributor_theatrical, distributor_online, dubbing. Вместе они отвечают на вопрос «где HBO была телеканалом»: companies=HBO&company.kind=network.

Возраст и выход

age_limit — российский возрастной ценз: 0, 6, 12, 16, 18. Список через запятую (age_limit=12,16) или диапазон (age_limit.gte=16). age_limit_max=12 — то же, что age_limit.lte=12. Тайтлы без ценза в выборку не попадают: неизвестный ценз — не ноль.
mpaa — американский сертификат: G, PG, PG-13, R, NC-17 и семейство TV-*. У тайтла один сертификат, поэтому для «любой из» пишите mpaa=R,NC-17.
released=true — вышедшие, released=false — предстоящие. Тайтл считается предстоящим, если дата выхода или год позже сегодняшних.

Готовые наборы: preset

preset — набор фильтров под именем. Явные параметры уточняют его: preset=top&votes_imdb.gte=500000 строже обычного топа. order=asc переворачивает сортировку пресета — preset=top&order=asc начинается с самых низких оценок, — а sort заменяет её целиком.

пресет	что внутри
`top`	`sort=-rating_imdb`, `votes_imdb.gte=100000`, есть оценка Кинопоиска и постер
`hidden_gems`	всё, кроме короткого метра и ТВ-шоу: 1 000–50 000 голосов на Кинопоиске и 1 000–25 000 на IMDb, без концертов, стендапов, спектаклей, музыки и документального кино, `sort=-rating_weighted`
`trending`	вышедшие, `sort=-popularity`
`new`	вышли за последние 30 дней, `sort=-release_date`
`classics`	до 1980 года, от 50 000 голосов на IMDb, `sort=-rating_imdb`

curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "preset=top" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,rating_imdb" \
  "https://api.kinodata.space/v1.3/titles"

Ответ200

{
  "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
    },
    {
      "imdb_id": "tt0795176",
      "kp_id": "279548",
      "tmdb_id": null,
      "tmdb_tv_id": "1044",
      "kinorium_id": "379535",
      "title_ru": "Планета Земля",
      "title_en": "Planet Earth",
      "rating_imdb": 9.4
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}

Подборки и франшизы

collection — тайтлы нашей подборки по её slug: collection=popular-titles. Список подборок — GET /collections. Несуществующая подборка — ошибка 400 со списком существующих.
franchise — тайтлы франшизы по части её названия в TMDB: franchise=matrix.

Полнота данных

required оставляет тайтлы, у которых заполнены перечисленные поля: required=poster,rating_imdb или required=kinorium_id. has_poster=true — то же для одного постера.

В других списках

Те же фильтры и sort работают в подборке, связях, фильмографии, совместных работах и витринах, а фильтры — ещё и в календаре релизов. Например, фильмы Кристофера Нолана от 100 000 голосов — по оценке IMDb:

curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "kind=movie" \
  --data-urlencode "votes_imdb.gte=100000" \
  --data-urlencode "sort=-rating_imdb" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,rating_imdb" \
  "https://api.kinodata.space/v1.3/persons/kp/41477/filmography"

Ответ200

{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0468569",
      "kp_id": "111543",
      "tmdb_id": "155",
      "tmdb_tv_id": null,
      "kinorium_id": "352641",
      "title_ru": "Тёмный рыцарь",
      "title_en": "The Dark Knight",
      "rating_imdb": 9.1
    },
    {
      "imdb_id": "tt1375666",
      "kp_id": "447301",
      "tmdb_id": "27205",
      "tmdb_tv_id": null,
      "kinorium_id": "472809",
      "title_ru": "Начало",
      "title_en": "Inception",
      "rating_imdb": 8.8
    },
    {
      "imdb_id": "tt0816692",
      "kp_id": "258687",
      "tmdb_id": "157336",
      "tmdb_tv_id": null,
      "kinorium_id": "384511",
      "title_ru": "Интерстеллар",
      "title_en": "Interstellar",
      "rating_imdb": 8.7
    }
  ],
  "limit": 3,
  "offset": 0,
  "roles": [
    {
      "role": "director",
      "label_ru": "Режиссёры",
      "label_en": "Directors",
      "count": 19
    },
    {
      "role": "actor",
      "label_ru": "Актёры",
      "label_en": "Actors",
      "count": 2
    },
    {
      "role": "self",
      "label_ru": "В роли себя",
      "label_en": "Self",
      "count": 90
    },
    {
      "role": "archive",
      "label_ru": "Архивные кадры",
      "label_en": "Archive Footage",
      "count": 12
    },
    {
      "role": "writer",
      "label_ru": "Сценаристы",
      "label_en": "Writers",
      "count": 20
    },
    {
      "role": "producer",
      "label_ru": "Продюсеры",
      "label_en": "Producers",
      "count": 22
    },
    {
      "role": "cinematographer",
      "label_ru": "Операторы",
      "label_en": "Cinematographers",
      "count": 5
    },
    {
      "role": "composer",
      "label_ru": "Композиторы",
      "label_en": "Composers",
      "count": 1
    },
    {
      "role": "editor",
      "label_ru": "Монтажёры",
      "label_en": "Editors",
      "count": 5
    },
    {
      "role": "crew",
      "label_ru": "Съёмочная группа",
      "label_en": "Crew",
      "count": 3
    }
  ],
  "total": 18
}

Пресеты тоже работают: preset=top в фильмографии ставит первыми работы с лучшей оценкой IMDb. В фильмографии и совместных работах порядок по умолчанию — от новых работ к старым, order=asc его переворачивает.

Ошибки в запросе

Неизвестный фильтр или оператор — ошибка 400, а не тишина: незаметно отброшенный фильтр выглядел бы как фильтр, под который подошло всё. Где замена очевидна, API подсказывает её в hint. Фильтра status нет — статус выхода спрашивают через released:

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

Ответ400

{
  "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"
  }
}

Параметр с одним значением нельзя повторять: kind=movie&kind=series — тоже 400. Несколько значений пишутся через запятую — kind=movie,series. Исключение — person: его повтор значит «все эти люди».

Дальше

Каталог и поиск — все параметры /titles.
Списки и пагинация — как листать результат.

Фильтры и сортировка

Операторы#

Что можно фильтровать#

Сортировка#

Оценки: ставьте порог голосов#

Окно оценок#

Люди и компании#

Возраст и выход#

Готовые наборы: preset#

Подборки и франшизы#

Полнота данных#

В других списках#

Ошибки в запросе#

Дальше#

Операторы

Что можно фильтровать

Сортировка

Оценки: ставьте порог голосов

Окно оценок

Люди и компании

Возраст и выход

Готовые наборы: preset

Подборки и франшизы

Полнота данных

В других списках

Ошибки в запросе

Дальше