
Entertainment Express Professional
Overview
Entertainment Express Professional provides subscribers access to all IVA trailers with direct links and various embed options. The API is is fully customizable using unlimited Application Profiles. Application Profiles let you customize which content you want returned from the API to streamline your code.
Entertainment Express Professional offers developers quick access to IVA’s content ecosystem which enhances their applications with the most organized collection of high quality trailers on earth.
Requirements / Restrictions:
1. Application Profile (APPID): This is used to customize the response from the API. By using an Application Profile, you can specify the media types, target audience, language preferences, and a host of other options. To get started, log into your Media Manager account create an Application Profile.
2. Program ID or Title: In order to find a trailer for a movie, game or tv show the API needs to know what you are searching for. This is best done using ID’s. Here is a complete list of IDs Entertainment Express supports. If you don’t have access to any ID’s, Entertainment Express also supports a Title Search option where you can search for titles. The API will return a list of matches ordered by relevance for you to display to your users or automatically select the first one to display on your application.
3. Rate Limit: Entertainment Express Professional includes up to 10,000 requests per hour. You can purchase additional requests in increments of 250,000 for a small fee.
URL Endpoints:
ID Search:
https://ee.internetvideoarchive.net/api/expresspro/{someid}?appid={your app id}&idtype={idtype}
Title Search:
https://ee.internetvideoarchive.net/api/expresspro/actions/search?appid={your app id}&term={searchterm}
Parameters:
Name | Required | Description | API Version |
---|---|---|---|
id | Required for ID Search. | Ex: expressstandard/1756?appid=12345 | STANDARD, PRO |
idtype | Required for ID Search. | Ex: expressstandard/1756?idtype=1&appid=12345. See data partners for complete list of options. | STANDARD, PRO |
term | Required for title search. | Ex: /api/expressstandard/actions/search?term=The+Matrix | STANDARD, PRO |
appid | Required | /api/expressstandard/1756?idtype=1&appid=12345 | STANDARD, PRO |
Example JSON Response
Note that some elements have been left blank intentionally.
[
{
"Title": "The Matrix",
"FirstReleasedYear": 1999,
"PublishedId": 8451,
"MediaType": "Movie",
"Performers": [
"Carrie-Anne Moss",
"Gloria Foster",
"Hugo Weaving",
"Joe Pantoliano",
"Keanu Reeves",
"Laurence Fishburne",
"Wachowski Brothers"
],
"DateModified": "2014-03-21T15:28:00+00:00",
"NormalizedTitles": [
"matrix"
],
"Assets": [
{
"PublishedId": 8451,
"Title": "The Matrix",
"isDefault": true,
"MediaType": "Movie",
"Mature": false,
"OriginalVideoWidth": 720,
"OriginalVideoHeight": 480,
"DurationInSeconds": 146,
"AllowAdvertising": true,
"EncodeDate": "2008-12-16T05:00:00+00:00",
"TargetAudience": "en-US",
"Images": [
{
"URL": "http://content.internetvideoarchive.com/content/photos/201/8451_007.jpg",
"width": 320,
"height": 240
},
{
"URL": null,
"width": 120,
"height": 90
},
{
"URL": null,
"width": 240,
"height": 135
},
{
"URL": null,
"width": 600,
"height": 338
}
],
"Captions": null,
"Encodes": [
{
"URL": "",
"Format": "mp4",
"BitRate": 750
},
{
"URL": "",
"Format": "mp4",
"BitRate": 8000
},
{
"URL": "",
"Format": "mp4",
"BitRate": 80
},
{
"URL": "",
"Format": "mp4",
"BitRate": 212
},
{
"URL": "",
"Format": "mp4",
"BitRate": 450
},
{
"URL": "",
"Format": "mp4",
"BitRate": 1500
},
{
"URL": "",
"Format": "hls",
"BitRate": 600
},
{
"URL": "",
"Format": "hds",
"BitRate": 600
},
{
"URL": "",
"Format": "hss",
"BitRate": 600
},
{
"URL": "",
"Format": "dash",
"BitRate": 600
}
],
"EmbedCodes": [
{
"Type": "free-flash",
"EmbedHTML": "*** IFRAME EMBED CODE EXCLUDED FOR EXAMPLE ***"
},
{
"Type": "html5-mp4",
"EmbedHTML": ""
},
{
"Type": "html5-hls",
"EmbedHTML": ""
},
{
"Type": "html5-dash",
"EmbedHTML": ""
}
],
"ProprietaryCustomerId": -1
}
]
}
]
API Response Objects
Program Object
The Program object contains metadata about the specific title or program being returnedProperty | Description |
---|---|
Title | This title will be the program title. {data.program.title} |
FirstReleasedYear | The year the program was first released. (YYYY) |
PublishedID | The IVA unique ID for the the program. This will be the same ID as the default video asset. |
MediaType | The media type of the program will be Movie, Series, Game, or Music. For a full list of our Media Types see the documentation. |
Performers | A collection of performer names. |
DateModified | The date the program was last modified. |
NormalizedTitles | a collection of normalized titles including any title AKA's. |
Assets | The Assets object is a collection of meta data about the videos IVA has for the Program. An example of an Asset is a trailer. |
Assets Object
This is a collection of video assets for the program. Use the encodes or the embed codes to display the video.Property | Description |
---|---|
PublishedID | The IVA unique ID for the video asset for the video. |
Title | Title of the video asset. {data.videoasset.title} |
IsDefault | True or False. Identifies the default video asset for the program/title. IVA editorially selects the "Best" video for a program based on where the program is in the release cycle (theatrical, VOD, etc) as well as overall video quality. |
MediaType | The type of video asset. Example: Movie, Movie Alternate, Behind the Scenes, Interview, etc... See the full list in our documentation. |
Mature | True or False. Denotes if the content contains explicit material. |
OriginalVideoWidth | Width of the source video before encoding. |
OriginalVideoHeight | Height of the source video before encoding |
DurationInSeconds | Length of the video in seconds. |
AllowAdvertising | True or False. Some content providers provide content with the restriction that no ads be displayed around the content. This type of content can be filtered out based on the app config. |
EncodeDate | Date the source video asset was encoded. |
TargetAudience | A combination of target country, language spoken and language subtitled of the video asset. It is intended to be used to filter assets based on territory. |
Images | A collection of images in various sizes. |
Captions | This will be null for anyone not using IVA's Caption API to order captions. If you have ordered a caption and there is one available, the API will display an array of links to the caption files. |
Encodes | Encodes are a list of directly link video renditions including HLS, mp4 and others. Encodes requires a paid subscription to Pro. |
EmbedCodes | HTML code used to place on web pages or HTML5 applications to display video. EmbedCodes Type=free-flash is the only embedcode available in Standard. Access to other embed code options requires a paid subscription to Pro. |
ProprietaryCustomerID | The customer Id of the customer this asset belongs. You will only see proprietary assets that belong to you. |
Images Object
A list of URLs, and sizes to display with the video asset. Note: only the 320x240 image is available in Standard. Access to other sizes requires a paid subscription to Pro.Property | Description |
---|---|
URL | URL to the image. |
Width | The width of the image. |
Width | The height of the image. |
Note: only the 320x240 image is available for Standard. |
Captions Object
Captions in the entertainment express response.Property | Description |
---|---|
Note: Captions require a paid subscription to Pro. Click here for more information. | |
URL | URL to the caption file. |
Format | The format of the caption file. |
Language | The language of the text in the caption. Ex: If you wanted Spanish captions on an English spoken trailer the language would be Spanish. |
CustomerId | The customerid assigned to you for your Pro Subscription. |
Encodes Object
A collection of the available encodes for each video asset. This object also contains live links to stream the video assets. For more information on our video formats please see our documentation.Property | Description |
---|---|
URL | A live URL to IVA's Video API to stream the video. |
Format | Video Format: MP4, HLS, HSS, HDS, DASH |
Bitrate | Bitrate of the specific encode. |
EmbedCodes Object
This object contains a collection of embed codes users can use to embed a video player with the video into an application, website or guide.Property | Description |
---|---|
Type | There are 4 types of embed codes to choose from in the array. Free-Flash that is an iframe of our free ad supported player. Enterprise customers will have 3 HTML5 embed code options with different formats (HLS, Dash, MP4) |
EmbedHTML | Embed code to embed the video in your application, website or guide. |
Code Samples
ID Search
This example makes an AJAX request to the API passing the ID, IDTYPE, and APPID. The JSON response is returned from the method. A real world example might attach to the page onload event and populate data on the page asynchronously.
function SearchById(id, idtype, appid) {
var response;
$.ajax({
dataType: "json",
headers: {
Authorization: 'Bearer ' + '{your_oAuth_token}',
'X-Api-Version': '1'
},
async: false,
url: 'https://ee.internetvideoarchive.net/api/ExpressPro/',
data: {
'idtype': idtype,
'appid': appid,
'id': id
},
success: function (d) {
response = d;
},
error: function (err, result) {
response = err.responseJSON;
}
});
return response;
}
Working Example of Id Search
Title Search
This example makes an AJAX request to the API passing the TERM and APPID. The JSON response is returned from the method. A real work example might attach to a search button onClick event which then makes a request to the API and populates the results asynchronously.
function SearchByTitle(term, appid) {
var response;
$.ajax({
dataType: "json",
headers: {
Authorization: 'Bearer ' + '{your_oAuth_token}',
'X-Api-Version': '1'
},
async: false,
url: 'https://ee.internetvideoarchive.net/api/ExpressPro/actions/search/',
data: {
'appid': appid,
'term': term
},
success: function (d) {
response = d;
},
error: function (err, result) {
response = err.responseJSON;
}
});
return response;
}
Working Example of Title Search
Data Partners
Below is a list of ID and IDTypes the API supports searching with.IdType | Description |
---|---|
1 | PublishedID. This is IVA's internal IDs for programs. |
7 | AMG Movie. This is the All Movie Guide ID from Rovi Corporation. |
11 | TMS. This is TMS id from Gracenote. |
12 | IMDB. This is IMDB id from www.imdb.com. (This is not a complete data set.) |
14 | Muze Movie. This is Muze 1.0 id from Rovi. |
15 | UPC. (This is not a complete data set.) Zero pad to 14 characters. |
18 | Fandango. This is Fandango id. (This is not a complete data set. It is primarily theatrical movies.) |
44 | EIDR. This is EIDR id from www.eidr.org |
62 | Rovi Cosmo 1.0 This is Rovi Cosmo 1.0 ID. |
65 | Rovi 2.0 This is Rovi 2.0 ID. |
88 | Rovi RCS 2.x ID |
HTTP Status Codes
HTTP status codes supported by the API.Code | Description |
---|---|
200 | OK. Request was received and a response with content is delivered. |
204 | No Content. The request was received, but the response was intentionally left empty. We did not have a matching video for your request. |
401 | Not Authorized. If valid AppID is missing from request, authorization will fail. |
429 | Too many requests. If you exceed the request limit, no content will be returned. |
500 | Internal Server Error. The API could not process your request due to an internal server error. |
Authentication
EntertainmentExpress API (PRO) requires a bearer token header be included in all of your requests. To obtain a bearer token, your application must first authenticate with our oAuth server by providing your appid and secret key
which can be found at http://mediamanager.internetvideoarchive.com/Account/Appprofiles/profiles.aspx under Accounts. Here you register your application and access your appid and secret key.
Important: Your SECRET_KEY is a password and should not be exposed, visible or shared with untrusted users.
Step 1: oAuth Request for Token
Your client application will make a request to the oAuth server located at:
https://ee.internetvideoarchive.net/token
The POST request needs to include grant_type, client_id, and client_secret parameters.
CURL:
$ curl -d grant_type="client_credentials" \
-d client_id=APPID \
-d client_secret=SECRET_KEY \
'https://ee.internetvideoarchive.net/token'
JQUERY:
$.ajax({
async: false,
type: "POST",
dataType: "json",
url: 'https://ee.internetvideoarchive.net/token',
data: {
'grant_type': "client_credentials",
'client_id': '{Your_APP_ID}',
'client_secret': '{Your_Secret_Key}'
},
...rest of code removed...
})
Step 2: oAuth Response with token
The response object returned will include your access_token, token_type and expires_in parameters.
The response is in JSON and can be easily parse using javascript.
{
"access_token": "sadf6d81159easdf3424kjdfg90345345hhh_fdf349d408f2f",
"token_type":"bearer",
"expires_in":405600543
}
Step 3: Include Access_Token in Requests to Entertainment Express Pro
For each api request (https://ee.internetvideoarchive.net/api/expresspro/1234?appid={APPID}) you will need to include the access_token in the header.
For Example:
$.ajax({
dataType: "json",
headers: {
Authorization: 'Bearer ' + 'sadf6d83424kjdfg90345345hhh_fdf349d408f2f',
'X-Api-Version': '1'
},
url: 'https://ee.internetvideoarchive.net/api/expresspro/actions/search/',
... remaining code ....
Step 4: Entertainment Express Pro Response
Express API will return Program object(s) requests if the Bearer token is valid in the header is valid.
Other Security Considerations
Tokens are passwords
Keep in mind that the APPID, SECRET_KEY, and bearer token (access_token) grant access to make requests on behalf of an application. These values should be considered as sensitive as passwords and must not be shared or distributed to untrusted parties.
SSL Required
This manner of authentication is only secure if SSL is used. All requests (both to obtain the tokens and the APIs themselves) must use HTTPS endpoints.
Rate Limiting
Access_tokens expire in 14 day. We recommend you cache your bearer access_token for 24 hours and re-authenticate to get a new access_token daily. Do not attempt to request a new access_token for each request or you will be rate limited and authentication will eventually fail.