Films API

Статус документа

Оглавление

Общее описание

Films API предназначено для взаимодействия с каталогом фильмов. API предоставляет возможность осуществлять поиск по каталогу, получать информацию о фильмах, существующих тегах, например: актеры, режиссеры, жанры и т.д.

Термины и определения

В этом документе используются термины и определения, описанные в документах «О программных интерфейсах сервисов Инетры» и «Термины и определения».

Взаимодействие с API

Точка входа определяется Регистратурой.

Запросы формируются следующим образом:

http://<path_to_api>/<запрос>/?[параметры]

Где:

• path_to_api — путь до API, полученный из Регистратуры

Значения всех параметров необходимо кодировать для предотвращения неоднозначной интерпретации так, как это рекомендуется в RFC3986.

Все ответы отправляются в XML, все строчки указываются без HTML–форматирования.

Общие параметры

Общие параметры, доступные для каждого запроса:

В зависимости от оборудования, от которого поступил запрос, требуется возвращать различные списки фильмов. Так, к примеру, в версии R8 приставки stb820, невозможен просмотр фильмов размером более 2 гигабайт.

Задание списка тагов

Афиши на CN.ru может иметь несколько тагов (атрибутов). Следующие вещи являются тагами:

• Жанры
• Страны
• Актеры
• Режиссеры
• Возрастные ограничения

У тага есть имя и идентификатор.

Можно указывать не один, а несколько тагов для выбора контента, указывая названия тагов через запятую. Выборка в таком случае будет производиться по тому контенту, у которого есть все перечисленные таги.

Начиная с версии 2.5 API можно указывать следующие параметры:

Например, чтобы получить список отечественных фильмов (не мультипликационных) возрастной категории 0+ надо передать фильтр: tag=for_all_age&tag_any=sssr,russia&tag_exclude=cartoon

Задание сортировки

Сортировка возможна по следующим критериям:

Для указания сортировки необходимо передать идентификаторы сортировки, перечислив их через запятую (порядок важен), указав суффикс:

• -a — сортировка в возрастающем порядке
• -d — сортировка в убывающем порядке

С помощью API нельзя задать одновременно более трех параметров сортировки.

Например, чтобы отсортировать список фильмов сначала по году выхода в возрастающем порядке, а внутри одного года выхода — по популярности в убывающем порядке, необходимо передать параметр sort=year-a,popularity-d

Фильтрация по времени публикации:

У редактора есть возможность запланировать публикацию афиши на определённое время. Время публикации конкретной серии внутри афиши задаётся автоматически и совпадает со временем её добавления. По умолчанию API выдаёт только те афиши и серии, время публикации которых уже наступило.

Для получения ещё не опубликованных афиш/серий используется параметр published_before. При его указании выдаются сущности, время публикации которых не позже заданного. Фильтрация применяется ко всем выборкам афиш/серий, которые делает данный метод API. Время задаётся целым числом в виде unix time.

Методы

tags — Получение списка тагов

Запрос: /tags/

Дополнительные параметры: отсутствуют.

Формат ответа: сообщение TagsListItems.

list — Получение списка фильмов

Запрос: /list/

Дополнительные параметры:

Формат ответа: сообщение FilmsList.

Замечания:

• Если ни одной афиши не найдено — должен вернуться пустой список
• Параметр exclude_film[] может быть передан несколько раз
• Если в параметре tag перечислены таги из списка tag_exclude, наличие их в последнем списке аннулируется.
• К параметру tag_exclude могут добавляться значения:
  • при выборке с поиском по названию (указан параметр q) — trailer
  • при выборке по списку идентификаторов (указан параметр ids) — не добавляются
  • во всех остальных случаях — trailer,anime
