Entertainment Express Professional

• Overview
• API Response Object
• Code Samples
• API Status Codes
• Data Partners
• Authentication

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:

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

Assets Object

Images Object

Captions Object

Encodes Object

EmbedCodes Object

Code Samples

 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;
 }

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;
 }

Data Partners

HTTP Status Codes

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.