Internet Video Archive Trailers

Overview

This API provides subscribers access to all Internet Video Archive,(IVA), trailers with direct links and various embed options. The API is is fully customizable using unlimited Application Profiles that are managed through IVA's CMS Media Manager.  Application Profiles let you customize which content and language versions you want returned from the API to streamline your code and provide an easy way to localize content where available. This API offers developers quick access to IVA's content ecosystem which enhances their applications with the most organized collection of high quality trailers on earth. To access this data and video you will need to obtain credentials through your Gracenote representative or directly from IVA.

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 to create an Application Profile. If you do not have access to Media Manager contact customer support for access to your specific account.
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. IVA Customer ID: This is the unique customer ID in IVA that identifies your account.
4. API Request Limit: 10,000 requests per hour. If more are needed contact IVA Support.

Creating an Application Key

  1. Log into Media Manager. Contact your support representative for your credentials.
  2. Click "Account -> Manage Express API Keys.
  3. Click "Create New Application Key"
  4. Select the desired options for your app key configuration. You can create more than one app key if needed. You may consider multiple app keys if you want specific media types or language profiles for each key. Take note of the the "Video URL Time To Live in Minutes" and set this based on how you will use the video URL's. If you will be implementing this client side then you can leave the default. If you plan on ingesting the URL's and storing them in your database then you should set the links not to expire for longer than your threshold for refreshing the links to the content.

URL Endpoints:

ID Search:

http://data.tmsapi.com/ivaTrailers/{someid}?appid={your app id}&idtype={idtype}&customerid={IVA customer ID}

Title Search:

http://data.tmsapi.com/ivaTrailers/actions/search?appid={your app id}&term={searchterm}&customerid={IVA customer ID}

Parameters:

Name Required Description API Version
id Required for ID Search. Ex: http://data.tmsapi.com/ivaTrailers/MV000722830000?appid=12345&customerid={IVA customer ID} WhiteListPro
idtype Required for ID Search. Ex: http://data.tmsapi.com/ivaTrailers/MV000722830000?idtype=1&appid=12345&customerid={IVA customer ID}. See data partners for complete list of options. WhiteListPro
term Required for title search. Ex: http://data.tmsapi.com/ivaTrailers/actions/search?term=The+Matrix&customerid={IVA customer ID} WhiteListPro
appid Required Ex: http://data.tmsapi.com/ivaTrailers/MV000722830000?idtype=1&appid=12345&customerid={IVA customer ID} WhiteListPro
customerid Required for API authentication Ex: http://data.tmsapi.com/ivaTrailers/MV000722830000?idtype=1&appid=12345&customerid={IVA customer ID}. WhiteListPro

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

Property 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 meida types.
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

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 of meida types.
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. Additional access and fees apply.
Encodes Encodes are a list of directly link video renditions including HLS, mp4 and others.
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 IVA Standard version. Gracenote customers should use one of the other embed codes if considering the embed option.
ProprietaryCustomerID The customer Id of the customer this asset belongs. You will only see proprietary assets that belong to you. This only applies to content you upload through Media Manager and only works with term search or IVA published ID idtype = 1. Additional access and fees apply for proprietary content.

Images Object

Property Description
URL URL to the image.
Width The width of the image.
Width The height of the image.

Captions Object

Property Description
Note: Captions require additional access and fees. 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 IVA customer ID linked to this asset.

Encodes Object

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

Property Description
Type There are 4 types of embed codes to choose from in the array. Gracenote customers will have 3 HTML5 embed code options with different formats (HLS, Dash, MP4). Free-Flash is an iframe of IVA's free ad supported player and should be ignored by Gracenote customers.
EmbedHTML Embed code to embed the video in your application, website or guide.

Media Type Definitions