• Параметры begin и end отвечают за границы времени обновления выдаваемых афиш. Формат параметров может совпадать с форматом интерпретации дат в PHP.
• Если не задан часовой пояс, подразумевается стандартное время по Новосибирску.
• Если параметр end совпадает c текущей датой, он автоматически выставляется на следующую дату. Таким образом, указав в параметрах begin и end одну и ту же дату, можно получить список афиш, обновленных за эту дату.
• Если не задано время, оно становится равным 0 часов, 0 минут и 0 секунд по Новосибирску.
• Если в запросе указан параметр ids, осуществляется выборка списка афиш с заданными идентификаторами. Идентификаторы передаются строкой, разделителем выступает символ ,. Сервер возвращает только афиши, чьи идентификаторы были найдены на сервере, а также подпавшие под действия фильтров, заданных остальными параметрами запроса, и ничего более. Если в качестве значения параметра ids указана пустая строка, должен вернуться пустой список.
• Если в запросе заданы параметры from_year, to_year, осуществляется выборка афиш по заданному диапазону годов выпусков фильмов, включая границы годов. Любой из параметров from_year, to_year взаимно исключает использование параметра year.
• Если в запросе задан параметр age_filter, осуществляется выборка афиш с учетом возрастного ценза.
• Параметры ids и q взаимно исключают друг друга.
• Параметр published_before используется для фильтрации по времени публикации.

similar — Получение списка похожих фильмов

Запрос: /list/similar/

Дополнительные параметры:

Формат ответа: сообщение FilmsList.

Замечания:

• Параметры ids представлен строкой из id искомых фильмов, соединенных знаком ,.

recommended — Получение списка «рекомендованных» фильмов

Запрос: /list/recommended/

Дополнительные параметры:

Формат ответа: сообщение FilmsList.

Замечания:

• Метод полностью аналогичен методу similar, под капотом он обращается к userData, получает список последних просмотренных фильмов и ищет похожие.

search — Поиск фильмов по ключевому слову (Устарело с версии 2.7)

Запрос: /search/

Дополнительные параметры:

Формат ответа: сообщение FilmsList.

Замечания:

• Поисковая строка должна быть передана в кодировке UTF–8 и закодирована в процентной кодировке
• Отсутствие указания сортировки выдачи означает сортировку по релевантности результатов поиска.

film — Получение серий фильма

Запрос: /film/<id>/

где:

• <id> — идентификатор фильма.

Дополнительные параметры:

Формат ответа: сообщение FilmInfo.

При указании параметра запроса age_filter производится фильтрация афиш в связанных подборках по возрастному цензу (подборки «Похожее», «Смотри также»). Параметр published_before используется для фильтрации по времени публикации.

upnext — Получение списка фильмов для непрерывного воспроизведения

Запрос: /upnext/<id>/<series_id>

где:

• <id> — идентификатор фильма.
• <series_id> — идентификатор серии сериала. Обязателен для сериалов

Дополнительные параметры:

Формат ответа: сообщение UpnextList.

getfilmsfile — Получение списка фильмов для приложения PeerSay

Запрос: /getfilmsfile/

Формат ответа: CSV.

Файл содержит поля: идентификатор фильма, название, год выхода. В качестве разделителя полей используется точка с запятой «;». Текcтовые поля экранируются двойными кавычками.

При выполнении запроса сервер перенаправит клиента на ответ, заранее сформированный с учетом правил доступа к афишам.

Форматы сообщений

Tag — информация о таге

message Tag {
  optional uint32 Id = 1;
  optional string Name = 2;
  optional string Title = 3;
  optional string URL = 4;
}

message TagsListItems {
  repeated Tag Items = 1;
}

Замечания:

• Id — численный идентификатор тага
• Name — строковый идентификатор тага
• Title — название тага
• URL — адрес API, по которому можно получить список афиш с данным тагом

Serie — информация о серии

message Serie {
  optional string Title = 1;
  optional string Magnet = 2;
  optional string URL = 3;
  optional uint32 Size = 4;
  optional uint32 Length = 5;
  optional string Published = 6;
  optional uint32 Quality = 7;
  optional uint32 Number = 8;
  enum PictureQualityEnum {
    SD = 0 [(CN.string_value) = "SD"];
    HD = 1 [(CN.string_value) = "HD"];
    3D = 2 [(CN.string_value) = "3D"];
  }
  optional PictureQualityEnum PictureQuality = 9;
  repeated string Images = 10 [(CN.child_names) = "Image"];
}

