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:

NameRequiredDescriptionAPI Version
idRequired for ID Search.Ex: expressstandard/1756?appid=12345STANDARD, PRO
idtypeRequired for ID Search.Ex:
expressstandard/1756?idtype=1&appid=12345. See data partners for complete list of options.
STANDARD, PRO
termRequired for title search.Ex:
/api/expressstandard/actions/search?term=The+Matrix
STANDARD, PRO
appidRequired/api/expressstandard/1756?idtype=1&appid=12345STANDARD, 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 returned
PropertyDescription
TitleThis title will be the program title. {data.program.title}
FirstReleasedYearThe year the program was first released. (YYYY)
PublishedIDThe IVA unique ID for the the program. This will be the same ID as the default video asset.
MediaTypeThe media type of the program will be Movie, Series, Game, or Music. For a full list of our Media Types see the documentation.
PerformersA collection of performer names.
DateModifiedThe date the program was last modified.
NormalizedTitlesa 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.
PropertyDescription
PublishedIDThe IVA unique ID for the video asset for the video.
TitleTitle of the video asset. {data.videoasset.title}
IsDefaultTrue 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.
MediaTypeThe type of video asset. Example: Movie, Movie Alternate, Behind the Scenes, Interview, etc... See the full list in our documentation.
MatureTrue or False. Denotes if the content contains explicit material.
OriginalVideoWidthWidth of the source video before encoding.
OriginalVideoHeightHeight of the source video before encoding
DurationInSecondsLength of the video in seconds.
AllowAdvertisingTrue 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.
EncodeDateDate the source video asset was encoded.
TargetAudienceA 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.
ImagesA collection of images in various sizes.
CaptionsThis 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.
EncodesEncodes are a list of directly link video renditions including HLS, mp4 and others. Encodes requires a paid subscription to Pro.
EmbedCodesHTML 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.
ProprietaryCustomerIDThe 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.
PropertyDescription
URLURL to the image.
WidthThe width of the image.
WidthThe height of the image.
Note: only the 320x240 image is available for Standard.


Captions Object

Captions in the entertainment express response.
PropertyDescription
Note: Captions require a paid subscription to Pro. Click here for more information.
URLURL to the caption file.
FormatThe format of the caption file.
LanguageThe language of the text in the caption. Ex: If you wanted Spanish captions on an English spoken trailer the language would be Spanish.
CustomerIdThe 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.
PropertyDescription
URLA live URL to IVA's Video API to stream the video.
FormatVideo Format: MP4, HLS, HSS, HDS, DASH
BitrateBitrate 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.
PropertyDescription
TypeThere 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)
EmbedHTMLEmbed 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.
IdTypeDescription
1PublishedID. This is IVA's internal IDs for programs.
7AMG Movie. This is the All Movie Guide ID from Rovi Corporation.
11TMS. This is TMS id from Gracenote.
12IMDB. This is IMDB id from www.imdb.com. (This is not a complete data set.)
14Muze Movie. This is Muze 1.0 id from Rovi.
15UPC. (This is not a complete data set.) Zero pad to 14 characters.
18Fandango. This is Fandango id. (This is not a complete data set. It is primarily theatrical movies.)
44EIDR. This is EIDR id from www.eidr.org
62Rovi Cosmo 1.0 This is Rovi Cosmo 1.0 ID.
65Rovi 2.0 This is Rovi 2.0 ID.

HTTP Status Codes

HTTP status codes supported by the API.
CodeDescription
200OK. Request was received and a response with content is delivered.
204No Content. The request was received, but the response was intentionally left empty. We did not have a matching video for your request.
401Not Authorized. If valid AppID is missing from request, authorization will fail.
429Too many requests. If you exceed the request limit, no content will be returned.
500Internal 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.