Filmon VOD REST Api v1.0 BETA

Introduction

This guide is for developers who are integration FilmOn functionality into theirs applications by means of the FilmOn VOD API.

The FilmOn VOD API supports both RESTful / Resource oriented api calls and REST-like api with session support (see FilmOn LiveTV api for details).

You can use just any web language to access the VOD API so long as it can make HTTP requests and parse JSON responses.

This page covers following topics:

Basic Terminology

Resource requests and responses

Response status codes

Retrieve Movie Information

Retrieve Genres Information

Creating search requests to VOD Items catalog

Back to Filmon REST Api v2.2

Basic Terminology

Movie - A movie that is potentially available for instant-watch streaming

Series - Aka Serials - are series of television programs and radio programs that rely on a continuing plot that unfolds in a sequential episode-by-episode fashion

Genres - A categories of movies and series with shared characteristics.

Resource requests and responses

This section covers how to form resource requests and how to work with the resulting responses.

All Filmon VOD API requests are made by the use of an HTTP verb

- in most cases you retrieve information from FilmOn by having your client make an HTTP GET request for the URL the identifies the specific resource you are requesting. You specify any parameters for the resource using name/value pairs.

For example, to search for Sports movies in the FilmOn catalog you might form the following GET request:

http://api.filmon.com/api/vod/search?genre=sports

You can get details about a specific movie by generating GET request

http://api.filmon.com/api/vod/movie?id=1325

Session Key, Sessions and client applications authentication overview.

The FilmOn VOD API is RESTful, which means that each requests are Stateless and client request contains all of the information necessary to service the request. However if client application implementation requires some special user-oriented functionality like “watch history”, “list of favorited movies”, access to pay HD streams and so on - Client application SHOULD initiate filmon session and include appropriate session_key parameter to each API request. For details about ‘how to init session’, ‘how to retrieve session_key’ and ‘how to Log In customer’ see FilmOn LiveTV API.

To access FilmOn VOD catalog data you must have registered your application with FilmOn, which gives you the Application ID (app_id) and Application Secret (app_secret) that you use as authentication credentials.

In RESTful mode (without providing session_key) client application must add to each request it’s authentication credentials (app_id and app_secret). It’s not required in state-aware mode, since session may be initialized only with correct app_id/app_secret pairs.

Session Key, Sessions and client applications authentication overview.

The FilmOn VOD API typically return data formatted as ‘JSON’.

The API will automatically return responses compressed in gzip format if you supply Accept-Encoding: gzip HTTP header in your request.

The response you receive from successful GET request varies according to resource. You can expect different fields of information depending on which resource you requested.

All responses packed to JSON object with following fields:

{

"code": 200, // The response status code

"status": "OK", // The response reason phrase

"response": { … } // response data, varies according to resource requested.

}

Response status codes

The FilmOn VOD service return standard HTTP header information with all of its responses.

The HTTP Status-Line (containing Status code and Reason Phrase) indicates results of request processing, and also duplicated in JSON body in fields ‘code’ and ‘status’ to avoid overwriting HTTP reason-phrase by proxy/caching servers

Meaning of Status-Code usually not slightly differs from standard HTTP status codes: 3xx status codes means ‘redirect’, 4xx - client failure, 5xx - server failure, and all 2xx responses are ‘success’

Common http status codes represented in table below

Status Code

Reason Phrase

400

Bad Request

The client application send a request that server could not understand. The common reason for this is not well-formed uri parameters, http headers or missed required request parameters like movieId or searchTerm. The client application should not retry this request with same set of parameters/http headers.

403

Forbidden

Client application make request to resource which accessible only after success customer authorization (see /api/login method in FilmOn LiveTV Api)

410

Session Gone

Indicates that allocated session is no longer available and will not be available again. The client application should not make any further requests with same session_key and should instantiate new session by calling /api/init method

503

Service Unavailable (temporarily)

Service currently unable to handle the request due to temporary maintenance or overloading of the server. The client application may retry same request after some delay, which may be indicated in a Retry-After header.

Retrieve Movie Information

Use /api/vod/movie call to retrieve details for specific VOD movie.

Parameters:

id - the specific movie ID, required.

Example:

GET http://api.filmon.com/api/vod/movie?id=1325

id

The Content Item ID

title

The title of the Movie

slug

a user- and SEO-friendly short text used in a URL to identify and describe a resource. The FilmOn web URL to this content Item may be generated using this slug by following format http://www.filmon.com/vod/view/$slug

description

A summary of the movie

series_number

The Content ID of series (null for non-episode items)

episode_number

The number of episode in series. null for non-series items.

episodes_count

Count of episodes

cast

Array of actors fullnames in the cast.

crew

Hashmap of the movie crew. Format for crew item described below.

artwork

The collection of artworks for the movie, including fanart, covers of DVD cases, etc. Format for the artwork item described below

poster

