API — различия между версиями

Материал из Твое Интернет Телевидение
Перейти к: навигация, поиск
(→‎Описание метода)
(→‎[epg] EPG для определенных каналов на заданный период времени)
Строка 502: Строка 502:
 
::::'''<REC_URL>''' - прямая ссылка архивную запись
 
::::'''<REC_URL>''' - прямая ссылка архивную запись
  
−
==[epg] EPG для определенных каналов на заданный период времени==
+
==[epg] Работа с телепрограммой==
  
−
http://api.iptv.so/1.0/xml/epg?cid=1&time=1473541200&period=0&channels=2,1,4,5,6,1,8,9,11,12,13,14&desc_limit=100&sort=1&limit=10&page=1&sid=session_id
+
===Описание метода===
 +
Возвращает '''постраничный список телеканалов''' с телепрограммой в зависимости от указанных параметров.
  
−
time<br/>
+
===Формат запроса===
−
@time - epg start time, unixtime<br/>
+
<pre>http://api.iptv.so/<API_VERSION>/<FORMAT_TYPE>/channels?token=<TOKEN_ID>&gid=<GROUP_ID>&sort=1&limit=20&page=1</pre>
−
@period - epg time to period, hours<br/>
+
:Обязательные параметры:
−
@channels - epg for channels ex.: 1,2,3<br/>
+
Обязательных параметров нет, по умолчанию возвращает постраничный список всех телеканалов имеющих телепрограмму с лимитом в 20 каналов начиная с первой страницы.
−
or @gid - all channels in this group id<br/>
+
:Необязательные параметры
−
@desc_limit - int, 0 - off, 200 - max<br/>
+
::'''sort''' - способ сортировки. Доступные значения: 1 - сортировка по умолчанию, 2 - по ID канала, 3 - по имени канала.
−
@limit<br/>
+
::'''desc_limit''' - лимит на количество символов в описании к телепередачам. 0 - описания выводится не будут. По умолчанию выводится полное описание при его наличии.
−
@start<br/>
+
<div style="border:1px solid #ccc;">
−
@page<br/>
+
::'''time''' - время начала программ передач. Используется в паре с параметром period. Если period не указан, то параметр time игнорируется, возвращается '''текущая передача''' для каждого канала.
−
@sort - 1|2|3
+
::'''period''' - получаем телепрограмму с начала времени time на количество часов указанных в этом параметре. Если параметр time не указан, временем начала считается начало текущих суток.
 +
::::'''или'''
 +
::'''c_to''' - взаимоисключающий с time и period параметр. Указывает на необходимое количество передач начиная с текущей. Значение от 1 до 20.
 +
</div>
 +
<div style="border:1px solid #ccc; margin-top:2px;">
 +
::'''channels''' - список каналов для которых необходимо получить телепередачу, через запятую.
 +
::::'''или'''
 +
::'''gid''' - ID категории каналов для которых необходимо получить телепередачу. Взаимоисключающий с channels параметр.
 +
</div>
 +
 
 +
===Примеры запроса===
 +
Получить текущую и три следующих телепередачи для канала с ID 1
 +
<pre>http://api.iptv.so/1.0/json/epg?token=<TOKEN_ID>&channels=1&c_to=3</pre>
 +
 
 +
Получить телепередачу для канала с ID 1 на 16 сентября 2016 года
 +
<pre>http://api.iptv.so/1.0/json/epg?token=<TOKEN_ID>&channels=1&time=1473984000&period=24</pre>
 +
 
 +
Получить текущую программу передач для каналов в группе ID=1 со второй страницы по 12 каналов на страницу c описанием телепередач не более 200-т символов и отсортировать каналы по названию
 +
<pre>http://api.iptv.so/1.0/json/epg?token=<TOKEN_ID>&gid=1&period=0&limit=12&page=2&desc_limit=200&sort=3</pre>
 +
 
 +
 
 +
