Jump to content

Rest Api English


Supervisor
 Share

Recommended Posts

All requests to REST API are based on the following URL:

 

httр://iptv.kartina.tv/api/<request type>/<procedure>?param1=value&param2=value...

 

<request type> could be xml or json

Please find below the procedure names and parameters.

 

For example:

httр://iptv.kartina.tv/api/xml/epg?cid=2&day=260610

 

COOKIE

 

We use standard HTTP sessions with COOKIE support to identify and open customer sessions.

 

Please pay attention to the different steps:

The first step should always be the login. This procedure opens a new customer session. If successfully generated a response of the current customer state and session will create a COOKIE which will be used for all follow-up requests.

The COOKIE contains the session ID. All other requests without this ID will cause errors. Always use the logout to close the customer session. The last step should always be the logout.

 

Furthermore the parameters can be send by URL. Use the cookie from the response sid_name.

Attention! This way of communication is not as secure as using the described login.

The response has the format of an associative array, JSON or XML depending on the used URL.

Wrong requests cause the transmission of the following data containing the error message:

 

<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>
  <message>An error message</message>
  <cоde>9999</cоde>
</error>
<servertime>1277893631</servertime>
</response>

 

 

Time format. All data has the unixtime format.

 

/login?login=<login>&pass=<password>&device=<apple|default:all>

 

Input parameters:

 

  • login - login, the customer's id.
  • password, integer customer's password.
  • device - the type of device.

 

 

Response:

 

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <sid>[session identifier]</sid>
   <sid_name>[name of the session identifier variable]</sid>
   <account>
     <login>[login]</login>
     <packet_name>[packet name]</packet_name>
     <packet_expire>[date and time of packet expiration]</packet_expire>
   </account>
   <servertime>[date and time of answer generation]</servertime>
</response>

 

 

The parameter of the session’s identifier is transferred in case of the customer not being able to receive "cookie" heading.

 

/account

 

Returns the information to an account similar to /login

 

/logout

Call without the parameters (the session identifier has to be transferred in form of "cookie").

 

Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<message>M_LOGOUT_OK</message>
<servertime>1277807573</servertime>
</response>

 

/channel_list