The artwork item which commonly may be used by client application as poster for VOD item. Actually it’s one of artwork items from artwork[] array, extracted from artwork for easy access in movie details.

streams

array of streams for instant watching

episodes

For Series - an array of episode Ids (array of integers) containing all series episodes.

genres

array of movie genres

The raw example response:

{

"code": 200,

"status": "OK",

"response": {

"id": "1325",

"title": "Get in My Guard",

"slug": "1325-1-get-in-my-guard",

"description": "This is the T.V. show Get in my Guard by Greg Gaggenwanker.",

"type_id": "1",

"series_number": null,

"episode_number": null,

"episodes_count": "5",

"genres": [{

"genre_id": "2",

"name": "Action",

"slug": "action"

}, {

"genre_id": "20",

"name": "Sports",

"slug": "sports"

}],

"cast": [],

"crew": {

"Actor": [{

"crew_id": "52985",

"crew_type": "Actor",

"fullname": "Kelly Brook",

"person_id": "17897"

}, {

"crew_id": "52982",

"crew_type": "Actor",

"fullname": "Alki David",

"person_id": "13715"

}, {

"crew_id": "52979",

"crew_type": "Actor",

"fullname": "Felix Yanez",

"person_id": "24356"

}, {

"crew_id": "52991",

"crew_type": "Actor",

"fullname": "Amber Savva",

"person_id": "24353"

}, {

"crew_id": "52988",

"crew_type": "Actor",

"fullname": "Billy Zane",

"person_id": "17894"

}],

"Director": [{

"crew_id": "52976",

"crew_type": "Director",

"fullname": "Alki David",

"person_id": "13715"

}]

},

"artwork": {

"1619900": {

"image_id": "1619900",

"type": "front",

"width": "450",

"height": "637",

"alt": "",

"copyright": "",

"url": "http:\/\/static.filmon.com\/couch\/vod_content\/1325\/front.png",

“parent_id” : null,

"thumbs": {

"thumb_120p": {

"image_id": "2247107",

"type": "thumb_120p",

width": "120",

"height": "170",

"alt": "",

"copyright": "",

"parent_id": "1619900",

"url": "http:\/\/static.filmon.com\/couch\/vod_content\/1325\/thumb_120px.png"

},

"thumb_220p": {

"image_id": "2247110",

"type": "thumb_220p",

"width": "220",

"height": "311",

"alt": "",

"copyright": "",

"parent_id": "1619900",

"url": "http:\/\/static.filmon.com\/couch\/vod_content\/1325\/thumb_220px.png"

}

}

}

},

"poster": {

"image_id": "1619900",

"type": "front",

"width": "450",

"height": "637",

"alt": "",

"copyright": "",

"url": "http:\/\/static.filmon.com\/couch\/vod_content\/1325\/front.png",

"thumbs": {

"thumb_120p": {

"image_id": "2247107",

"type": "thumb_120p",

"width": "120",

"height": "170",

"alt": "",

"copyright": "",

"parent_id": "1619900",

"url": "http:\/\/static.filmon.com\/couch\/vod_content\/1325\/thumb_120px.png"

},

"thumb_220p": {

"image_id": "2247110",

"type": "thumb_220p",

"width": "220",

"height": "311",

"alt": "",

"copyright": "",

"parent_id": "1619900",

"url": "http:\/\/static.filmon.com\/couch\/vod_content\/1325\/thumb_220px.png"

}

}

},

"episodes": ["86363", "86360", "86357", "86354", "86351"],

}

}

The client application may also request details for set of movies. To do that client app should call /api/vod/movies?ids=[comma separated list of movie ids] method.

Example:

GET http://api.filmon.com/api/vod/movies?ids=6299,1165,112,114

Retrieve Genres Information

To create a catalog based or genre-oriented navigation client application may request a genres list from FilmOn VOD service.

Example:

http://api.filmon.com/api/vod/genres

Request does not have any parameters. Example response is following:

{

"code": 200,

"reason": "OK",

"response": [{

"id": "47",

"name": "Hotties",

"slug": "hotties",

"position": "0",

"content_count": "1993",

"description": null,

"images": [{

"url": "http:\/\/static.filmon.com\/couch\/genres\/hotties\/image.png",

"width": 148,

"height": 131,

"type": "logo"

}, {

"url": "http:\/\/static.filmon.com\/couch\/genres\/hotties\/image_retina.png",

"width": 296,

"height": 262,

"type": "logo-retina"

}]

}, {

"id": "50",

"name": "Shorts",

"slug": "shorts",

"position": "0",

"content_count": "888",

"description": null,

"images": [{

"url": "http:\/\/static.filmon.com\/couch\/genres\/shorts\/image.png",

"width": 148,

"height": 131,

"type": "logo"

}, {

"url": "http:\/\/static.filmon.com\/couch\/genres\/shorts\/image_retina.png",

"width": 296,

"height": 262,

"type": "logo-retina"

}]

}, ...

}]

}

