Media Guide

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

Оглавление

Цель и смысл

Данный документ описывает программный интерфейс (API) сервиса Media Guide, ранее известный как TV Guide («программа телепередач»).

С помощью данного API можно выяснить:

На замену настоящему API для получения информации о каналах, передачах и выпусках готовится Media Catalogue API.

Получение ссылок на адреса вещания осуществляется:

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

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

Размещение и использование

Точка входа определяется Регистратурой, при этом числовой идентификатор сервиса — 4, строковый — tv_guide.

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

http://<path_to_api>/<method>.<format>?[parameters]

Где:

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

Возрастные ограничения

В версии 2.1 введено понятие возрастного ограничения (возраст в годах, с которого можно потреблять медиа–контент без вреда для психики человека) для:

Возрастные ограничения могут быть выставлены вручную или автоматически, на основании возрастных ограничений элементов, из которых состоит сущность. При автоматическом вычислении возрастного ограничения результат является максимумом возрастных ограничений элементов. Таким образом, для канала, возрастные ограничения передач которого колеблются от 0 до 18 лет, возрастным ограничением будет 18 лет.

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

параметр смысл возможные значения значение по умолчанию
t идентификатор территории[1] число автоматически определенная
c идентификатор контрагента[1] число автоматически определенный

Замечания:

  1. Рекомендуется явно указывать территорию, для которой запрашивается программа передач.

Локализация

Каждый запрос к API позволяет получить описание контента на предпочитаемом пользователем языке. Для указания предпочитаемых языков необходимо в запросе использовать заголовок Accept-Language.

Методы Media Guide API

idbytitle — получение списка идентификаторов каналов по их именам

Запрос идентификаторов каналов, для которых в списке каналов провайдера (службы IPTV, Радио) не указан числовой идентификатор канала.

ВАЖНО: названия каналов передаются в кодировке текста UTF–8

Обращение при помощи GET–запроса (устарело с версии 2.11)

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

параметр значение
titles Список названий каналов из списка каналов (службы IPTV или Радио), для которых запрашиваются идентификаторы

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

  1. Все запятые (,) в названии каналов экранируются символом \
  2. Преобразованные названия склеиваются с помощью запятой (,)

Обращение при помощи POST–запроса

Список названий каналов, для которых запрашиваются идентификаторы, передается сообщением TitlesRequest в теле запроса методом POST в формате запроса.

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

Замечания:

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

Пример взаимодействия

GET–запрос:

GET /tvguide/2/idbytitle.json?titles=Первый+канал,Шестьсот+шестьдесят+шестой+канал,Второй+канал

Ответ:

{
  "channels": [
    {
      "title": "Первый",
      "channelId": 1237961
    },
    {
    },
    {
      "title": "Россия 2",
      "channelId": 2204872
    }
  }
}

POST–запрос:

POST /tvguide/2/idbytitle.json

{"titles":["Первый","РБК","НТВ Беларусь","78 канал"]}

Ответ:

{
  "channels": [
    {
      "channelId":10338245,
      "title":"Первый"
    },{
      "channelId":10338214,
      "title":"РБК"
    },{
      "channelId":50036870,
      "title":"НТВ-Беларусь"
    },{
    }
  ]
}

channels — получение информации о каналах

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

параметр значение
channel список числовых идентификаторов каналов через ,
fields список полей через , из сообщения Channel (допускается указывать любое поле)

В независимости от переданного значения в параметре fields в выдаче для каждого сообщения Channel должно присутствовать поле channelId. Если параметр fields задан, то неуказанные в параметре поля (за исключением channelId) не должны попадать в выдачу.

Если параметр fields не задан, то по умолчанию в выдачу должны быть включены поля title, alias, logoURL, ageRestriction, hasSchedule, что гарантирует наличие в выдаче:

Если параметр channel не задан, то должна быть возвращена информация по всем каналам.

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

schedule — получение расписания для канала

параметр по умолчанию значение
channel отсутствует идентификатор канала
dates текущий день даты, по которой выдать расписание (в формате YYYY-MM-DD, через запятую)

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

Вне зависимости от порядка запрошенных дат расписание вернется в хронологическом порядке без повторов.

telecastInfo — получение информации о выпуске передачи по его идентификатору

параметр значение
telecast список идентификаторов выпусков передач через запятую

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