===Формат полученных данных===
 +
{| class="wikitable" style="float:left; margin-right:20px"
 +
|+XML
 +
|-
 +
|<pre>
 +
<response>
 +
  <info>
 +
    <limit><ITEMS_LIMIT></limit>
 +
    <count><ITEMS_COUNT></count>
 +
      <pages><ITEMS_PAGES></pages>
 +
      <page><ITEMS_CURRENT_PAGE></page>
 +
  </info>
 +
  <epg>
 +
    <channels>
 +
      <item>
 +
        <id><CH_ID></id>
 +
        <name><CH_NAME></name>
 +
          <epg>
 +
            <item>
 +
              <text><CH_PROG_TEXT></text>
 +
              <start><CH_PROG_START></start>
 +
              <end><CH_PROG_END></end>
 +
              <description><CH_PROG_DESC></description>
 +
            </item>
 +
            ...
 +
          </epg>
 +
        </item>
 +
        ...
 +
    </channels>
 +
  </epg>
 +
  <session>
 +
    <token><TOKEN_ID></token>
 +
    <expire><TOKEN_EXPIRE></expire>
 +
    <now><SERVERTIME></now>
 +
  </session>
 +
</response>
 +
</pre>
 +
|}
 +
{| class="wikitable"
 +
|+JSON
 +
|-
 +
|<pre>{
 +
  "info": {
 +
    "limit": <ITEMS_LIMIT>,
 +
    "count": <ITEMS_COUNT>,
 +
    "pages": <ITEMS_PAGES>,
 +
    "page": <ITEMS_CURRENT_PAGE>
 +
    },
 +
  "epg": {
 +
    "channels": [
 +
      {
 +
        "id": <CH_ID>,
 +
        "name": <CH_NAME>,
 +
          "epg": [
 +
          {
 +
            "text": <CH_PROG_TEXT>,
 +
            "start": <CH_PROG_START>,
 +
            "end": <CH_PROG_END>,
 +
            "description": <CH_PROG_DESC>
 +
          }
 +
          ...
 +
          ]
 +
      },
 +
      ...
 +
    ]
 +
  },
 +
  "session": {
 +
    "token": <TOKEN_ID>,
 +
    "expire": <TOKEN_EXPIRE>,
 +
    "now": <SERVERTIME>
 +
  }
 +
}
 +
</pre>
 +
|}
 +
<div style="clear:both"></div>

Версия 09:31, 18 сентября 2016

Содержание

Общие обозначения

  • <FORMAT_TYPE> - формат возврата ответа от сервера. Доступны формат XML и JSON.
  • <API_VERSION> - Версия API. Текущая версия 1.0
  • <SERVERTIME> - Текущее время на сервере.
  • <TOKEN_ID> - Уникальный ключ token полученный в результате авторизации.
  • <TOKEN_EXPIRE> - время до которого ключ token будет актуален.

Методы

[auth] Авторизация

Описание метода

Самым первым запросом на сервер API всегда должен быть запрос на авторизацию клиента. В случае успеха, сервер вернет информацию о аккаунте клиента и информации о созданной сессии в которой содержится уникальный ключ - token, для доступа к остальным методам API. Без этого ключа вызов других методов API невозможен.

Формат запроса

http://api.iptv.so/<API_VERSION>/<FORMAT_TYPE>/auth?hash=<HASH>

HASH - это MD5-хеш полученный в результате конкатенации логина пользователя и MD5-хеша пароля пользователя - MD5(<USER_LOGIN> + MD5(<USER_PASSWORD>))


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

PHP 

$data=file_get_contents('http://api.iptv.so/1.0/xml/auth?hash='.MD5($login.MD5($password)));


Формат полученных данных

