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

GET/v1.3/titles

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

Главный список API: поиск, витрины и выборки по любым признакам. Фильтры, сортировка и пресеты подробно разобраны в Фильтры и сортировка, пагинация и fields — в Списки и пагинация.

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

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

qstring
Поиск по названию на любом языке. Прощает опечатки: «матрца» и «matrx» найдут «Матрицу». С q сортировка по умолчанию — по релевантности.
Пример: q=матрица
фильтры
Любой фильтр каталога с операторами .any, .all, .not, .gte, .lte: kind=anime, country=jp, year.gte=1990, votes_imdb.gte=50000, person=kp:41477. Полный список — в Фильтры и сортировка.
sortstring
Порядок: ключ со знаком, - — по убыванию, + — по возрастанию. Можно два ключа через запятую: sort=-rating_imdb,+year. По умолчанию — по популярности, а с q — по релевантности.
popularityrelevancerelease_dateyearruntimeratingrating_imdbrating_kprating_tmdbrating_krrating_letterboxdrating_rtrating_metacriticrating_criticsvotes_imdbvotes_kpvotes_tmdbvotes_krvotes_letterboxdvotes_totalrating_weighteddivergencebudgetbox_office_usrevenue_worldwins_imdboscars_wonrandom
По умолчанию:
popularity, с q — relevance
Пример: sort=-rating_imdb
presetenum
Готовый набор фильтров. Явные параметры его уточняют. Что внутри каждого — в Фильтры и сортировка.
tophidden_gemstrendingnewclassics
Пример: preset=top
limitinteger
Сколько тайтлов на странице, от 1 до 50.
По умолчанию:
50
Пример: limit=20
offsetinteger
Сколько тайтлов пропустить от начала.
По умолчанию:
0
cursorstring
Курсор для глубокой прокрутки. Первый запрос — с пустым cursor=, дальше — значение next_cursor из ответа. Не работает с sort=random. Есть только у каталога.
fieldscsv
Какие поля элемента вернуть: fields=title,year. Со знаком - — какие убрать: fields=-genres. title оставляет title_ru и title_en, poster_url — poster_url_ru и poster_url_en. ID приходят всегда.
titletitle_originalyearrelease_datekindposter_urlposters_by_sourcerating_kprating_tmdbrating_imdbrating_krrating_letterboxdvotes_kpvotes_tmdbvotes_imdbcountriesgenres
Пример: fields=title,year
langru | en
Оставить в ответе один язык.

Поля ответа

itemsarray
Тайтлы.
Показать 24 поля
- imdb_id · kp_id · tmdb_id · tmdb_tv_id · kinorium_idstring | null
  ID тайтла в каталогах. Приходят всегда, даже с fields.
- title_ru · title_en · title_originalstring | null
  Названия: на русском, на английском и на языке оригинала.
- yearinteger | null
  Год выхода.
- release_datestring | null
  Первая дата выхода, YYYY-MM-DD.
- kindenum
  Вид тайтла: movie, series, mini_series, tv_show, anime, cartoon, short.
- poster_url_ru · poster_url_enstring | null
  Постер для русской и английской витрины.
- posters_by_sourceobject
  Постер каждого источника: kp, tmdb, imdb, kinorium.
- rating_kp · rating_tmdb · rating_imdb · rating_kr · rating_letterboxdnumber | null
  Оценки Кинопоиска, TMDB, IMDb, Кинориума и Letterboxd, шкала 0–10.
- votes_kp · votes_tmdb · votes_imdbinteger | null
  Голоса Кинопоиска, TMDB и IMDb.
- countriesarray
  Страны: code, name_ru, name_en.
- genresarray
  Жанры: slug, name_ru, name_en.
totalnull
Каталог не считает общее число тайтлов: точный подсчёт по фильтру — второй проход по всей базе. Листайте по has_more.
limit · offsetinteger
Размер страницы и смещение. offset нет, когда вы листаете курсором.
has_moreboolean
Есть ли следующая страница.
next_cursorstring | 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	Исчерпан предел в секунду или квота на сутки.

Все коды и что с ними делать — на странице Ошибки.

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

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

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

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

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
}

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
}

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

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

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

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

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