tvshows — получение информации о передачах

параметр значение
tvshow список идентификаторов передач через запятую

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

Устаревшие методы

channel — получение информации о канале по его идентификатору (устарел с версии 2.7)

параметр значение
channel идентификатор канала

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

Описания форматов способом Google Protocol Buffers

DateTime — Описание даты и времени

message DateTime {
  optional uint32 year = 1;
  optional uint32 month = 2;
  optional uint32 day = 3;

  optional uint32 hour = 4;
  optional uint32 minute = 5;
  optional uint32 second = 6;

  optional int32 timezone = 7;
}

Замечания:

TVShow — Передача

message TVShow {
  optional uint32 id = 1;
  optional string title = 2;
  optional string description = 3;
  repeated Channel channels = 4;
  optional uint32 ageRestriction = 5;
  optional string URL = 6;
  repeated TelecastImage telecastImages = 7;
}

message TVShowList {
  repeated TVShow tvShows = 1;
}

Замечания:

TelecastImage — снимки выпуска передачи

  message TelecastImage {
    enum Profile {
      IMAGE = 0;
      PREVIEW = 1;
      MAIN = 2;
      IMAGE2 = 3;
    }
    optional Profile profile = 1;
    optional uint32 width = 2;
    optional uint32 height = 3;
    optional string location = 4;
  }

Telecast — Описание фрагмента

message Telecast {
  optional uint64 id = 1;
  optional string title = 2;
  optional string description = 3;
  optional DateTime date = 4;
  optional uint32 duration = 5;
  optional string URL = 6;
  repeated TelecastImage telecastImages = 7;

  optional TVShow tvShow = 10;
  optional Channel channel = 11;
  optional uint32 ageRestriction = 12;
  optional uint64 views_count = 13;
  optional int32 time_offset = 14 [default = 0];
  optional uint64 parent_id = 15;

  repeated Category categories = 16;
  repeated uint64 ad_tags = 17;
  optional string alias = 18;
}

Замечания:

Category — Категория аудиовизуального материала

enum CategoryType {
  option (allow_alias) = true;

  PORNOGRAPHIC = 1;
  DOCUMENTAL = 2;
  HUMOROUS = 3;
  MUSIC = 4;
  INFORMATIONAL = 5;
  ENTERTAINMENT = 6;
  FOR_KIDS = 7;
  SPORT = 8;
  FASHION = 9;
}

message Category {
  optional CategoryType type = 1;
  optional string title = 2;
}

Замечания:

Channel — Описание канала

message Channel {
  enum ChannelType {
    TV = 0;
    RADIO = 1;
  }

  optional uint32 channelId = 1;
  optional string title = 2;
  optional string description = 3;
  optional string logoURL = 5;
  optional string promoURL = 6;

  repeated DateTime scheduledDates = 8;
  optional Telecast currentTelecast = 9;

  optional string alias = 10;
  optional uint32 ageRestriction = 12;
  optional bool hasSchedule = 13;

  optional ChannelType type = 15 [default = TV];
  optional string artworkURL = 16;

  repeated Category categories = 17;
  repeated Rubric rubrics = 18;
}

Замечания:

Rubric - Рубрика канала

message Rubric {
  optional int64 id;
  optional string title;
}

Замечание:

Schedule — Расписание для канала

message Schedule {
  optional string channelId = 1 [deprecated = true];

  repeated Telecast telecastsList = 2;
  optional int64 items_skipped = 3;
  optional int64 total_count = 4;
}

Замечание:

ChannelsList — Список каналов

message ChannelsList {
  optional string title = 1;

  repeated Channel channels = 2;  
}

TitlesRequest — список названий каналов

message TitlesRequest {
  repeated string titles = 1;
}