Замечания:

• Title — название серии
• Magnet — ссылка на файл в файлообменной сети
• URL — HTTP–ссылка на файл
• Size — размер файла в байтах
• Length — продолжительность серии в секундах.
• Published — время публикации в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС
• Quality — субъективное качество серии. Оценивается комплексно по ряду параметров (качество звука, озвучки, картинки)
• Number — порядковый номер серии в сезоне
• PictureQuality — качество изображения в серии
• Images — скриншоты к серии.

FilmsList — список фильмов

message FilmInfo {
  optional string URL = 1;
  optional string Title = 2;
  optional string Desc = 3;
  optional string Updated = 4;
  optional uint32 Year = 5;
  optional string Preview = 6;
  optional string Poster = 7;
  optional string User = 8;

  repeated Tag Tags = 9 [(CN.child_names) = "Tag"];
  repeated Tag Quality = 10 [(CN.child_names) = "Tag"];
  repeated Tag Directors = 11 [(CN.child_names) = "Director"];
  repeated Tag Actors = 12 [(CN.child_names) = "Actor"];
  repeated Tag Countries = 13 [(CN.child_names) = "Country"];

  message Rating {
    enum RatingType {
      CN = 0 [(CN.string_value) = "cn"];
      KINOPOISK = 1 [(CN.string_value) = "kinopoisk"];
      IMDB = 2 [(CN.string_value) = "imdb"];
    }
    optional RatingType Type = 1;
    optional string Title = 2;
    optional uint32 Count = 3;
    optional float Max = 4;
    optional float Rank = 5;
  }
  repeated Rating Ratings = 14;
  repeated FilmInfo RelatedFilms = 15 [(CN.child_names) = "RelatedFilm"];
  repeated FilmInfo SeeAlso = 16 [(CN.child_names) = "Item"];

  repeated Serie Items = 17 [(CN.child_names) = "Item"];
  repeated Serie Trailers = 18 [(CN.child_names) = "Trailer"];

  repeated string Images = 19 [(CN.child_names) = "Image"];
  optional uint64 Id = 20;
}

Замечания:

• Id — идентификатор фильма
• URL — адрес, по которому можно получить полную информацию о афише фильма
• Title — название фильма
• Desc — описание фильма
• Updated — время последнего обновления афиши
• Year — год выхода фильма
• Preview — URL до маленькой картинки о фильме (используется в списках)
• Poster — URL до постера фильма (используется на странице фильма)
• User — владелец афиши. В случае афиши от редакции значение не заполняется
• Tags — таги: жанры
• Quality — таги: качество
• Directors — таги: режиссеры
• Actors — таги: актеры
• Countries — таги: страны
• Ratings — рейтинги афиши:
  • Rating.Type — источник рейтинга
  • Rating.Title — имя источника рейтинга
  • Rating.Count — количество проголосовавших
  • Rating.Max — максимальная оценка
  • Rating.Rank — непосредственно оценка
• RelatedFilms — информация о других сезонах данного сериала
• SeeAlso — информация о похожих афишах
• Items — список серий
• Trailers — список трейлеров
• Images — скриншоты к фильму

UpnextList — список фильмов для непрерывного воспроизведения

message UpnextFilm {
  optional uint64 Id = 1;
  optional string Title = 2;
  optional string Desc = 3;
  optional string Updated = 4;
  optional uint32 Year = 5;
  optional string Preview = 6;
  optional string Poster = 7;

  message Item {
    optional string Title = 1;
    optional string Magnet = 2;
    optional uint64 Size = 3;
    optional uint32 Length = 4;
    optional string Published = 5;
    optional uint8 Quality = 6;
    optional uint32 Number = 7;
    optional string PictureQuality = 8;
  }
  repeated Items Item = 8;

  repeated string Images = 9 [(CN.child_names) = "Image"];
}

