Данный документ описывает программный интерфейс (API) сервиса Media Guide, ранее известный как TV Guide («программа телепередач»).
С помощью данного API можно выяснить:
На замену настоящему API для получения информации о каналах, передачах и выпусках готовится Media Catalogue API.
Получение ссылок на адреса вещания осуществляется:
В этом документе используются термины и определения, описанные в документах «О программных интерфейсах сервисов Инетры» и «Термины и определения».
Точка входа определяется Регистратурой, при этом числовой идентификатор сервиса — 4
, строковый — tv_guide
.
Запросы формируются следующим образом:
http://<path_to_api>/<method>.<format>?[parameters]
Где:
path_to_api
— путь до API, полученный из Регистратурыmethod
— имя методаformat
— формат передачи данных, может быть одним из:
json
— JSONxml
— XMLparameters
— параметры методаЗначения всех параметров необходимо кодировать для предотвращения неоднозначной интерпретации так, как это рекомендуется в RFC3986.
В версии 2.1 введено понятие возрастного ограничения (возраст в годах, с которого можно потреблять медиа–контент без вреда для психики человека) для:
Возрастные ограничения могут быть выставлены вручную или автоматически, на основании возрастных ограничений элементов, из которых состоит сущность. При автоматическом вычислении возрастного ограничения результат является максимумом возрастных ограничений элементов. Таким образом, для канала, возрастные ограничения передач которого колеблются от 0 до 18 лет, возрастным ограничением будет 18 лет.
параметр | смысл | возможные значения | значение по умолчанию |
---|---|---|---|
t |
идентификатор территории[1] | число | автоматически определенная |
c |
идентификатор контрагента[1] | число | автоматически определенный |
Замечания:
Каждый запрос к API позволяет получить описание контента на предпочитаемом пользователем языке. Для указания предпочитаемых языков необходимо в запросе использовать заголовок Accept-Language
.
idbytitle
— получение списка идентификаторов каналов по их именамЗапрос идентификаторов каналов, для которых в списке каналов провайдера (службы IPTV, Радио) не указан числовой идентификатор канала.
ВАЖНО: названия каналов передаются в кодировке текста UTF–8
Параметры запроса:
параметр | значение |
---|---|
titles |
Список названий каналов из списка каналов (службы IPTV или Радио), для которых запрашиваются идентификаторы |
Список названий каналов кодируются следующим образом:
,
) в названии каналов экранируются символом \
,
)Список названий каналов, для которых запрашиваются идентификаторы, передается сообщением TitlesRequest
в теле запроса методом POST в формате запроса.
Формат ответа: сообщение ChannelsList
.
Замечания:
Channel
Channel
должны заполняться поля:
title
— локализованное название найденного каналаchannelId
— идентификатор найденного каналае
и ё
при необходимостиЗамечание к серверной реализации: в случае если для переданного названия было найдено две и более сущности, то данный факт необходимо зафиксировать в журнале событий как ошибку.
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
.
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;
}
Замечания:
timezone
задается в секундах относительно GMT.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;
}
Замечания:
id
— идентификатор передачиtitle
— локализованное название передачиdescription
— локализованное описание передачиchannels
— список каналов, на которых выходят выпуски передачиageRestriction
— возрастное ограничение передачиURL
— адрес страницы передачи на сайте сервиса 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;
}
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;
}
Замечания:
id
— идентификатор выпуска передачиtitle
— локализованное название выпускаdescription
— локализованное описание выпускаdate
— время выхода выпуска по расписаниюduration
— продолжительность (в секундах)URL
— адрес выпуска передачи на сайтеtelecastImages
— изображения для передачиtvShow
— передача. При наличии, указывается только идентификатор передачиchannel
— канал выпуска передачи. При наличии, указывается только идентификатор каналаageRestriction
— возрастное ограничение для выпуска передачиviews_count
— количество просмотров (прослушиваний) выпуска передачи за все времяtime_offset
:
parent_id
): время в секундах от начала выпуска передачи до начала сюжета в нем.parent_id
— идентификатор выпуска передачи, к которой относится сюжет (новое в версии 2.8.1)categories
— категории передач (новое в 2.9)ad_tags
— список идентификаторов рекламных тэговalias
— строковый идентификатор передачи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;
}
Замечания:
type
— фиксированный тип категории, описывающий семантику использования;title
— человекочитаемое название категории.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;
}
Замечания:
channelId
— числовой идентификатор каналаtitle
— локализованное название каналаdescription
— локализованное описание каналаlogoURL
— логотип каналаpromoURL
— ссылка на сайт каналаscheduledDates
— список дней, для которых есть расписание передачcurrentTelecast
— текущая передачаalias
— строковый идентификатор каналаageRestriction
— возрастное ограничение для каналаhasSchedule
— наличие расписания для канала (передается тогда, когда передача подробной информации о канале не нужна)type
— тип канала (новое в 2.8):
TV
— телевизионный канал (значение по умолчанию);RADIO
— радиоканал.artworkURL
— афиша для канала (новое в 2.8);categories
— категории передач, вещаемых на канале (новое в 2.9).rubrics
— рубрики, в которые входит канал (новое в 2.13).message Rubric {
optional int64 id;
optional string title;
}
Замечание:
id
— идентификатор рубрики;title
— человекочитаемое название категории.message Schedule {
optional string channelId = 1 [deprecated = true];
repeated Telecast telecastsList = 2;
optional int64 items_skipped = 3;
optional int64 total_count = 4;
}
Замечание:
items_skipped
— количество пропущенных выпусков передач в выдачеtotal_count
— общее количество выпусков передач, подпавших под действие фильтраmessage ChannelsList {
optional string title = 1;
repeated Channel channels = 2;
}
message TitlesRequest {
repeated string titles = 1;
}
Замечания:
titles
— список названий каналов.ao
— за ненадобностью;uid
— должен передаваться на сервер статистики, а не в API;tz
— данные берутся из описания территории./list
помечен как «устаревший».Channel
.idbytitle
Schedule
добавлены поля items_skipped
и total_count
, отвечающие за частичную выдачу информацииTelecast
добавлено поле views_count
, отвечающее за количество просмотров выпуска телепередачи пользователями сервисаaccess
для канала помечено устаревшимstorage_hours
для канала, отражающий время хранения записей выпусков телепередач на серверах сервиса Peers.TVgetcollections
, списка выпусков телепередач по тематике — collection
.getcollections
telecastInfo
.time_offset
, описывающий разницу между датой фактического выхода и датой выхода по расписанию.channels
по списку идентификаторов каналов при помощи параметра channel_ids
;fields
в метод channels
для осуществления частичной выдачи.channel_ids
метода channels
переименован в channel
по аналогии с остальными методами.type
в сообщение Channel
;artworkURL
в сообщение Channel
;parent_id
для ссылки на выпуск передачи.channels
, внесены дополнительные пояснения.views_count
сообщения Telecast
.list.xspf
, так как он доступен только в рамках PeersTV API;idbytitle
.device
, device-version
, которые более не используютсяschedule
t
обозначен как рекомендуемый к указанию при обращениях к методами APITelecastImage
;ad_tags
из сообщения Telecast
Channel
tvshows
из Registry API ↩