Release Notes

Last Updated 5/2/2016

Changes 5/2/2016
Add two new APIs to access Editorial Lists.
/GetEditorialLists Returns a collection of EditorialLists.
Parameters:
  • appid (required)
  • skip (integer) - for paging. Default is 0.
  • take (integer) - for paging. Default is 10.
Example URL:
  • https://ee.internetvideoarchive.net/api/ExpressStandard/GetEditorialLists/?skip=0&take=10&appid=xyz
  • https://ee.internetvideoarchive.net/api/ExpressPro/GetEditorialLists/?skip=0&take=10&appid=xyz
/GetEditorialList Returns a specific EditorialList by ID.
Parameters:
  • appid (required)
  • ID (required)
Example URL:
  • https://ee.internetvideoarchive.net/api/ExpressStandard/GetEditorialList/30?appid=xyz
  • https://ee.internetvideoarchive.net/api/ExpressPro/GetEditorialList/30?appid=xyz
Changes 2/12/2016
Performance improvements. Migrated to Redis Cache to reduce response time and increase scalability.
Added IP address white list security option. Contact sales rep for information and access.
Added Video URL Time to live configuration in your application key. The default is one day but you can now configure your URL Time to live inside MediaManager.internetvideoarchive.com under "Manage Express API Keys".
Changes 10/28/2015
Added Baseline ID support. The IDType = 38.
Changes 6/5/2015
Added caption support to the response. Now, in the application profile in mediamanager.internetvideoarchive.com you select the caption output options and if you ordered captions for the asset, you will see the caption URLs in the language and format when available.
Added UPC code support. Now if you have UPC codes for products, you can use them to locate trailers.
Changes 5/21/2015
Added oAuth 2.0 authentication to access api endpoints. See security information below.
Endpoint URLs have been modified. There are now 2 different API url structures to support the Pro and Standard versions of the api.
  • https://ee.internetvideoarchive.net/api/expresspro/{someid}?appid={your app id}
  • https://ee.internetvideoarchive.net/api/expressstandard/{someid}?appid={your app id}
This was done to support our free edition of this API which returns the same data but is limited to our ad supported embedHTML and does not include any Encodes. This version still has rate limiting (at 1,000 requests per hour) but does not need to authenticate using oAuth.
API Versioning has been included although there is only one version at this time.
To specify a version other than the default (highest version) you add the following header:
  • 'X-Api-Version': '1'
Changes 5/13/2015
Rate limiting has been enabled for customers. The response headers include RateLimit-Limit which is the customer's hourly rate limit as well as RateLimit-Remaining which are the number of requests remaining for the hour.
Adding Free/Developer Profile Type to allow testing of the API with light volume. These responses will not include Encode.URLs and will only include our flash-free embed code.
Changes 5/6/2015
Replaced Lucene search index with Amazon Cloud Search service. This provides less headaches and is always up to date.
Most of the images are using the image service. If they are not requested, they don't exist as we make them on the fly. The update process now makes a request for the image to the image service so that the image will be created so it is available immediately. This happens during the update process which occurs every 15 minutes.
Changes 5/3/2015
Search results have been tweaked to include Exact Phrase (ex: "Star Wars") to provide slightly more accurate results.
We also increased the internal result set from 10 to 50 before filtering down by MediaTypes. We saw situations where movie MediaTypes were returning lower result scores than other media types and not getting returned when application profile was looking for Movie.
Search is using Lucene search engine. You should be able to create your own Lucene query against the search index which currently includes the following fields: (PublishedId, MediaType, FirstReleasedYear, Performers, Titles). The default field being used is Titles.

Updated 4/29/2015

HTTP Status Codes

Below are the 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. (not implemented)
500 Internal Server Error. The API could not process your request due to an internal server error.
Caching

The table below outlines the frequency in which the data is updated.

Item Description
Document Storage This is updated every five minutes.
Document Cache on Web Servers Documents are cached in shared cache when requested. This cache is updated every 15 minutes if objects change.
Search Results Search results are cached in short term shared cache for 15 minutes.
Search Index The search index is updated by worker role every 15 minutes with changes and cached in shared cache for all web servers.
Searcher Object The searcher object reads the Search Index and caches it's data in memory. In order for the searcher to see new records it needs to be refreshed every 15 minutes.
Application Profiles This is getting cached in short term shared cache for 15 minutes.
ID Hash Tables Ids are stored in local in-memory hash tables for fast lookup. These hash tables are refreshed every 15 minutes.
Supported 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.)
18 Fandango. This is Fandango id. (This is not a complete data set. It is primarily theatrical movies.)
38 Baseline. This is Baseline id. (This is not a complete data set. It is primarily 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.
80 TMS Root ID
83 AMG Game ID
88 Rovi RCS 2.X Group ID
Security

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 Description
1
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...
})

2

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
}
3
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 ' + 'sadf6d81159easdf3424kjdfg90345345hhh_fdf349d408f2f',
   'X-Api-Version': '1'   
  },
  url: 'https://ee.internetvideoarchive.net/api/expresspro/actions/search/',
  ... remaining code ....
4

Express API will return Program object(s) requests if the Bearer token is valid in the header is valid.

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 days. 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.