XML 
  <response>
    <account>
      <info>
        <login><USER_LOGIN></login>
        <mail><USER_EMAIL></mail>
        <name><USER_NAME></name>
      </info>
      <options>
        <OPTION_NAME>1|0</OPTION_NAME>
        ...
      </options>
      <services>
        <item>
          <id><SERVICE_ID></id>
          <expire><SERVICE_EXPIRE></expire>
          <name><SERVICE_NAME></name>
          <type><SERVICE_TYPE></type>
        </item>
        ...
      </services>
      <settings>
        <server_id><SERVER_ID></server_id>
        <server_name><SERVER_NAME></server_name>
        <tz_name><TZ_NAME></tz_name>
        <tz_gmt><TZ_GMT></tz_gmt>
      </settings>
    </account>
    <session>
      <token><TOKEN_ID></token>
      <expire><TOKEN_EXPIRE></expire>
      <now><SERVERTIME></now>
    </session>
</response>
JSON 
{	"account": {
		"info": {
			"login": <USER_LOGIN>,
			"mail": <USER_EMAIL>,
			"name": <USER_NAME>
		},
		"options": {
			<OPTION_NAME>: 1|0
		},
		"services": [
			{
				"id": <SERVICE_ID>,
				"expire": <SERVICE_EXPIRE>,
				"name": <SERVICE_NAME>,
				"type": <SERVICE_TYPE>
			},
			...
		],
		"settings": {
			"server_id": <SERVER_ID>,
			"server_name": <SERVER_NAME>,
			"tz_name": <TZ_NAME>,
			"tz_gmt": <TZ_GMT>
		}
	},
	"session": {
		"token": <TOKEN_ID>,
		"expire": <TOKEN_EXPIRE>,
		"now": <SERVERTIME>
	}
}

Описание полученных данных

account - содержит в себе

info - информация о аккаунте клиента
USER_LOGIN - логин клиента
USER_EMAIL - e-mail клиента
USER_NAME - имя клиента
options - список доступных
OPTION_NAME - имя опции, может принимать значение 1 - доступно или 0 - недоступно для клиента.
services - список доступных для клиента сервисов, может содержать несколько вложенных элементов item удовлетворяющих следующему описанию:
SERVICE_ID - уникальный ID сервиса
SERVICE_EXPIRE - срок истечения подписки на сервис
SERVICE_NAME - имя сервиса
SERVICE_TYPE - тип сервиса [пакет каналов, опция, плейлист]
settings - текущие настройки клиента
SERVER_ID - ID сервера вещания
SERVER_NAME - отображаемое имя сервера вещания
TZ_NAME - имя временной зоны
TZ_GMT - смещение временной зоны относительно Гринвича

session - описание текущей сессии

TOKEN_ID - ключ доступа который используется для вызова всех остальных методов API
TOKEN_EXPIRE - время до которого действителен текущий ключ доступа. При каждом успешном запросе срок жизни ключа продлевается до 24-х часов с текущей даты.
SERVERTIME - текущее время на сервере



[account] Аккаунт

Описание метода

Возвращает ту же информацию, что и метод auth. Может использоваться для получения информации об аккаунте без повторной авторизации.


Формат запроса

http://api.iptv.so/<API_VERSION>/<FORMAT_TYPE>/account?token=<TOKEN_ID>



[logout] Закрытие сессии

Описание метода

Метод уничтожает текущую сессию и все данные хранящиеся в ней.


Формат запроса

http://api.iptv.so/<API_VERSION>/<FORMAT_TYPE>/logout?token=<TOKEN_ID>


Формат полученных данных

XML 
<response>
  <session>
    <destroyed>1</destroyed>
    <now><SERVERTIME></now>
  </session>
</response>
JSON 
{
	"session": {
		"destroyed": 1,
		"now": <SERVERTIME>
	}
}



[groups] Список ТВ категорий

Описание метода

Возвращает полный список доступных для клиента ТВ категорий.


Формат запроса

http://api.iptv.so/<API_VERSION>/<FORMAT_TYPE>/groups?token=<TOKEN_ID>


Формат полученных данных

XML 
<response>
  <groups>
    <item>
      <name_ru><GROUP_ID></name_ru>
      <name_ru><GROUP_NAME_RU></name_ru>
      <name_en><GROUP_NAME_EN></name_en>
      <count><GROUP_CHANNELS_COUNT></count>
    </item>
    ...
  </groups>
  <session>
    <token><TOKEN_ID></token>
    <expire><TOKEN_EXPIRE></expire>
    <now><SERVERTIME></now>
  </session>
