Table of Contents

TVIP JSON Middleware API v2

Basic request format

For most requests HTTP GET is used: 

 GET ${TVIPAPI_BASE_URL}/tvipapi/json/<command>.json

For some requests HTTP POST is used: 

 POST ${TVIPAPI_BASE_URL}/tvipapi/json/<command>.json

tvipapi/json subfolder allows implementing API inside of existing web site (not dedicated domain).

Here: ${TVIPAPI_BASE_URL} is HTTP/HTTPS base URL of Middleware server. For example, http://server.com/iptv/.
<command> is an API command.

All responses have general form: 

{
  "method" : "methodname",
  "status" : 0,
  "text" : "Status text",
  "response" :
    {
    }
}

Client should first check that method name equals original requested method.
Then client should check status integer value for error code.
If status==0 || status==200 (no error), client can parse response object for the requested data.
If status>0, error text could be provided.

Code Commands Description
0/200 All Request success. No errors
400 All Wrong request syntax.
404 All Method is not supported or data not available (for EPG).
403 All, ex serverinfo,auth,register Authentication required. Client should call auth command to require authentication.
401 auth Registration required. Client should call register with appropriate credential information.
402 auth This device is blocked. Client can periodically call auth, to wait until blocking is over.
401 register Incorrect credentials. User supplied wrong login/password, MAC address or other information.
403 register Can not register this STB. User message is provided.
500 All Other server-side errors

To simplify “static” server implementations, content requests can response with HTTP error codes, instead of JSON errors.
server_info command should not response with HTTP error codes as it will be treated as protocol error.

HTTP code Commands
403 All, except serverinfo,auth,register
404 All

All other API requests should respond HTTP/200, even on error. Error code should be provided in “status” field of JSON responce object!

Request HTTP Headers

Header Description
User-Agent Standard web client identifier.
Mac-Address Unique MAC address of client.
Accept-Language Language code of client's user interface (for ex. “en”).
Device-Type Client device type (model) name.
Device-Firmware Device specific firmware version.
Device-Os Device specific Operating system name.
Udpxy-Address Address of UDP-proxy if any.
Device-Use-Nat If device can detect NAT state, this header has value “yes” or “no”. Otherwise, header is not present.



Server Info

Server information request. This request is peformed by client on protocol initializtion.
If a server fails to provide Server Info data, client will not access any server features.

Request: 

GET ${TVIPAPI_BASE_URL}/tvipapi/json/server_info.json

Response: 

{
  "method" : "server_info",
  "status" : 0,
  "response" :
    {
      "proto_version": 2,
      "server": "middleware_server",
      "service_provider":"MegaGiga",
      "server_time": 1234567946,
      "remote_addr": "192.168.10.5",
      "tz_offset": 10800,
      "auth":true,
      "channel_list_update_interval":3600,
      "poll": {
          "interval": 300,
          "timeslot": 0.1,
      }, 
      "cas_configs": [
         {
           "id": 1,
           "type": "tvipcas",
           "options" : {
             "key": "value",
           }
         }
      ]
    }
}
Option Type Req.Description Def.val
proto_version Integer Yes Protocol version, implemented by the server. Client should check that protocol version is not higher then supported.
server String No Identification string of middleware server. undef.
service_provider String No Name of Service provider to display to user. undef.
server_time Integer No Server's current time. STB could sync with it. undef.
remote_addr String No Client's IP address as seen by the server. Used to detect NAT. undef.
tz_offset Integer No Server's current time offset from GMT in seconds. 0
auth Bool No Whether “auth.json” call is required before accessing middleware. false
cas_configs Array No CAS/DRM protocols, that should be initialized for this middleware with specific options options. undef.
channel_list_update_interval Integer No Interval in seconds to check server for channel list (or EPG) updates. If not set, client default value is used. 86400
poll/interval Integer No Interval in seconds to poll server for incoming messages. If not set, message system is disabled. undef.
poll/timeslot Float No Timeslot inside poll interval (see messages). undef.

Authentication

If authentication is enabled by server info, client should authenticate on the server. It should provide any tokens/cookies, that it currently has in this request.

Request: 

GET ${TVIPAPI_BASE_URL}/tvipapi/json/auth.json

Response: 