Замечания:

• Id — идентификатор фильма
• Title — название фильма
• Desc — описание фильма
• Updated — время последнего обновления афиши
• Year — год выхода фильма
• Preview — URL до маленькой картинки о фильме (используется в списках)
• Poster — URL до постера фильма (используется на странице фильма)
• Items — информация о сериях:
  • Item.Title — название серии
  • Item.Magnet — ссылка на файл серии
  • Item.Size — размер серии
  • Item.Length — длительность серии
  • Item.Published — дата публикации серии
  • Item.Quality — качество записи серии
  • Item.Number — номер серии
  • Item.PictureQuality — качество картинки серии
• Images — скриншоты к фильму

FilmsList, FilmAlone — список фильмов

message FilmsList {
  option (CN.root_name) = "Films";
  optional uint32 Page = 1;
  optional uint32 PagesCount = 2;
  repeated FilmInfo Items = 3 [(CN.child_names) = "Item"];
  repeated FilmInfo Suggests = 4 [(CN.child_name) = "Item"];
}

message FilmAlone {
  Iroot_name) = "Films";
  optional FilmInfo Film = 3;
}

Замечания:

• FilmsList.Page — текущая страница
• FilmsList.PagesCount — количество страниц в выборке
• FilmsList.Items — результаты выборки
• FilmsList.Suggests — возможные альтернативы (указываются только для поиска)

История версий

Изменения в версии 2.1

• Добавлена поддержка запроса фильмов, находящихся одновременно в нескольких тагах

Изменения в версии 2.2

• Добавлены порядковые номера серий.
• Добавлена поддержка указания качества изображения в серии.

Изменения в версии 2.3

• Добавлен поиск по тагированному контенту.
• Добавлена сортировка при выдаче списка фильмов.

Изменения в версии 2.4

• Добавлены сортировки по рейтингам (CN.ru, Кинопоиск, IMDB).
• Добавлена поддержка скриншотов для серий сериалов.

Изменения в версии 2.5

• Добавлена поддержка дополнительных списков тагов.

Изменения в версии 2.5.1

• Добавлена вводная часть документа;

Изменения в версии 2.6 (TVREC–307)

• В метод list добавлен фильтр по идентификаторам афиш.

Изменения в версии 2.6.1

• Обновлен markdown-синтаксис документа;
• Описано получение пути к API через сервис «Регистратура»;
• Общий параметр api-version помечен как устаревший;
• Описан атрибут Id из сообщения FilmInfo.

Изменения в версии 2.7 (TVREC–719, TVREC–718)

• Описаны параметры from_year, to_year для фильтрации списка фильмов по годам для метода list;
• Описан параметр age_filter для фильтрации списка афиш с учетом возрастного ценза.

Изменения в версии 2.7.1

• Метод search помечен как устаревший;
• Добавлен параметр q в метод list, позволяющий осуществлять выборку по поисковой фразе с учетом дополнительных фильтров метода.

Изменения в версии 2.8 (TVREC–763)

• Добавлен параметр age_filter в методе film для фильтрации связанных подборок по возрастному цензу.

Изменения в версии 2.8.1

• Внесено уточнение о значении параметра tag_exclude при выборке элементов по названию при помощи метода list.

Изменения в версии 2.9.0 (TVREC–876)

• Исключена фильтрация по умолчанию параметром tag_exclude в методе list при выборке афиш по списку идентификаторов.

Изменения в версии 2.9.1 (WEBDEV–10087)

• Добавлен метод getfilmsfile.

Изменения в версии 2.10 (WEBDEV–11173)

• Описана фильтрация по времени публикации в методах list и film.

Изменения в версии 2.11

• Добавлены методы similar и recommended.
• Добавлена сортировка в случайном порядке в методе list.

Изменения в версии 2.12

• Добавлен метод upnext.