</response>
JSON 
{
	"groups": [
		{
			"id": <GROUP_ID>,
			"name_ru": <GROUP_NAME_RU>,
			"name_en": <GROUP_NAME_EN>,
			"count": <GROUP_CHANNELS_COUNT>
		},
		...
	],
	"session": {
		"token": <TOKEN_ID>,
		"expire": <TOKEN_EXPIRE>,
		"now": <SERVERTIME>
	}
}


Описание полученных данных

groups - содержит в себе

GROUP_ID - ID группы
GROUP_NAME_RU - Имя группы на русском языке
GROUP_NAME_EN - Имя группы на английском языке
GROUP_CHANNELS_COUNT - Количество каналов доступных для клиента в этой группе



[channels] Список каналов в группе

Описание метода

Возвращает постраничный список доступных для клиента каналов в определенной категории.

Формат запроса

http://api.iptv.so/<API_VERSION>/<FORMAT_TYPE>/channels?token=<TOKEN_ID>&gid=<GROUP_ID>&sort=1&limit=20&page=1
Обязательные параметры:
gid - ID группы каналов.
Необязательные параметры:
sort - способ сортировки. Доступные значения: 1 - сортировка по умолчанию, 2 - по ID канала, 3 - по имени канала.

Формат полученных данных

XML 
<response>
  <channels>
    <item>
      <info>
        <id><CH_ID></id>
        <name><CH_NAME></name>
        <groups><CH_GROUPS></groups>
        <protected><CH_PROTECTED_FLAG></protected>
        <records><CH_REC_HOURS></records>
      </info>
      <epg>
        <text><CH_PROG_TEXT></text>
        <start><CH_PROG_START></start>
        <end><CH_PROG_END></end>
        <description><CH_PROG_DESC></description>
      </epg>
    </item>
    ...
  </channels>
  <session>
    <token><TOKEN_ID></token>
    <expire><TOKEN_EXPIRE></expire>
    <now><SERVERTIME></now>
  </session>
</response>
JSON 
{
	"channels": [
		{
			"info": {
				"id": <CH_ID>,
				"name": <CH_NAME>,
				"groups": <CH_GROUPS>,
				"protected": <CH_PROTECTED_FLAG>,
				"records": <CH_REC_HOURS>,
			},
			"epg": [
				"text": <CH_PROG_TEXT>,
				"start": <CH_PROG_START>,
				"end": <CH_PROG_END>,
				"description": <CH_PROG_DESC>
			]
		},
		...
	],
	"session": {
		"token": <TOKEN_ID>,
		"expire": <TOKEN_EXPIRE>,
		"now": <SERVERTIME>
	}
}


Описание полученных данных

channels - содержит массив данных

info - общая информация о канале
CH_ID - ID канала
CH_NAME - имя канала
CH_GROUPS - ID категорий канала перечисленных через запятую
CH_PROTECTED_FLAG - указывает закрыт ли канал кодом доступа, значение 1 или 0.
CH_REC_HOURS - наличие архива на канале в часах, 0 - архив отсутствует
epg - информация о текущей программе передач. Пустой элемент, если телепрограмма не доступна.
CH_PROG_TEXT - название текущей передачи
CH_PROG_START - время начала передачи
CH_PROG_END - время окончания передачи
CH_PROG_DESC - описание передачи. Отсутствует, если описание недоступно.



[live] Получение ссылки на прямую трансляцию

Описание метода

Метод возвращает краткую информацию по каналу и ссылку на поток его прямой трансляции.

  • Ссылка на поток должна быть использована в течении 5 минут
  • Ссылка на поток привязана к IP клиента полученного в результате его запроса на сервер API.
  • Ссылка на поток привязана к серверу вещания для которого она была получена.


Формат запроса

http://api.iptv.so/<API_VERSION>/<FORMAT_TYPE>/live?token=<TOKEN_ID>&cid=<CH_ID>&protected=<CODE>
Обязательные параметры:
cid - ID телеканала.
Необязательные параметры:
protected - код родительского контроля, высылается в активационном письме. По умолчанию равен 0000 (четыре ноля).

