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. }
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.
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
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" }] }, ... }] } 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 }Response status codes
Retrieve Movie Information
Retrieve Genres Information
Creating search requests to VOD Items catalog