Creating search requests to VOD Items catalog

To search for movies and series in FilmOn VOD service client application should generate GET request to /api/vod/search resource

This resource taking following parameters:

term

Set this to the word or term to search the catalog for. The FilmOn VOD API searches the title and synopses of catalog titles for a match. This parameter is required.

start_index

Set this to a zero-based offset into the list that results from the query. By using this with the max_results parameter, you can request successive pages of search results.

max_results

Set this to the maximum number of results to return. This number cannot be greater than 100. If you do not specify max_results, the default value is 25.

The following optional parameters also may be used:

parent_id

search for episodes of specified series.

order_by

Order search results by one of following strategies:

- relevance

- date

content_type

Filter and return search results only for specified content_type. Parameter value should be one of :

- relevance

- date

genre

Filter and search for movies only in specified genre. Parameter value should be a slug of corresponding genre, retrieved from /api/vod/genres resource.

Example request:

GET http://api.filmon.com/api/vod/search?term=Bruce&max_results=2&start_index=30&genre=action

{

"code": "200",

"reason": "ok",

"response": [{

"id": "236522",

"title": "The Legend Of Bruce Lee E18",

"slug": "236522-0-the-legend-of-bruce-lee-e18",

"description": "30 hours series of The Legend of Bruce Lee. Original Chinese language dubbed in English. Produced by Shannon Lee daughter of Bruce Lee.\r\nExclusive for FilmOn.TV",

"type_id": "0",

"series_number": null,

"episode_number": null,

"episodes_count": "0",

"parent_id": "2273",

"genres": [{

"genre_id": "2",

"name": "Action",

"slug": "action"

}],

"poster": {

"image_id": "1753574",

"type": "front",

"width": "450",

"height": "637",

"alt": "",

"copyright": "",

"parent_id": null,

"url": "http:\/\/static.filmon.com\/couch\/vod_content\/236522\/front.png",

"thumbs": {

"thumb_120p": {

"image_id": "2291219",

"type": "thumb_120p",

"width": "120",

"height": "170",

"alt": "",

"copyright": "",

"parent_id": "1753574",

"url": "http:\/\/static.filmon.com\/couch\/vod_content\/236522\/thumb_120px.png"

},

"thumb_220p": {

"image_id": "2291222",

"type": "thumb_220p",

"width": "220",

"height": "311",

"alt": "",

"copyright": "",

"parent_id": "1753574",

"url": "http:\/\/static.filmon.com\/couch\/vod_content\/236522\/thumb_220px.png"

}

}

},

"streams": {

"low": {

"quality": "low",

"url": "rtmp:\/\/flash-cloud.filmon.com\/demand\/storage\/226\/109987\/377935",

"name": "377935.mp4",

"watch-timeout": 172800

},

"high": {

"quality": "high",

"url": "rtmp:\/\/flash-cloud.filmon.com\/demand\/storage\/226\/109987\/377934",

"name": "377934.mp4",

"watch-timeout": 172800

}

}

}, {

"id": "236525",

"title": "The Legend Of Bruce Lee E20",

"slug": "236525-0-the-legend-of-bruce-lee-e20",

"description": "30 hours series of The Legend of Bruce Lee. Original Chinese language dubbed in English. Produced by Shannon Lee daughter of Bruce Lee.\r\nExclusive for FilmOn.TV",

"type_id": "0",

"series_number": null,

"episode_number": null,

"episodes_count": "0",

"parent_id": "2273",

"genres": [{

"genre_id": "2",

"name": "Action",

"slug": "action"

}],

"poster": {

"image_id": "1753592",

"type": "front",

"width": "450",

"height": "637",

"alt": "",

"copyright": "",

"parent_id": null,

"url": "http:\/\/static.filmon.com\/couch\/vod_content\/236525\/front.png",

"thumbs": {

"thumb_120p": {

"image_id": "2291231",

"type": "thumb_120p",

"width": "120",

"height": "170",

"alt": "",

"copyright": "",

"parent_id": "1753592",

"url": "http:\/\/static.filmon.com\/couch\/vod_content\/236525\/thumb_120px.png"

},

"thumb_220p": {

"image_id": "2291234",

"type": "thumb_220p",

"width": "220",

"height": "311",

"alt": "",

"copyright": "",

"is_synchronized": "1",

"url": "http:\/\/static.filmon.com\/couch\/vod_content\/236525\/thumb_220px.png"

}

}

},

"streams": {

"low": {

"quality": "low",

"url": "rtmp:\/\/flash-cloud.filmon.com\/demand\/storage\/226\/109989\/377933",

"name": "377933.mp4",

"watch-timeout": 172800

},

"high": {

"quality": "high",

"url": "rtmp:\/\/flash-cloud.filmon.com\/demand\/storage\/226\/109989\/377936",

"name": "377936.mp4",

"watch-timeout": 172800

}

}

}],

"total": 2,

"total_found": 47

}