Формат полученных данных

XML 
<response>
  <live>
    <channel>
      <id><CH_ID></id>
      <name><CH_NAME></name>
      <protected><CH_PROTECTED_FLAG></protected>
      <records><CH_REC_HOURS></records>
    </channel>
    <url><LIVE_URL></url>
  </live>
  <session>
    <token><TOKEN_ID></token>
    <expire><TOKEN_EXPIRE></expire>
    <now><SERVERTIME></now>
  </session>
</response>
JSON 
{
	"live": {
		"channel": {
			"id": <CH_ID>,
			"name": <CH_NAME>,
			"protected": <CH_PROTECTED_FLAG>,
			"records": <CH_REC_HOURS>
		},
		"url": <LIVE_URL>
	},
	"session": {
		"token": <TOKEN_ID>,
		"expire": <TOKEN_EXPIRE>,
		"now": <SERVERTIME>
	}
}


Описание полученных данных

live - содержит:

channel - общая информация о канале
CH_ID - ID канала
CH_NAME - имя канала
CH_PROTECTED_FLAG - указывает закрыт ли канал кодом доступа, значение 1 или 0.
CH_REC_HOURS - наличие архива на канале в часах, 0 - архив отсутствует
url
<LIVE_URL> - прямая ссылка на прямую трансляцию



[rec] Получение ссылки на запись

Описание метода

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

  • Ссылка на поток должна быть использована в течении 5 минут
  • Ссылка на поток привязана к IP клиента полученного в результате его запроса на сервер API.
  • Ссылка на поток привязана к серверу вещания для которого она была получена.
  • Запись начинается с времени указанного в параметре time.
  • Параметр time может использоваться как способ перемотки.
  • Длинна записи = <CH_PROG_END> - <CH_PROG_START>.
  • Начало записи = <REC_START_TIME>
  • Конец записи = <CH_PROG_END>

Формат запроса

http://api.iptv.so/<API_VERSION>/<FORMAT_TYPE>/rec?token=<TOKEN_ID>&cid=<CH_ID>&time=<REC_START_TIME>&protected=<CODE>
Обязательные параметры:
cid - ID телеканала.
time - Время с которого начинается запись.
Необязательные параметры:
protected - код родительского контроля для закрытых каналов, высылается в активационном письме. По умолчанию равен 0000 (четыре ноля).

Формат полученных данных

XML 
<response>
  <rec>
    <channel>
      <id><CH_ID></id>
      <name><CH_NAME></name>
      <protected><CH_PROTECTED_FLAG></protected>
      <title><CH_PROG_TEXT></title>
      <start><CH_PROG_START></start>
      <end><CH_PROG_END></end>
      <records><CH_REC_HOURS></records>
    </channel>
    <url><REC_URL></url>
  </rec>
  <session>
    <token><TOKEN_ID></token>
    <expire><TOKEN_EXPIRE></expire>
    <now><SERVERTIME></now>
  </session>
</response>
JSON 
{
	"rec": {
		"channel": {
			"id": <CH_ID>,
			"name": <CH_NAME>,
			"protected": <CH_PROTECTED_FLAG>,
			"title": <CH_PROG_TEXT>,
			"start": <CH_PROG_START>,
			"end": <CH_PROG_END>,
			"records": <CH_REC_HOURS>
		},
		"url": <REC_URL>
	},
	"session": {
		"token": <TOKEN_ID>,
		"expire": <TOKEN_EXPIRE>,
		"now": <SERVERTIME>
	}
}


Описание полученных данных

rec - содержит:

channel - общая информация о канале
CH_ID - ID канала
CH_NAME - имя канала
CH_PROTECTED_FLAG - указывает закрыт ли канал кодом доступа, значение 1 или 0.
CH_PROG_TEXT - название текущей передачи
CH_PROG_START - время начала передачи
CH_PROG_END - время окончания передачи
CH_REC_HOURS - наличие архива на канале в часах, 0 - архив отсутствует
url
<REC_URL> - прямая ссылка архивную запись