{
  "method" : "auth",
  "status" : 0,
  "response" :
    {
      "registered" : true,
      "register_type": "login",
      "session_type": "token",
      "token": "AAAAAAAA",
      "header": "Auth-Data",
      "param": "session"
    }
}

Server should not response with HTTP 403, even if auth failed.

Server should always have response block with register_type option.

registered reports current register status of client. If true - client device was already registered on the server; false - device can be registered, if register_type is defined.

register_type defines type of user authentication logic, implemented by the server. Possible values are:
mac - server uses only MAC address of the device to authenticate it. No Login/Password is used.
login - user should provide login and password to register the device.

session_type defines which kind of session information server will provide to client in order to keep it's registered session. Each successful auth request should correctly update session information (i.e. provide the same or different token). Possible values are:
mac - no token is used. Client just sends it's MAC address in *Mac-Address* HTTP header.
token - a simple string token is provided in the token field of the response. Client Should use HTTP Header “Auth-Token” in each content request too keep session.
cookie - client will keep cookies provided in the current response and apply them to any content request.
header - client will keep the value of token and provide it as custom HTTP-header header.
param - client will keep the value of token attribute and will provide it as GET param on each content request.

Registration

If authentication was failed, STB should call Register command, providing credentials according to the register_type (see auth command). Also, all session data, that client may have, should be provided to the call.
If register type is mac, client can immidiately call register command after failed auth.
If register type is login, client should display a message to user with login and password fields. Then call register method. 

{
  "login": "login_name",
  "password": "passssss"
}

Request: 

GET/POST ${TVIPAPI_BASE_URL}/tvipapi/json/register.json

Response: 

{
  "method" : "register",
  "status" : 0,
  "response" : {
      "token": "xxxxxxxxxxxxxxxxxx"
 
  }
}

If registration is OK, no additional data is provided. Client can repeat auth command.

Cancel registration

User can try to unregister device. Session information should be provided.

Request: 

GET ${TVIPAPI_BASE_URL}/tvipapi/json/unregister.json

Response: 

{
  "method" : "unregister",
  "status" : 0,
  "response" : null
}

If unregister is OK (or user is not registered), no additional data is provided. Client can repeat auth command.

User info

Get information about registred user.

Request: 

GET ${TVIPAPI_BASE_URL}/tvipapi/json/user_info.json

Response: 

{
  "method" : "user_info",
  "status" : 0,
  "response" : {  
      "fullname":"Ivan Smith",
      "enabled":true,
      "contract":"13279 от: 23.06.2014"
   }
}

User structure:

Field: Type Req. Description
fullname String Yes User fullname.
enabled Boolean Yes True if subscribrictions are active.
contract String No Contract information



Content requests

The following commands should only be called by client after successfull authentication.

Channel List

This command loads channel list from the server. Channel list is always loaded full (all channels).

Request: 

GET ${TVIPAPI_BASE_URL}/tvipapi/json/channels.json

Response: 

{
	"method": "channels",
	"status": 0,
	"response": {
                "channels_version" : 1,
                "channels_hash": "d41d8cd98f00b204e9800998ecf8427e",
                "epg_version": 1,
		"channels": [{
			"id": 1,
			"title": "ОРТ",
			"number": 666,
			"logo": "http://megaprov.ru/images/logos/ort1.png",
			"url": "udp://@1.1.1.1:1234",
			"age_group_id": 1,
 
		        "tshift_proto":"flussonic",
			"tshift_depth": 3586954,
                        "tshift_base_url": "http://2.2.2.2:4321",
			"tshift_cas_config_id": null,
 
                        "media": {
                          "aspect": "4:3",
                        },
 
			"cas_config_id": null
		}],
 
		"groups": [
		  {
			"id": 1,
			"title": "ProPutina",
			"items": [1, 2, 3, 4]
		  }
		],
		"age_groups":[
		   {
		       "id":1,
                       "age":18,
                       "caption":"18+"
 
		   }
		]
	}
}

channels_version defines version or timestamp of current channel list. If this value is the same as on previous request, playlist will not be updated on the device.
channels_hash unique hash of available channels, used in short epg
epg_version defines version or timestamp or current EPG data. If this value is the same as on previous request, EPG will be considered the same.

Channel structure:

