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:
Resource requests and responses
Creating search requests to VOD Items catalog
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
}