[epg] Работа с телепрограммой

Описание метода

Возвращает постраничный список телеканалов с телепрограммой в зависимости от указанных параметров.

Формат запроса

http://api.iptv.so/<API_VERSION>/<FORMAT_TYPE>/channels?token=<TOKEN_ID>&gid=<GROUP_ID>&sort=1&limit=20&page=1
Обязательные параметры:

Обязательных параметров нет, по умолчанию возвращает постраничный список всех телеканалов имеющих телепрограмму с лимитом в 20 каналов начиная с первой страницы.

Необязательные параметры
sort - способ сортировки. Доступные значения: 1 - сортировка по умолчанию, 2 - по ID канала, 3 - по имени канала.
desc_limit - лимит на количество символов в описании к телепередачам. 0 - описания выводится не будут. По умолчанию выводится полное описание при его наличии.
time - время начала программ передач. Используется в паре с параметром period. Если period не указан, то параметр time игнорируется, возвращается текущая передача для каждого канала.
period - получаем телепрограмму с начала времени time на количество часов указанных в этом параметре. Если параметр time не указан, временем начала считается начало текущих суток.
или
c_to - взаимоисключающий с time и period параметр. Указывает на необходимое количество передач начиная с текущей. Значение от 1 до 20.
channels - список каналов для которых необходимо получить телепередачу, через запятую.
или
gid - ID категории каналов для которых необходимо получить телепередачу. Взаимоисключающий с channels параметр.

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

Получить текущую и три следующих телепередачи для канала с ID 1 

http://api.iptv.so/1.0/json/epg?token=<TOKEN_ID>&channels=1&c_to=3

Получить телепередачу для канала с ID 1 на 16 сентября 2016 года 

http://api.iptv.so/1.0/json/epg?token=<TOKEN_ID>&channels=1&time=1473984000&period=24

Получить текущую программу передач для каналов в группе ID=1 со второй страницы по 12 каналов на страницу c описанием телепередач не более 200-т символов и отсортировать каналы по названию 

http://api.iptv.so/1.0/json/epg?token=<TOKEN_ID>&gid=1&period=0&limit=12&page=2&desc_limit=200&sort=3


Формат полученных данных

XML 
<response>
  <info>
    <limit><ITEMS_LIMIT></limit>
    <count><ITEMS_COUNT></count>
      <pages><ITEMS_PAGES></pages>
      <page><ITEMS_CURRENT_PAGE></page>
  </info>
  <epg>
    <channels>
      <item>
        <id><CH_ID></id>
        <name><CH_NAME></name>
          <epg>
            <item>
              <text><CH_PROG_TEXT></text>
              <start><CH_PROG_START></start>
              <end><CH_PROG_END></end>
              <description><CH_PROG_DESC></description>
            </item>
            ...
          </epg>
        </item>
        ...
    </channels>
  </epg>
  <session>
    <token><TOKEN_ID></token>
    <expire><TOKEN_EXPIRE></expire>
    <now><SERVERTIME></now>
  </session>
</response>
JSON 
{
  "info": {
    "limit": <ITEMS_LIMIT>,
    "count": <ITEMS_COUNT>,
    "pages": <ITEMS_PAGES>,
    "page": <ITEMS_CURRENT_PAGE>
    },
  "epg": {
    "channels": [
      {
        "id": <CH_ID>,
        "name": <CH_NAME>,
          "epg": [
           {
             "text": <CH_PROG_TEXT>,
             "start": <CH_PROG_START>,
             "end": <CH_PROG_END>,
             "description": <CH_PROG_DESC>
           }
           ...
          ]
      },
      ...
    ]
  },
  "session": {
    "token": <TOKEN_ID>,
    "expire": <TOKEN_EXPIRE>,
    "now": <SERVERTIME>
  }
}
Источник — «http://wiki.tvclub.us/index.php?title=API&oldid=783»