Media ID Media Type Description
0 Movie This is the main movie trailer. If more than one trailer has been made to promote a movie, the most recent trailer becomes the main, or default asset; older trailers become media type Movie Alternate.
20 Movie Alternate This category includes all trailers that IVA receives in addition to the main, or default trailer. This category can include older trailers, as well as international versions with subtitles or other languages spoken.
10 Movie SceneOrSample A clip or scene from the movie.
5 Movie Interview Interviews with cast and crew about the movie.
6 Movie Behind the Scenes Behind-the-scenes footage from the making of the movie.
34 Movie Fan-Made Not currently available.
24 Series Assets that are representative of the series as a whole; intended to give anyone who watches an idea of what the program is about.
52 Series Alternate Additional assets that IVA has received to promote the series.
51 Series SceneOrSample A clip or scene from the series.
49 Series Interview Interviews with cast and crew about the series.
50 Series Behind-the -Scenes Behind-the-scenes footage from the making of the series.
64 Series Slider A video slideshow comprised of production and promotional stills.
53 Series Fan-Made Not currently available.
26 Season Assets promoting a specific season of a series.
57 Season Alternate Additional assets that IVA has received to promote the season.
56 Season SceneOrSample A clip or scene from the season.
54 Season Interview Interviews with cast and crew about the season.
55 Season Behind-the- Scenes Behind-the-scenes footage from the making of the season.
53 Season Fan-Made Not currently available.
27 Episode Assets promoting a specific episode in the season.
32 Episodic Alternate Additional assets that IVA has received to promote a specific episode.
31 Episodic SceneOrSample A clip or scene from the episode.
29 Episodic Interview Interviews with cast and crew about the episode.
30 Episodic Behind-the-Scenes Behind-the-scenes footage from the making of the episode.
38 Episodic Fan-Made Not currently available.
25 Show Video assets that are promos for a specific show.
62 Show Alternate Alternate versions of promos for this show.
61 Show SceneOrSample A clip or scene from the show.
59 Show Interview Interviews with participants and crew about the show.
60 Show Behind-the- Scenes Behind-the-scenes footage from the making of the show.
63 Show Fan-Made Not currently available.
3 Song Media type for music videos of a song.
33 Song Alternate Alternate versions of the music video.
14 Song SceneOrSample A clip or sample from the music video.
12 Song Interview Interviews with performer(s) about the music video or the band.
15 Song Behind-the-Scenes Behind-the-scenes footage from the making of the music video.
1 Game Media type for game trailers.
23 Game Alternate Alternate versions of the game trailer.
21 Games SceneOrSample A clip or sample from the game.
35 Game Fan-made Place holder for future content.
43 Live Event Video assets that are of this type are promos for a live event.
47 Live Event Alternate Alternate versions of promos for this live event.
46 Live Event SceneOrSample A clip or scene from the live event.
44 Live Event Interview Interviews with cast and crew about the live event.
45 Live Event Behind-the-Scenes Behind-the-scenes footage from the making of or preparation of the live event.
48 Show Fan-Made Not currently available
28 Other Used for content that does not fit in any of the categories above. Also used by IVA clients for proprietary content.
42 Other Alternate Alternate versions of promos for Other media type.
41 Other SceneOrSample A clip or sample from video.
39 Other Interview Interviews with participants and crew.
40 Other Behind-the- Scenes Behind-the-scenes footage.
37 Other Fan-Made Not currently available.
8 Commercial Used by IVA customers for proprietary video content.
19 News Used by customers for proprietary video content.

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: {
           
          'X-Api-Version': '1'   
         },
         async: false,
         url: 'http://data.tmsapi.com/ivaTrailers/',
         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: {
           
          'X-Api-Version': '1'   
         },
         async: false,
         url: 'http://data.tmsapi.com/ivaTrailers/',
         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

Supported Data Partner ID's and their idtype.

IdType Description
1 PublishedID. This is IVA's internal IDs for programs.
11 TMS. This is TMS id from Gracenote.
80 TMS Root ID
12 IMDB. This is IMDB id from www.imdb.com. (This is not a complete data set.)
44 EIDR. This is EIDR id from www.eidr.org

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.