Справочник схем¶
Формы, которые встречаются больше чем в одном ответе. Эндпоинты ссылаются сюда, чтобы не повторять одно и то же описание десять раз.
Пустое скалярное значение всегда null, а не 0 и не "". Массив пустой —
[].
Конверт списка¶
Общая оболочка любого списка.
| поле | тип | описание |
|---|---|---|
items |
массив | сами элементы; при ?group= — секции |
total |
целое | null |
размер выборки до пагинации; null, когда её задал запрос |
limit |
целое | реальный размер страницы после клампа |
offset |
целое | смещение; отсутствует в ответе с курсором |
has_more |
булево | есть ли ещё за этой страницей |
next_cursor |
строка | null |
только в ответе с курсором, вместо offset |
Свои поля ресурса едут рядом с этими: counts у связей и текстов, summary у
состава, roles у фильмографии, collection у подборки, region у календаря,
direction у расхождения.
Секция¶
Элемент items в сгруппированном ответе. Устроена как список, чтобы один
разбор читал оба уровня.
| поле | тип | описание |
|---|---|---|
| (поле группировки) | строка | null |
relation, role, kind, type, class или language — по чему сгруппировано |
label |
строка | null |
подпись значения на языке ?lang= |
total |
целое | настоящий размер секции, даже если элементы обрезаны |
has_more |
булево | обрезана ли секция |
items |
массив | элементы секции |
Карточка тайтла¶
Короткая карточка — то, из чего состоят все списки тайтлов: каталог, чарты,
витрины, подборки, связи, фильмография, known_for.
| поле | тип | описание |
|---|---|---|
imdb_id kp_id tmdb_id tmdb_tv_id |
строка | null |
номера в каталогах; tmdb_id и tmdb_tv_id взаимоисключающие |
kinorium_id |
строка | null |
ещё один номер каталога |
title_ru title_en title_original |
строка | null |
названия как есть |
year |
целое | null |
год |
release_date |
дата | null |
первая дата выхода |
kind |
строка | вид тайтла, набор title_kinds |
poster_kp poster_tmdb poster_imdb |
строка | null |
постеры по источникам |
rating_kp rating_tmdb rating_imdb |
число | null |
оценки, шкала 0–10 |
rating_kr rating_letterboxd |
число | null |
ещё две оценки, шкала 0–10 |
votes_kp votes_tmdb votes_imdb |
целое | null |
голоса |
countries |
массив | {code, name_ru, name_en} |
genres |
массив строк | слаги жанров |
Списки, которые строит движок выборки — /titles, подборка, связи,
фильмография — добавляют к карточке два производных поля:
| поле | тип | описание |
|---|---|---|
title |
строка | null |
название, разрешённое по ?lang= |
poster_url |
строка | null |
постер, выбранный из трёх источников |
И своё, по ресурсу: ord и note в подборке, relation и subtype в связях,
credits в фильмографии, date в календаре, divergence с парой
votes_kp_count / votes_imdb_count в расхождении.
Карточка тайтла целиком¶
Ответ /titles/{type}/{id}. Двадцать два блока
верхнего уровня — они же имена для ?fields=.
| блок | содержимое |
|---|---|
ids |
номера каталогов + urls на страницы источников; приходит всегда |
meta |
hydrated, filled_at, lang ответа |
title |
title_ru, title_en, title_original, производный title |
type |
kind, is_series, status и их подписи |
synopsis |
описания и слоганы по источникам + производные overview, tagline |
release |
year, runtime, releases[] — даты по регионам |
ratings |
sources{} по источникам, votes_total, distribution[], divergence_kp_imdb, popularity |
finance |
budget, revenue, box_office |
awards |
сводка и ceremonies[] — награды по церемониям |
countries |
{code, name_ru, name_en, name} |
classification |
age_limit, mpaa, original_language, is_adult |
series |
seasons_total, episodes_total, start_year, end_year |
media |
постеры, задник, трейлеры, саундтрек |
genres |
{slug, name_ru, name_en, name} |
companies |
{name, kind, slug} |
akas |
альтернативные названия: {title, regions, source} |
tags |
{tag, kind, kind_label} |
watch |
где смотреть: {host, kind, kind_label, section, url} |
parental |
возрастные предупреждения по категориям и их выраженность |
credits_top |
верх состава, готовый к отрисовке |
franchise |
{name, poster_url, size}; только у входящих во франшизу |
counts |
сколько чего на подресурсах |
Оценка источника¶
Элемент ratings.sources.
| поле | тип | описание |
|---|---|---|
value |
число | оценка в своей шкале |
votes |
целое | сколько голосов |
scale |
целое | 10 или 100 |
kind |
строка | critics у критических оценок; у зрительских отсутствует |
url |
строка | страница источника, если она есть |
Кредит¶
Элемент состава в /cast.
| поле | тип | описание |
|---|---|---|
person |
объект | человек в кредите |
role |
строка | роль, набор credit_roles |
character |
объект | null |
персонаж; null у съёмочной группы |
job |
строка | null |
должность внутри роли: Screenplay, Producer |
dubs |
объект | null |
актёр, которого озвучивает этот дубляжный кредит |
ord |
целое | место в титрах |
sources |
массив строк | каталоги, подтвердившие кредит |
В фильмографии кредит устроен проще: без person (человек и так известен) и с
плоским character — строкой на языке ?lang=, рядом с character_ru и
character_en. Кадра персонажа там нет.
Персонаж¶
Поле character в составе тайтла.
| поле | тип | описание |
|---|---|---|
ru en original |
строка | null |
имя персонажа; повторы отбрасываются |
photo_url |
строка | null |
кадр из фильма с этим персонажем |
Человек в кредите¶
| поле | тип | описание |
|---|---|---|
imdb_id kp_id tmdb_id kinorium_id |
строка | null |
номера каталогов |
name_ru name_en name_orig |
строка | null |
имена |
photo_url_kp photo_url_tmdb photo_url_kinorium |
строка | null |
фото по источникам |
gender |
строка | null |
набор genders |
birth_year |
целое | null |
год рождения |
professions |
массив строк | чем занимается, набор credit_roles |
Человек¶
Ответ /persons и поле person в профиле.
Отличается от человека в кредите: здесь один photo_url и есть биография.
| поле | тип | описание |
|---|---|---|
imdb_id kp_id tmdb_id kinorium_id |
строка | null |
номера каталогов |
name_ru name_en name_orig |
строка | null |
имена |
birth_year death_year |
целое | null |
годы жизни |
gender |
строка | null |
набор genders |
birthplace |
строка | null |
место рождения |
photo_url |
строка | null |
фото |
professions |
массив строк | чем занимается |
biography |
строка | null |
биография |
popularity |
число | null |
известность |
also_known_as |
массив строк | другие написания имени |
homepage instagram |
строка | null |
ссылки |
Медиа¶
Элемент /media. Одна форма на изображения и
видео.
| поле | тип | описание |
|---|---|---|
class |
строка | image или video |
type |
строка | вид: наборы image_types и video_kinds |
url |
строка | адрес файла или страницы видео |
language |
строка | null |
язык изображения |
width height |
целое | null |
размеры изображения |
youtube_id |
строка | null |
идентификатор видео |
preview_url |
строка | null |
кадр-превью видео |
runtime_sec |
целое | null |
длительность видео в секундах |
class говорит, как рисовать элемент, но у poster_gif он равен image при
файле video/mp4 — см. примечание к медиа.
Текст¶
Элемент /texts. Общие поля — kind и text;
остальное зависит от вида.
| вид | дополнительные поля |
|---|---|
quote |
original, author, author_role |
fact |
fact_kind (набор fact_kinds), is_spoiler |
faq |
question, answer |
Серия и сезон¶
Элементы /episodes.
| поле серии | тип | описание |
|---|---|---|
season episode |
целое | номера |
name_ru name_en |
строка | null |
названия |
air_date |
дата | null |
дата выхода |
rating_imdb rating_kr |
число | null |
оценки |
votes_imdb |
целое | null |
голоса |
special |
булево | спецвыпуск |
| поле сезона | тип | описание |
|---|---|---|
season |
целое | номер; 0 — спецвыпуски |
episodes |
целое | сколько серий |
first_air last_air |
дата | null |
границы сезона |
rating_imdb votes_imdb |
число | null |
средняя оценка сезона |
specials |
булево | сезон спецвыпусков |
Подборка¶
| поле | тип | описание |
|---|---|---|
slug |
строка | идентификатор в пути |
name |
строка | название |
description |
строка | null |
описание |
poster_url |
строка | null |
обложка |
language |
строка | язык подборки |
items_count |
целое | сколько тайтлов |
created_at updated_at |
время | ISO 8601, UTC |
Ошибка¶
| поле | тип | описание |
|---|---|---|
error.code |
строка | машинный код; список — в Ошибках |
error.message |
строка | человекочитаемое пояснение |
error.field |
строка | параметр, который не подошёл |
error.allowed |
массив | допустимые значения, если набор закрыт |
error.hint |
строка | подсказка — например, «did you mean "tmdb"?» |
Первые два поля есть всегда, остальные три — когда их есть чем заполнить.
Перечисления¶
Восемнадцать закрытых наборов. Значения — те же строки, что принимают фильтры;
подписи отдаёт /enums.
| набор | значения |
|---|---|
title_kinds |
movie, series, mini_series, tv_show, anime, cartoon, short |
credit_roles |
director, actor, writer, producer, cinematographer, composer, sound, art, editor, voice_director, voice, author, translator, producer_ussr, crew |
relation_kinds |
similar, related, referenced_in, reference |
text_kinds |
fact, faq, quote |
fact_kinds |
fact, trivia, blooper |
image_types |
poster, poster_gif, backdrop, still, cover, logo, promo, backstage, other |
video_kinds |
trailer, teaser, tvspot, clip, interview, music_video, behind_scenes, blooper, overview, other |
statuses |
released, ended, returning_series, in_production, post_production, in_development, planned, canceled, rumored, pilot, to_be_determined, will_continue |
company_kinds |
production, studio, network, special_effects, distributor_theatrical, distributor_online, dubbing |
site_kinds |
official, streaming, store, encyclopedia, wiki, rating, web, social, other |
site_sections |
encyclopedia, streaming, soundtrack, official, social, source |
tag_kinds |
subgenre, adjective, keyword |
parental_categories |
sex_nudity, violence, profanity, substances, frightening |
parental_severities |
mild, moderate, severe |
mpaa_ratings |
G, PG, PG-13, R, NC-17, NR, TV-Y, TV-Y7, TV-G, TV-PG, TV-14, TV-MA |
genders |
male, female |
sources |
imdb, kp, tmdb, kinorium |
faq_link_types |
person |
Подтипы связей в ?subtype= — sequel, prequel, spinoff, parent,
chronology, remake, original, version — живут при самих связях и в
/enums не публикуются.