Field: Type Req. Description
id Integer Yes Unique id of the channel in the middleware.
title String Yes Name of the channel to be displayed to the end user. Should be localized.
number Integer Yes Unique channel number, that is displayed to user and used to switch channels.
logo String No URL of an image file (PNG), that represents channel logo.If path contains ${h} and ${w} variables client can replace these variables with required height and width in pixels.
url String Yes URL of the Live stream.
age_group_id Int Yes Age group ID, may be null
tshift_proto String No Timeshift server type. Auto detect by default.
tshift_base_url String No Base URL of timeshifted stream. Syntax depends on timeshift type.
tshift_depth Integer No Enables server achive/timeshift for the channel and sets number of seconds back from live.
tshift_cas_config_id String No CAS/DRM config id, that should be used to play timeshifted stream.
cas_config_id Integer or null No CAS/DRM config id, that should be used to play this stream.
media Object No Various media options for the stream (aspect, def. audio track, def. subtitle, etc.

Age group structure:

Field: Type Req. Description
id Integer Yes Id
age Integer Yes Age rating
caption String Yes Age rating caption

Media structure:

Field: Type Req. Description
aspect String No Override aspect ratio (allowed values: “4:3”, “16:9”, “16:10”, may be null (no override)


TODO: Some MWs support dynamic links. So, real URL should be async requested by the Player at the moment that user changes channel.

EPG Download

EPG is supposed to be segmented as one file per one day per channel. Day is supposed to be an inteval from 00:00 to 23:59:59 UTC time (*not* local time). The *start* time of event is used. 

GET ${TVIPAPI_BASE_URL}/tvipapi/json/epg/<channel_id>/YYYY-MM-DD.json

Here, channel_id is supposed to be the id of channel from the playlist.
YYYY-MM-DD is the date of the requested day (like 2015-01-25). Day borders (begin-end) are defined by server's timezone specified by tz_offset in server info.

Response: 

{
  "method" : "epg",
  "status" : 0,
  "response" :
     {
        "version": 2,
        "channel_id" : 1,
        "date" : "2015-01-25",
        "events" : [
          {
            "start": 1447285765,
            "end" : 1447256765,
            "title" : "News",
            "description:" "Today's news program.",
            "age_group_id": 1,
          }
        ],
        "age_groups":[
          {
             "id":1,
             "age":18,
             "caption":"18+"
          }
	]
     }
}

Event structure:

Field: Type Req. Description
version Integer Yes Version of EPG. Should be changed each time EPG database is updated on server.
channel_id Integer Yes Id of the channel for which EPG is provided.
date String Yes Date of the current EPG block 2015-01-25. Borders (00:00:00 - 23:59:59 should be in UTC timezone).
start Integer Yes Unix timestamp of program start. It should be within borders of the date.
end Integer Yes Unix timestamp of the program end. it should be equal or later then start. And no later, then start of the next program.
title String Yes Title of the programm.
description String No Description of the program.
age_group_id Integer Yes Override channel age_group option, must be null if override not needed

Short EPG Download

GET ${TVIPAPI_BASE_URL}/tvipapi/json/short_epg/<hash>.json

Here, hash is channel hash.

Filter short EPG by channel: 

GET ${TVIPAPI_BASE_URL}/tvipapi/json/short_epg/<channel>/epg.json

Here, channel is supposed to be the id of channel from the playlist.

Response: 

{
   "method":"short_epg",
   "status":200,
   "text":null,
   "response":{
      "version":"70",
      "channels":[
         {
            "channel_id":3,
            "events":[
               {
                  "start":1463131800,
                  "end":1463134800,
                  "title":"News",
                  "description":"",
                  "age_group_id":1
               },
               {
                  "start":1463134800,
                  "end":1463138100,
                  "title":"Politics",
                  "description":"",
                  "age_group_id":1
               },
               {
                  "start":1463138100,
                  "end":1463143500,
                  "title":"Just another soap",
                  "description":"",
                  "age_group_id":null
               }
            ]
         }
      ],
      "age_groups":[
         {
            "id":1,
            "age":18,
            "caption":"18+"
         }
      ]
   }
}

version - EPG version

channels structure

Field: Type Req. Description
channel_id Integer Yes Channel id
events Array Yes EPG event objects

Messages

Client polls server periodically according to poll settings for incoming messages.
Each client uses its own timeslot to poll server for messages. Each day (starting from UTC 00:00) is splitted into poll intervals.
ceil( ( current_unixtime - (floor(current_unixtime / 86400) * 86400) - floor(poll_timeslot * poll_interval) ) / poll_interval ) * poll_interval + (floor(current_unixtime / 86400) * 86400) + floor(poll_timeslot * poll_interval)

Request: 

GET/POST ${TVIPAPI_BASE_URL}/tvipapi/json/messages.json

GET is for message polling (receiving). POST is pushing message (sending).\\

POST request example: 

{
  "messages": [
    {
      "id": 1,
      "command": "channel_view_stat",
      "args": {
        "channel_id": 1,
        "content_begin": 111111111,
        "content_end": 22222222,
        "session_begin": 111110000,
        "session_end": 222220000
      }
    }
  ]
}

POST server response example: 

{
  "method" : "messages",
  "status" : 0,
}

GET server response example: 

{
  "method" : "messages",
  "status" : 0,
  "response" :
     {
        "poll": {
          "interval": 300,
          "timeslot": 0.1,
        }, 
        "messages": [
          {
            "id" : 1,
            "command": "command_name",
            "ttl": 1447285765,
            "args": {
              "arg1": "test1",
              "arg2": "test2"
            }
 
          },
 
        ]
     }
}
Field: Type Req. Description Default
id Int64 Yes Unique message ID on the server
command String Yes Command code name, see table of supported commands below.
ttl Integer No Unix timestamp of time, until which this message is valid. If 0, then valid forever.
confirm Boolean No True if message needs confirmation over message_confirm command.
args Object No Arguments, depending on executed command.
poll/interval Integer No Interval in seconds to poll server for incoming messages. If not set, message system is disabled. undef.
poll/timeslot Float No Timeslot inside poll interval (see messages). undef.

Supported message types:

Message Type Source Description
user_message server Display text messages to user screen, available types: notify, confirm.
reinit server Ask client to refresh server_info.
refresh_channel_list server Telling device to update channel list.
restart server Depending on the platform restarts app or OS.
open_url server Display data from given url to user screen.
force_update server Telling device to update app/firmware.
send_crash_report server Telling device to send crash reports to provider.
channel_view_stat client Send channel view statistics to server.
channel_quality_stat client Send stream view statistics to server.

User messages

Alert type Description
confirm Text window with confirm button.
Device freezes waiting for user response
notify Simple text notification. No user reaction expected.
Time of presentation controls with “ttl” argument
ticker Ticker string that rolling over the screen
Json structure:
Field Type Req. Description
type Enum Yes Available types: confirm, notify, ticker
title String No Title for confirm type
text String Yes Message text
delay Integer No Message exposure time

Statistics

Channel view statistics:

Field Type Req. Description
channel_id Integer Yes Viewed channel id.
content_begin Integer Yes Timestamp, when content was started.
content_end Integer Yes Timestamp, when content was ended.
session_begin Integer Yes Timestamp, when playback session was started.
session_end Integer Yes Timestamp, when playback session was ended.

VoD

Tag list

Tag list usually used for filling main screen layout

This command loads vod tags for requested places. Now boxies load only 'primary' tag list.

Request: 

GET ${TVIPAPI_BASE_URL}/tvipapi/json/vod/tag_list/{name}.json

Response: 

{  
   "method":"tag_list",
   "status":200,
   "text":null,
   "response":{  
      "name":"primary",
      "tags":[  
         {  
            "id":34,
            "title":"Комедия"
         },
         {  
            "id":31,
            "title":"Криминал"
         },
         {  
            "id":30,
            "title":"Драма"
         },
         {  
            "id":32,
            "title":"Фэнтези"
         },
         {  
            "id":33,
            "title":"Детектив"
         },
         {  
            "id":35,
            "title":"Биография"
         },
         {  
            "id":36,
            "title":"История"
         },
         {  
            "id":37,
            "title":"Фантастика"
         },
         {  
            "id":38,
            "title":"Боевик"
         },
         {  
            "id":39,
            "title":"Триллер"
         },
         {  
            "id":40,
            "title":"Мультфильм"
         },
         {  
            "id":41,
            "title":"Мюзикл"
         },
         {  
            "id":42,
            "title":"Приключения"
         },
         {  
            "id":43,
            "title":"Семейный"
         }
      ]
   }
}

Category list

Category list usually used for filling main screen layout

This command loads vod сategories for requested places. Now boxies load only 'primary' list.

Request: 

GET ${TVIPAPI_BASE_URL}/tvipapi/json/vod/category_list/{name}.json

Response: 

{  
   "method":"category_list",
   "status":200,
   "text":null,
   "response":{  
      "categories":[  
         {  
            "id": 1,
            "name": "Fantasy",
            "logo": "http://localhost/tvipapi/png/141766/logo.jpg/%24%7Bw%7D/%24%7Bh%7D/%24%7Bmode%7D",
            "tags": [1,2,3,4,10,12]
         },
         {  
            "id": 2,
            "name": "Cartoons",
            "logo": "http://localhost/tvipapi/png/57612/logo.jpg/%24%7Bw%7D/%24%7Bh%7D/%24%7Bmode%7D",
            "tags": [1,2,3]
         }
      ]
   }
}

Content list

Request parameters:
Field Type Req. Description
tags Int[] No Array of tags id's, must be presended by comma delimited list, like a &tags=1,2,3
categories Int[] No Array of categories id's, must be presended by comma delimited list, like a &categories=1,2,3
search String No Search by title or original title
start Int No Start from record (default value: 0)
limit Int No Limits records on output (default value: 10)

Request: 

GET ${TVIPAPI_BASE_URL}/tvipapi/json/vod/content_list.json?tags={tags_array}&categories={categories_array}&search={text}&start={start}&limit={limit}

Response: 

{  
   "method":"content_list",
   "status":200,
   "text":null,
   "response":{  
      "start":0,
      "limit":10,
      "count":11,
      "search":null,
      "search_tags":[  
 
      ],
      "tags":[  
         {  
            "id":35,
            "title":"Биография"
         },
         {  
            "id":36,
            "title":"История"
         },
         {  
            "id":37,
            "title":"Фантастика"
         },
         {  
            "id":38,
            "title":"Боевик"
         },
         {  
            "id":39,
            "title":"Триллер"
         },
         {  
            "id":40,
            "title":"Мультфильм"
         },
         {  
            "id":41,
            "title":"Мюзикл"
         },
         {  
            "id":42,
            "title":"Приключения"
         },
         {  
            "id":43,
            "title":"Семейный"
         },
         {  
            "id":33,
            "title":"Детектив"
         },
         {  
            "id":32,
            "title":"Фэнтези"
         },
         {  
            "id":34,
            "title":"Комедия"
         },
         {  
            "id":31,
            "title":"Криминал"
         },
         {  
            "id":30,
            "title":"Драма"
         }
      ],
      "categories":[  
          {  
            "id": 1,
            "name": "Fantasy",
            "logo": "http://localhost/tvipapi/png/141766/logo.jpg/%24%7Bw%7D/%24%7Bh%7D/%24%7Bmode%7D",
            "tags": [1,2,3,4,10,12]
         },
         {  
            "id": 2,
            "name": "Cartoons",
            "logo": "http://localhost/tvipapi/png/57612/logo.jpg/%24%7Bw%7D/%24%7Bh%7D/%24%7Bmode%7D",
            "tags": [1,2,3]
         }
      ],
      "age_groups":[  
         {  
            "id":1,
            "age":18,
            "caption":"18+"
         },
         {  
            "id":2,
            "age":16,
            "caption":"16+"
         },
         {  
            "id":3,
            "age":12,
            "caption":"12+"
         },
         {  
            "id":4,
            "age":6,
            "caption":"6+"
         },
         {  
            "id":5,
            "age":3,
            "caption":"3+"
         },
         {  
            "id":6,
            "age":0,
            "caption":"0+"
         },
         {  
            "id":7,
            "age":21,
            "caption":"21+"
         }
      ],
      "content":[  
         {  
            "id":102,
            "title":"Побег из Шоушенка",
            "poster_path":"http://10.170.253.207/tvipapi/jpg/429/poster.jpg/236/340/match",
            "view_mode": 1
         },
         {  
            "id":103,
            "title":"Зеленая миля",
            "poster_path":"http://10.170.253.207/tvipapi/jpg/430/poster.jpg/236/340/match",
            "view_mode": 1
         },
         {  
            "id":105,
            "title":"Список Шиндлера",
            "poster_path":"http://10.170.253.207/tvipapi/jpg/432/poster.jpg/236/340/match",
            "view_mode": 1
         },
         {  
            "id":106,
            "title":"1+1",
            "poster_path":"http://10.170.253.207/tvipapi/jpg/433/poster.jpg/236/340/match",
            "view_mode": 1
         },
         {  
            "id":107,
            "title":"Начало",
            "poster_path":"http://10.170.253.207/tvipapi/jpg/434/poster.jpg/236/340/match",
            "view_mode": 1
         },
         {  
            "id":108,
            "title":"Король Лев",
            "poster_path":"http://10.170.253.207/tvipapi/jpg/435/poster.jpg/236/340/match",
            "view_mode": 1
         },
         {  
            "id":109,
            "title":"Леон",
            "poster_path":"http://10.170.253.207/tvipapi/jpg/436/poster.jpg/236/340/match",
            "view_mode": 1
         },
         {  
            "id":110,
            "title":"Бойцовский клуб",
            "poster_path":"http://10.170.253.207/tvipapi/jpg/437/poster.jpg/236/340/match",
            "view_mode": 1
         },
         {  
            "id":111,
            "title":"Автостопом по галактике",
            "poster_path":"http://10.170.253.207/tvipapi/jpg/438/poster.jpg/236/340/match",
            "view_mode": 1
         },
         {  
            "id":112,
            "title":"Теория большого взрыва (сериал 2007 – ...)",
            "poster_path":"http://10.170.253.207/tvipapi/jpg/439/poster.jpg/236/340/match",
            "view_mode": 1
         }
      ]
   }
}
Content object structure
Field Type Req. Description
id int yes Content id
title String yes Content title
poster_path String No Path pattern to poster as described here.
view_mode int yes Option render content: 1 - with a poster and 2 without a poster. Only for series

Content detail

Request: 

GET ${TVIPAPI_BASE_URL}/tvipapi/json/vod/content/{id}.json

Response: 

{  
   "method":"content",
   "status":200,
   "text":null,
   "response":{  
      "content":{  
         "id":112,
         "title":"Теория большого взрыва",
         "poster_path":"http://localhost/tvipapi/jpg/439/poster.jpg/236/340/match",
         "view_mode": 1,
         "original_title":"The Big Bang Theory",
         "year":2007,
         "description":"Два блестящих физика, Леонард и Шелдон, «великие умы», которые понимают, как «работает Вселенная». Но их гениальность ничуть не помогает им общаться с людьми, особенно с женщинами. Всё начинает меняться, когда напротив них поселяется красавица Пенни. Когда Леонард и Шелдон встречают Пенни, Леонард сразу же начинает интересоваться ею. Он видит в общении с Пенни огромную перспективу, вплоть до любви, однако Шелдон понимает, что мечтам его друга не суждено сбыться. Стоит также отметить пару странных друзей этих физиков: Воловиц, который любит употреблять фразы на разных языках, включая русский, и Раджеш Кутрапали, теряющий дар речи при виде женщин.",
         "duration_min":22,
         "age_group_id":2,
         "categories":[
            1
         ],
         "tags_id":[  
            34
         ],
         "items":[  
            {  
               "id":16,
               "title":"Трейлер (HD)",
               "url":"https://kp.cdn.yandex.net/306084/kinopoisk.ru-Big-Bang-Theory-The-144199.mp4",
               "type_id":1
            },
            {  
               "id":17,
               "title":"Трейлер (SD)",
               "url":"https://kp.cdn.yandex.net/306084/kinopoisk.ru-Big-Bang-Theory-The-144198.flv",
               "type_id":2
            }
         ],
         "team":[  
            {  
               "person_id":20,
               "fullname":"Джим Парсонс",
               "title":"Actor"
            },
            {  
               "person_id":21,
               "fullname":"Джонни Галэки",
               "title":"Actor"
            },
            {  
               "person_id":22,
               "fullname":"Кейли Куоко",
               "title":"Actor"
            },
            {  
               "person_id":23,
               "fullname":"Саймон Хелберг",
               "title":"Actor"
            },
            {  
               "person_id":24,
               "fullname":"Кунал Нэйэр",
               "title":"Actor"
            },
            {  
               "person_id":25,
               "fullname":"Мелисса Рауш",
               "title":"Actor"
            },
            {  
               "person_id":26,
               "fullname":"Майем Биалик",
               "title":"Actor"
            },
            {  
               "person_id":27,
               "fullname":"Кевин Сасмэн",
               "title":"Actor"
            },
            {  
               "person_id":28,
               "fullname":"Кэрол Энн Сьюзи",
               "title":"Actor"
            },
            {  
               "person_id":29,
               "fullname":"Джон Росс Боуи",
               "title":"Actor"
            },
            {  
               "person_id":17,
               "fullname":"Марк Сендроуски",
               "title":"Director"
            },
            {  
               "person_id":18,
               "fullname":"Энтони Джозеф Рич",
               "title":"Director"
            },
            {  
               "person_id":19,
               "fullname":"Питер Чакос",
               "title":"Director"
            },
            {  
               "person_id":32,
               "fullname":"Чак Лорри",
               "title":"Producer"
            },
            {  
               "person_id":33,
               "fullname":"Билл Прэди",
               "title":"Producer"
            },
            {  
               "person_id":34,
               "fullname":"Стивен Моларо",
               "title":"Producer"
            },
            {  
               "person_id":32,
               "fullname":"Чак Лорри",
               "title":"Script"
            },
            {  
               "person_id":33,
               "fullname":"Билл Прэди",
               "title":"Script"
            },
            {  
               "person_id":34,
               "fullname":"Стивен Моларо",
               "title":"Script"
            }
         ],
         "children":[  
            {  
               "id":6,
               "title":"8 сезон",
               "items":[  
 
               ],
               "children":[  
                  {  
                     "id":9,
                     "title":"24 серия",
                     "items":[  
                        {  
                           "id":15,
                           "title":"Смотреть (SD)",
                           "url":"http://ov.tvip.ru:8080/films/sd/Big%20Bang%208/The.Big.Bang.Theory.S08E24.Kuraj-Bambey.%5bqqss44%5d.avi",
                           "type_id":2
                        }
                     ],
                     "children":[  
 
                     ]
                  },
                  {  
                     "id":8,
                     "title":"23 серия",
                     "items":[  
                        {  
                           "id":14,
                           "title":"Смотреть (SD)",
                           "url":"http://ov.tvip.ru:8080/films/sd/Big%20Bang%208/The.Big.Bang.Theory.S08E23.Kuraj-Bambey.%5bqqss44%5d.avi",
                           "type_id":2
                        }
                     ],
                     "children":[  
 
                     ]
                  },
                  {  
                     "id":7,
                     "title":"21 серия",
                     "items":[  
                        {  
                           "id":13,
                           "title":"Смотреть (SD)",
                           "url":"http://ov.tvip.ru:8080/films/sd/Big%20Bang%208/The.Big.Bang.Theory.S08E21.Kuraj-Bambey.%5bqqss44%5d.avi",
                           "type_id":2
                        }
                     ],
                     "children":[  
 
                     ]
                  }
               ]
            },
            {  
               "id":7,
               "title":"21 серия",
               "items":[  
                  {  
                     "id":13,
                     "title":"Смотреть (SD)",
                     "url":"http://ov.tvip.ru:8080/films/sd/Big%20Bang%208/The.Big.Bang.Theory.S08E21.Kuraj-Bambey.%5bqqss44%5d.avi",
                     "type_id":2
                  }
               ],
               "children":[  
 
               ]
            },
            {  
               "id":8,
               "title":"23 серия",
               "items":[  
                  {  
                     "id":14,
                     "title":"Смотреть (SD)",
                     "url":"http://ov.tvip.ru:8080/films/sd/Big%20Bang%208/The.Big.Bang.Theory.S08E23.Kuraj-Bambey.%5bqqss44%5d.avi",
                     "type_id":2
                  }
               ],
               "children":[  
 
               ]
            },
            {  
               "id":9,
               "title":"24 серия",
               "items":[  
                  {  
                     "id":15,
                     "title":"Смотреть (SD)",
                     "url":"http://ov.tvip.ru:8080/films/sd/Big%20Bang%208/The.Big.Bang.Theory.S08E24.Kuraj-Bambey.%5bqqss44%5d.avi",
                     "type_id":2
                  }
               ],
               "children":[  
 
               ]
            }
         ]
      },
      "age_groups":[  
         {  
            "id":1,
            "age":18,
            "caption":"18+"
         },
         {  
            "id":2,
            "age":16,
            "caption":"16+"
         },
         {  
            "id":3,
            "age":12,
            "caption":"12+"
         },
         {  
            "id":4,
            "age":6,
            "caption":"6+"
         },
         {  
            "id":5,
            "age":3,
            "caption":"3+"
         },
         {  
            "id":6,
            "age":0,
            "caption":"0+"
         },
         {  
            "id":7,
            "age":21,
            "caption":"21+"
         }
      ]
   }
}
Detail content object structure
Field Type Req. Description
id int yes Content id
title String yes Content title
poster_path String No Path pattern to poster as described here.
description String No Content description
original_title String No Title at native language
duration_min int No Duration in minutes
year int No Year of release
age_group_id int No Link to age group object
category_id int No Link to age category object
children Object[] No Array of Child Object
tags_id array No Array of links to tag object
items Object[] No Array of Item Object
team Object[] No Array of person object
view_mode int Yes Option render content: 1 - with a poster and 2 without a poster. Only for series
Child object structure
Field Type Req. Description
id int yes Child id
title String yes Child title
items Object[] No Array of Item Object
children Object[] No Array of Child Object
Item object structure
Field Type Req. Description
id int yes Child id
title String yes Item title
url String yes Url to media
type_id int yes Type of media (HD,SD,…)
Person object structure
Field Type Req. Description
person_id Int yes Person id
fullname String yes Person fullname
title String yes Person title (like “Actor”, “Director”)

Getting the image by reference

This loads the image processed with parameters specified by unique id.

Prerequisites

The URL pattern will be received from the another request.

Usage

URL pattern contains some templates that may be replaced with appropriate values. These values may be found from the table below.

Request pattern:
GET ${TVIPAPI_BASE_URL}/tvipapi/{fileType}/{id}/{fileName}/{w}/{h}/{mode}
Template Type Description
{fileType} String Defines the mime type of image required. Now supported values are “png”, “jpeg”, “jpg”. This parameter is optional and may be considered if the image type conversion specified makes sense. If not replaced, “png” value is used as default.
{id} Integer Defines unique id of image. It's defined by the server, so no need to worry about it.
{fileName} String Defines the desired file name. It's defined by the server depending upon what is image required for. Actual file descriptor of the image file depends on the client requested the image.
{w} Integer Positive integer value of the width desired. If not replaced or invalid, the original width dimension will be used.
{h} Integer Positive integer value of the height desired. If not replaced or invalid, the original height dimension will be used.
{mode} String Optional parameter. Specifies what resize mode will be used, if desired dimensions are not matched with original ones. Possible values may be found from the table below. If not replaced, “crop” mode will be used as default, “match” - for VOD posters, “padding” - for channel logo. If unknown mode specified, default mode “keep” will be used.
Image processing modes
Name Maintaining aspect ratio Must match the dimensions requested Description
match No Yes Default mode. Returns the entire image, but may be looking not so good, if the desired dimensions do not provide the same aspect ratio as original image ones.
crop Yes Yes Performs zoom operation on the image. Returns as much of original image as possible, but some areas may be cropped, if the aspect ratio does not match.
padding Yes Yes Returns the entire image, but may contain some background padding around in order to match the dimensions requested, if the aspect ratio does not match.
keep Yes No Returns the entire image, but its dimensions may differ from the requested ones in order to maintain the aspect ratio if not matched.
top Yes Yes Performs aligning the image on the top edge, matching the original image width. If necessary, the image will be cropped or padded to match the dimensions requested.
Example of prepared request URL:
http://10.170.253.203:8080/tvipapi/png/289/logo.png/64/64/padding
Response:
200 OK returns image as byte array.
404 Not Found image not found.
500 Internal Server Error image processing error.