Замечания:

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

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

  1. Изменения в общих параметрах:
  2. В XSPF оставлен только один метод — list.xspf, для клиентов, не поддерживающих API. Все остальное переведено на JSON, XML и Protocol Buffers.
  3. Убран метод договора оферты.
  4. Убран метод получения дат с наличествующем расписанием для канала.
  5. Добавлен метод получения описания о конкретном канале.
  6. Добавлен метод получения информации о канале по идентификатору выпуска телепередачи.
  7. Добавлена возможность получения расписания передач канала для нескольких дат.

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

  1. Добавлен признак доступности эфира и записей телепередач канала.
  2. Метод /list помечен как «устаревший».
  3. Добавлена сущность «Телепередача».
  4. В информацию о выпуске телепередачи добавлен канал, на котором был выпуск.
  5. Добавлены параметры «Возрастные ограничения» для канала, передачи и выпуска телепередачи.
  6. Добавлен параметр наличия расписания в сообщении Channel.

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

  1. Указан ориентир на Catalogue API
  2. Добавлен метод получения предполагаемых идентификаторов каналов по их написанию idbytitle

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

  1. Добавлен метод получения топ передач за указанный период времени (Closes: #WEBDEV–6465)
  2. В сообщение Schedule добавлены поля items_skipped и total_count, отвечающие за частичную выдачу информации
  3. В сообщение Telecast добавлено поле views_count, отвечающее за количество просмотров выпуска телепередачи пользователями сервиса

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

  1. Уточнено использование API в рамках веб–служб TV Guide и Peers.TV
  2. Поле access для канала помечено устаревшим

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

  1. Добавлен атрибут storage_hours для канала, отражающий время хранения записей выпусков телепередач на серверах сервиса Peers.TV

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

  1. Обновлена дата планового срока внедрения Catalogue API;
  2. Добавлено описание подборок сервиса Peers.TV;
  3. Добавлены методы для получения списка тематических подборок выпусков телепередач — getcollections, списка выпусков телепередач по тематике — collection.

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

  1. Обновлена поддерживаемая на сервере версия.
  2. Добавлено пояснение к методу getcollections

Изменения в версии 2.5.2 (TVREC–172)

  1. Описана возможность передавать список идентификаторов выпусков телепередач в метод telecastInfo.

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

  1. Описано правило формирования признака наличия записей для канала.

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

  1. Добавлен атрибут для выпуска телепередачи time_offset, описывающий разницу между датой фактического выхода и датой выхода по расписанию.

Изменения в версии 2.7 (TVREC–136)

  1. Добавлена фильтрация в метод channels по списку идентификаторов каналов при помощи параметра channel_ids;
  2. Добавлен параметр fields в метод channels для осуществления частичной выдачи.

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

  1. Параметр channel_ids метода channels переименован в channel по аналогии с остальными методами.

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

  1. Добавлен атрибут типа канала type в сообщение Channel;
  2. Добавлен атрибут афиши канала artworkURL в сообщение Channel;
  3. Унифицирован термин канал, добавлены производные термины — телеканал, радиоканал.

Изменение в версии 2.8.1 (TVREC–274)

  1. Добавлен атрибут parent_id для ссылки на выпуск передачи.

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

  1. Добавлены категории, характеризующие передачи и каналы.

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

  1. Исправлено описание метода channels, внесены дополнительные пояснения.

Изменения в версии 2.9.2 (WEBDEV–7958)

  1. Уточнено значение атрибута views_count сообщения Telecast.

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

  1. Удалено описание метода list.xspf, так как он доступен только в рамках PeersTV API;
  2. Удалены прогнозы из документации.

Изменения в версии 2.10.0 (TVREC–425)

  1. Добавлена локализация.

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

  1. Описано требование по кодированию значений параметров при обращении к методам API.

Изменения в версии 2.11 (TVREC–379)

  1. Описано использование HTTP метода POST для выполнения запроса к методу API idbytitle.

Изменения в версии 2.11.1 (TVREC–176)

  1. Внесены уточнения об использовании территории для получения программы передач.

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

  1. Удалено описание общих для всех методов параметров device, device-version, которые более не используются
  2. Описаны значения по умолчанию для метода schedule
  3. Удалено упоминание PeersTV API вследствие прекращения поддержки
  4. Общий параметр t обозначен как рекомендуемый к указанию при обращениях к методами API

Изменения в версии 2.11.3 (WEBDEV–10732)

  1. Добавлен новый профиль иллюстраций IMAGE2 в сообщение TelecastImage;

Изменения в версии 2.12.0 (TVREC–1074)

  1. Добавлен способ передачи рекламных тэгов для ограничения использованиия рекламых сетей на контенте.

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

  1. Исправлен тип данных для аттрибута ad_tags из сообщения Telecast

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

  1. Добавлены рубрики каналов в сообщение Channel

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

  1. Для получения информации о передачах добавлен метод tvshows

  1. из Registry API  ↩