Call without the parameters (the session identifier has to be transferred in form of "cookie “).

 

Response:

 

<?xml version="1.0" encoding="UTF-8"?>
<response>
 <groups>
   <item>
     <id>[id identifier]</id>
     <name>[group name]</name>
     <color>[CSS color of group]</color>
     <channels>
       <item>
         <id>[channel identifier]</id>
         <name>[name of channel]</name>
         <stream_params> [the parameters of stream]
           <item>
             <rate>[bitrate]  Possible bitrate channel. Set in the configuration variable bitrate</rate>
              <ts>[timeshift] hours for example: a value of 2 - delay broadcast at 2:00. Get url broadcasting possible by configuring the variable</ts>
           </item>
           ...
           <item>
             <rate>1500</rate>
             <ts>11</ts>
           </item>
         </stream_params>
         <is_video>[flag streaming video 0/1 1 Video, 0-radio]</is_video>
         <need_bandwidth>[bitrate are recomended (mbps)]<need_bandwidth>
         <protected>[flag if the channel is closed 0/1]</protected>
         <have_archive>[flag has a channel archive 0/1]</have_archive>
         <icon>[relative path will icon file of channel]</icon>
         <epg_progname>[name of the current TV]</epg_progname>
         <epg_start>[Date and time start of the current transfer]</epg_start>
         <epg_end>[Date and time termination of the current transfer]</epg_end>
       </item>
       <item>   /* example*/
         <id>3</id>
         <name>Pоссия</name>
         <stream_params>
            <item>
               <rate>1500</rate>
               <ts>0</ts>
            </item>
            <item>
               <rate>900</rate>
               <ts>0</ts>
            </item>
            <item>
               <rate>1500</rate>
               <ts>1</ts>
            </item>
            <item>
               <rate>1500</rate>
               <ts>2</ts>
            </item>
            <item>
               <rate>1500</rate>
               <ts>3</ts>
            </item>
            <item>
               <rate>1500</rate>
               <ts>4</ts>
            </item>
            <item>
               <rate>1500</rate>
               <ts>8</ts>
            </item>
            <item>
               <rate>1500</rate>
               <ts>9</ts>
            </item>
            <item>
               <rate>1500</rate>
               <ts>10</ts>
            </item>
            <item>
               <rate>1500</rate>
               <ts>11</ts>
            </item>
         </stream_params>
         <is_video>1</is_video>
         <protected>0</protected>
         <have_archive>1</have_archive>
         <icon>/img/ico/3.gif</icon>
         <epg_progname>ВЕСТИ-МОСКВА</epg_progname>
         <epg_start>1277807400</epg_start>
         <epg_end>1277808600</epg_end>
       </item>
       ...        /* пример */
     </channels>
   </item>
   <item>
     <id>2</id>
     <name>Новости</name>
     <color>#ef0000</color>
     <channels>
       <item>
         <id>6</id>
         <name>РТР Вести</name>
         <is_video>1</is_video>
         <protected>0</protected>
         <icon>/img/ico/6.gif</icon>
         <epg_progname>"Вести. Сейчас. Главные события".</epg_progname>
         <epg_start>1277807400</epg_start>
         <epg_end>1277807700</epg_end>
       </item>
       ...
     </channels>
   </item>
 </groups>
 <servertime>1277807687</servertime>
</response>

 

 

 

/get_url?cid=<channel ID>&gmt=<Date and time of position in Archive>&protect_code=<password for protected channels>

 

Parameters:

 

  • cid - channel ID from channel list
  • gmt - Date and time of position in VOD in unixtime format
  • protect_code - password for password protected channels. If the channel is protected but lacking a password then the response has the tag <url> with value "protected".

 

 

Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<url>http/ts://217.19.222.34:18046/?ticket=W4z3WFdoSRnMMXHgYFq...md4ZGtVyT6mjgqGZk%3D :http-caching=1500 :no-http-reconnect</url>
<servertime>1277808472</servertime>
</response>

 

URL is especially adapted to be played by VLC with needed parameters

 

URL will be generated only once. For repeated playing we need to generate the URL again. By trying to play several URL concurrently only the last URL will be played. This kind of limitation allows only one stream with one session.

 

/epg?cid=<channel ID>&day=<date DDMMYY>

 

Parameters

  • cid - channel ID received from the channel list
  • day - date DDMMYY (For example: 29 juni 2010 = 290610)

 

<?xml version="1.0" encoding="UTF-8"?>
<response>
<epg>
<item>
<ut_start>[дата и время начала передачи]</ut_start>
<progname>[название передачи]</progname>
</item>
<item>
<ut_start>1277521800</ut_start>
<progname>"Вся Россия".</progname>
</item>
<item>
<ut_start>1277522700</ut_start>
<progname>"Диалоги о животных".</progname>
</item>
...
</epg>
<servertime>1277809426</servertime>
</response>

 

 

/epg3?dtime=<Date and time to start EPG>&period=<how many hours ahead>

The telecast delivery of accessible channels from the time indicated in “dtime” to the following “period” hours.

It is necessary for the organization of the function “what’s on air” on the website http://tv.yahoo.com/listings. The program is generated in accordance to the "timeshift" variable exposed in settings by the user.

Parameters:

  • dtime – date and time (unixtime) of the EPG’s beginning. The current situation is selected by default (on north time)
  • period – on how many hours forward. EPG for next 3 hours is issued by default.

 

 

 

 

 

<?xml version="1.0" encoding="UTF-8"?>
<response>
<item>
<id>2</id>
<name>Первый</name>
<epg>
<item>
<ut_start>1278944400</ut_start>
<progname>"ХОЧУ ЗНАТЬ" с Михаилом Ширвиндтом</progname>
<t_start>17:20</t_start>
</item>
<item>
<ut_start>1278946200</ut_start>
<progname>"ОБРУЧАЛЬНОЕ КОЛЬЦО" - многосерийный фильм Сериал.</progname>
<t_start>17:50</t_start>
</item>
</epg>
</item>
<item>
<id>3</id>
<name>Pоссия</name>
<epg>
<item>
<ut_start>1278942600</ut_start>
<progname>"ТАЙНЫ СЛЕДСТВИЯ" - детективный сериал. В главной роли Анна Ковальчук</progname>
<t_start>16:50</t_start>
</item>
<item>
<ut_start>1278948600</ut_start>
<progname>"КУЛАГИН И ПАРТНЕРЫ"</progname>
<t_start>18:30</t_start>
</item>
</epg>
</item>
<item>
<id>54</id>
<name>Discovery</name>
<epg>
<item>
<ut_start>1278943800</ut_start>
<progname>"СМЕРТЕЛЬНЫЙ УЛОВ: ВРЕМЯ РАСПЛАТЫ"</progname>
<t_start>17:10</t_start>
</item>
<item>
<ut_start>1278947100</ut_start>
<progname>"ДЕРЗКИЕ ПРОЕКТЫ: АРИЗОНСКИЕ "КАРДИНАЛЫ"</progname>
<t_start>18:05</t_start>
</item>
<item>
<ut_start>1278950400</ut_start>
<progname>"РАЗРУШИТЕЛИ ЛЕГЕНД: СПЕЦВЫПУСК "ДЖЕЙМС БОНД". 1 часть"</progname>
<t_start>19:00</t_start>
</item>
</epg>
</item>
<servertime>1278944765</servertime>
</response>

 

/epg_next?cid=<id channel>

 

Returns EPG on flowing and on 3 subsequent telecasts of the channel with set ID

 

<?xml version="1.0" encoding="UTF-8"?>
<response>
<epg>
<item>
<ts>1294834800</ts>
<progname>ХОЧУ ЗНАТЬ
- с Михаилом Ширвиндтом</progname>
</item>
<item>
<ts>1294836600</ts>
<progname>"ОБРУЧАЛЬНОЕ КОЛЬЦО"
- сериал Сериал.</progname>
</item>
<item>
<ts>1294840200</ts>
<progname>ФЕДЕРАЛЬНЫЙ СУДЬЯ</progname>
</item>
</epg>
<servertime>1294835324</servertime>
</response>

 

/favorites

List of favourite channels. The storage of 12 favourite channels is organized. Each cell is named by the index “place”, containing the identifier of the channel without the parameter.

 

<?xml version="1.0" encoding="UTF-8"?>
<response>
<favorites>
<item>
<place>2</place>
<channel_id>2</channel_id>
</item>
<item>
<place>8</place>
<channel_id>3</channel_id>
</item>
</favorites>
<servertime>1278944963</servertime>
</response>

 

/favorites_set?place=<number of cells for storage>&cid=<Channel ID>

 

Places the favourite channel in the defined cell . If cid=0 is installed, then the channel will be deleted from the favourite channels list.

 

Response: Message burst about successful fulfillment or the error burst.

 

/settings?var=<http_caching|stream_server|timeshift|timezone>

To receive the value of the variable adjustment.

 

 

• http_caching – Time buffering of the stream in milliseconds.

• stream_server - IP of the streaming server. Possible values are transferred in List array.

• timeshift - timeshift. Possible values are transferred in List array.

• timezone – time zone . Possible values from -12 up to +12

 

Responce:

 

<?xml version="1.0" encoding="UTF-8"?>
<response>
<settings>
<name>timeshift</name>
<value>3</value>
<list>
<item>0</item>
<item>1</item>
<item>2</item>
<item>3</item>
<item>4</item>
<item>8</item>
<item>9</item>
<item>10</item>
<item>11</item>
</list>
</settings>
<servertime>1278946045</servertime>
</response>

 

If the variable has a list of possible values, then they are returned in an array with the "list" parameter.

 

 

/settings_set?var=<pcode|http_caching|stream_server|timeshift|timezone>&val=<value>

The set of the settings option.

 

  • pcode – set protected code. Need to send additional parameters: old_code – previous password, new_code – new password, confirm_code – confirmation of the new password
  • http_caching. Additional parameter val send the possible value of the installation.
  • stream_server - install IP streaming server. “val” transfers the possible value of the installation.
  • timeshift - val transfers the possible value of the installation.
  • timezone - time zone . Possible values from -12 up to +12

 

 

VIDEO ON DEMAND (VOD)

 

To receive the list of films from base VOD. Films are deduced as it should be set in the parameter type, portions on 20 films.

 

Parameters for formation of the list of films:

 

/vod_list?

 

  • type = best|last|text
  • page = 1
  • query = text if type==text
  • genre = id
  • nums = <films on page>

 

  • type = best - The best films it agree a rating on viewings.

    last - The same list of films but is sorted by addition date upside-down.

    text - Search in base under the film name. A line for search in query

  • page = N - Number of page for a conclusion. 1st number of page is by default established.
  • query - Line for search. Works if it is established type=text
  • genre = id - The filter on genres. Shows films only the specified genre. Transfer of deduced genres through a sign "|" is possible. For example: genre=205|206|215
  • nums = NN Quantity of films on page by default: 20

 

Answer:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<type>best</type> [Current type of inquiry]
<total>60</total> [in total records satisfying to inquiry]
<count>20</count> [Quantity on current page]
<page>1</page> [Page number]
<rows>
<item>
<id>119</id> [The film identifier (not a file for an announcement!!!)]
<dt_modify>2010-12-24 14:35:18</dt_modify> [Date of last updating]
<name>Убить Шакала </name> [The film name]
<name_orig></name_orig> [the original name of a film (if English)]
<description>Ограблен ювелирный магазин. Объявлен всесоюзный розыск бандита по кличке Шакал. А тем временем в поезде, 
следующем из Киева в Крым, происходит загадочное убийство. Прибывший на место преступления следователь Петров обнаруживает 
связь между этим убийством и ограблением</description> [description]
<poster>/img/vod/470616.jpg</poster> [The relative reference to a poster picture. Rather http://iptv.kartina.tv/]
<year>1991</year> [Year of release of a film]
<rate_imdb>0.000</rate_imdb> [Value of rating IMDB]
<rate_kinopoisk>6.500</rate_kinopoisk> [Value of a rating of film search]
<rate_mpaa></rate_mpaa> [Value of rating MPAA]
<country>СССР</country> [The manufacture country]
<genre_str>детектив</genre_str> [Line of genres (the list of genres of a film collected at line and divided by commas)]
</item>
...
<rows>
</responce>

 

 

 

/vod_info?id=<film id>

 

To receive the full information on a film. Parameter: id - the film identifier received from the list of films.

 

 

Answer:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<film>
<id>119</id> [The film identifier]
<name>Убить Шакала </name> [The film name]
<name_orig></name_orig> [The original name of a film]
<description>Ограблен ювелирный магазин. Объявлен всесоюзный розыск бандита по кличке Шакал. А тем временем в поезде, 
следующем из Киева в Крым, происходит загадочное убийство. Прибывший на место преступления следователь Петров обнаруживает 
связь между этим убийством и ограблением</description> [The film description]
<poster>/img/vod/470616.jpg</poster> [The reference to a poster file]
<lenght>73</lenght> [Length of a film minutes]
<genre_str>детектив</genre_str> [The genres of a film divided by commas]
<year>1991</year> [Year of release]
<director>Григорий Кохан</director> [director]
<scenario>Николай Оганесов, Григорий Кохан</scenario> [scriptwriter]
<actors>Евгений Жариков, Олег Масленников, Нина Колчина-Бунь, Давид Бабаев, Римас Моркунас, Евгений Смирнов, Вячеслав Езепов, 
Бимболат Ватаев, Александр Быструшкин, Степан Олексенко</actors> [in roles]
<rate_imdb>0.000</rate_imdb> [Rating IMDB]
<rate_kinopoisk>6.500</rate_kinopoisk> [Film search rating]
<rate_mpaa></rate_mpaa> [Rating MPAA]
<country>СССР</country> [The manufacture country]
<studio></studio> [studio]
<awards></awards> [awards]
<budget>0</budget> [budget]
<images></images> [screenshot (If is)]
<videos> [Film files (series)]
<item>
<id>161</id> [The file identifier]
<title></title> [The series name. If the film one-episode, a field can be not set]
<format>dvd</format> [quality. tv|dvd|hd|fullhd|etc]
<url>KILL_JACKAL.m4v</url> [File name (the help. It is not used.)]
<size>0</size> [The size of a file]
<lenght>0</lenght> [Duration of a film in minutes]
<codec>h264</codec> [codec]
<width>0</width> [Width of a picture]
<height>0</height> [Height of a picture]
<track1_codec>aac</track1_codec> [Audio type]
<track1_lang></track1_lang> [Language sound track1]
<track2_codec></track2_codec> [The sound codec]
<track2_lang></track2_lang>
<track3_codec></track3_codec>
<track3_lang></track3_lang>
</item>
</videos>
<genres> [File of genres of a film]
<item>
<id>209</id> [The genre identifier]
<name>детектив</name> [The genre name]
</item>
</genres>
</film>
<servertime>1294761468</servertime>
</response>

 

To receive the reference for an announcement of a stream of video.

 

/vod_geturl?fileid=< File Id>

Parameter fileid - the file identifier received from /vod_info

 

Answer:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<url>http://vod.kartina.tv/Tass_02.m4v?ticket=mkcuTmdjrxyJAOE5Nb6EZNxeNin3IDojbkF0...WQlzY4CMP%2F5%2BIr8Y%3D :http-caching=1500 :no-http-reconnect</url><servertime>1294826729</servertime><BR></response>

 

Attention! The announcement reference is generated dynamically. Depending on loading on the server.

 

/vod_genres

Without parameters. Returns the list of genres.It is not recommended to do a static copy of a directory as genres can appear in process of receipt of new films.

 

 

Answer:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<genres>
<item>
<id>205</id>
<name>биографический</name>
</item>
<item>
<id>206</id>
<name>боевик</name>
</item>
<item>
<id>208</id>
<name>военный</name>
</item>
<item>
<id>209</id>
<name>детектив</name>
</item>
<item>
<id>210</id>
<name>детский</name>
</item>
<item>
<id>213</id>
<name>драма</name>
</item>
<item>
<id>215</id>
<name>исторический</name>
</item>
<item>
<id>216</id>
<name>комедия</name>
</item>
<item>
<id>219</id>
<name>криминал</name>
</item>
<item>
<id>220</id>
<name>мелодрама</name>
</item>
<item>
<id>221</id>
<name>музыка</name>
</item>
<item>
<id>222</id>
<name>музыкальный</name>
</item>
<item>
<id>224</id>
<name>приключения</name>
</item>
<item>
<id>227</id>
<name>семейный</name>
</item>
<item>
<id>230</id>
<name>триллер</name>
</item>
<item>
<id>231</id>
<name>ужасы</name>
</item>
<item>
<id>232</id>
<name>фантастика</name>
</item>
<item>
<id>234</id>
<name>фэнтези</name>
</item>
</genres>
<servertime>1294827021</servertime>
</response>

 

/vod_favlist The list of the selected favourite films [/size]

 

The answer format is identical to a list format/vod_list

 

/vod_favadd?id=<Film ID>

To add a film with the identifier id in the list of favourite films

 

/vod_favsub?id=<Film ID>

To remove a film with the identifier id from the list of favourite films

 

Additional information:

 

Codes and messages by mistakes:

define('E_UNKNOW_ERROR',        0);
define('E_INCORRECT_REQUEST',   1);
define('E_TOO_ENOUGH_DATA',     2);
define('E_ACCESS_DENIED',       3);
define('E_INCORRECT_LOGIN',     4);
define('E_CONTRACT_INACTIVE',   5);
define('E_CONTRACT_PAUSED',     6);
define('E_NOT_ALLOWED',         7);
define('E_GET_URL_INFO',        8);
define('E_NEED_DAY',            9);
define('E_NEED_CHANNEL_ID',     10);
define('E_ANOTHER_CLIENT_IN',   11);
define('E_AUTH_ERROR',          12);
define('E_PACKET_EXPIRED',      13);
define('E_INCORRECT_METHOD',    14);
define('E_ARCHIVE_NOT_AVAILABLE',    15);
define('E_NEED_PLACE',    16);
define('E_NEED_SETTING_VARIABLE',    17);
define('E_PASS_BAD_CONFIRM',    18);
define('E_CURRENT_PASS_BAD',    19);
define('E_NEW_PASS_BAD',        20);
define('E_NEED_VALUE',          21);
define('E_VALUE_NOT_ALLOWED',   22);
define('E_NEED_PARAM',              23);
define('E_NEED_PARAM_ID',           24);
define('E_NEED_PARAM_FILEID',       25);
define('E_NEED_PARAM_TYPE',         26);
define('E_NEED_PARAM_QUERY',        27);
define('E_BITRATE_NOT_AVAILABLE',   29);


define('M_FAVORITE_SETS', 2);
define('M_PASS_CHANGED', 3);
define('M_COMPLETED', 4);

E_INCORRECT_REQUEST        E_INCORRECT_REQUEST
E_TOO_ENOUGH_DATA        Wrong login or password
E_ACCESS_DENIED                 Access denied
E_INCORRECT_LOGIN        Login incorrect
E_CONTRACT_INACTIVE        You contract is inactive
E_CONTRACT_PAUSED        You contract is paused
E_NOT_ALLOWED                   Channel not found or not allowed
E_GET_URL_INFO                  Error generate URL. Bad parameters
E_NEED_DAY                      Need DAY parameter <DDMMYY>
E_NEED_CHANNEL_ID        Need ChannelID
E_ANOTHER_CLIENT_IN        Another client with you login was logged
E_AUTH_ERROR                    Authentification error
E_PACKET_EXPIRED        You packet was expired
E_UNKNOW_ERROR                  Unknown error
E_INCORRECT_METHOD        Unknown API function
E_ARCHIVE_NOT_AVAILABLE        Archive is not available
E_NEED_PLACE                    Need place to set
E_NEED_SETTING_VARIABLE        Need name of settings variable
E_PASS_BAD_CONFIRM        Incorrect confirmation code
E_CURRENT_PASS_BAD        Current code is wrond
E_NEW_PASS_BAD                  New code is wrond
E_NEED_VALUE                    Need value (val) parameter
E_VALUE_NOT_ALLOWED        This value is not allowed
E_NEED_PARAM                    Need parameter
E_NEED_PARAM_ID                    Need parameter <id>
E_NEED_PARAM_FILEID                    Need parameter <fileid>
E_NEED_PARAM_TYPE                    Need parameter <type>
E_NEED_PARAM_QUERY                    Need parameter <query>


M_FAVORITE_SETS                 Favorite channel was set
M_PASS_CHANGED                  Password was changed
M_COMPLETED                     Operation completed successfully

Link to comment
Share on other sites

  • 1 year later...
  • 1 year later...

Just a little question, could you add an extra mimetype for the m4v.low ( => video/mp4 ) files? Or simply just rename them to m4v?

I build up my own little app for KartinaTV and the .low extension makes it a little tricky. So if you could add the extra mime I would be realy thankful and would also share my app with you, just if you want.

 

greets akoww

Link to comment
Share on other sites

Guest
This topic is now closed to further replies.
 Share

  • Recently Browsing   0 members

    • No registered users viewing this page.
×
×
  • Create New...