Editorial Services API

Editorial Services API

This API is used to access the weekly lists and the assets they contain (check out the IVA blog for examples of our lists). The API uses an Application Key obtained through Media Manager for paid subscribers or through our free developer program.  Authentication is done in the same way as with Entertainment Express using OAuth 2.0.  Certain features in the API response will be limited for users of the free service.  For more information on our editorial services click here or contact sales.  To see an example of our lists check out our blog.

Endpoints: These endpoints have been added to the Entertainment Express API

/GetEditorialLists

Returns a collection of Editorial Lists
Parameters:  
appid (required)Generate this ID either inside of Media Manager (Pro version) or you can use an appid from our free developer account(Standard version)
skip (integer)Use this for paging through the results. Default is 0.
take (integer)Use this for paging or to limit the number of lists that get returned. Default is 10.
includepublic (Boolean)Default = True. ***only used for paid versions of Editorial Services. Allows you to exclude the public lists from the response.

Example URL:


https://ee.internetvideoarchive.net/api/ExpressStandard/GetEditorialLists/?skip=0&take=10&appid=xyz
or
https://ee.internetvideoarchive.net/api/ExpressPro/GetEditorialLists/?skip=0&take=10&appid=xyz

/GetEditorialList

Returns a specific EditorialList by ID.
Parameters:  
appid (required)Application key obtained through Media Manager (Pro Version) or from a free developer account (Standard).
ID (required)Id of the specific list you want returned.

Example URL:


https://ee.internetvideoarchive.net/api/ExpressStandard/GetEditorialList/30?appid=xyz
or
https://ee.internetvideoarchive.net/api/ExpressPro/GetEditorialList/30?appid=xyz

Example JSON Response

Note that some elements have been left blank intentionally.


{
    "ID": 76,
    "CustomerId": 0,
    "Title": "Movie Mutants",
    "Description": "It's mutants, mutants, and more mutants in X-MEN: APOCALYPSE, the sixth installment of the X-Men movie franchise. Genetic mutations, whether they come from within or without, can be a tricky proposition at best. Here are ten films featuring mutants of all shapes and sizes, and we mean that literally!",
    "Published": true,
    "Created": "2016-05-11T20:08:22",
    "Modified": "2016-05-17T15:00:42",
    "EditorialListPhotos": [
        {
            "ID": 90,
            "ListId": 76,
            "Url": "http://content.internetvideoarchive.com/content/lists/fbd7-76/fd547461fde9403d9f1e30a3236b3001.png",
            "Width": 1100,
            "Height": 630,
            "Created": "2016-05-16T15:10:18"
        }
    ],
    "EditorialListItems": [
        {
            "ID": 633,
            "ListId": 76,
            "PublishedId": 567,
            "Title": "Basket Case",
            "ContextDetail": "A young man carries his mutated twin brother in a basket while seeking vengeance on the doctors who separated them against their will.",
            "SortOrder": 1,
            "Asset": {
                "PublishedId": 567,
                "Title": "Basket Case",
                "isDefault": true,
                "MediaType": "Movie",
                "Mature": false,
                "OriginalVideoWidth": 636,
                "OriginalVideoHeight": 480,
                "DurationInSeconds": 62,
                "AllowAdvertising": true,
                "EncodeDate": "2016-05-10T08:59:42",
                "TargetAudience": "en-US",
                "Images": [
                    {
                        "URL": "http://content.internetvideoarchive.com/content/photos/014/567_018.jpg",
                        "width": 320,
                        "height": 240
                    },
                    {
                        "URL": "",
                        "width": 120,
                        "height": 90
                    },
                    {
                        "URL": "",
                        "width": 240,
                        "height": 135
                    },
                    {
                        "URL": "",
                        "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 src="\"https://syndication.videodetective.com/widget/inview/player.htm?publishedid=567&autostart=false&randomize=false&mute=false&sub=expressapi\"" width="\"560\"" height="\"315\"" frameborder="\"0\"" allowfullscreen="allowfullscreen"></iframe>" }, { "Type": "html5-mp4", "EmbedHTML": "<video poster="\"http://content.internetvideoarchive.com/content/photos/014/567_018.jpg\"" preload="\"auto\"" controls="controls" width="300" height="\"448\""><source src="\""" type="\"video/mp4\"/" /></video>" }, { "Type": "html5-hls", "EmbedHTML": "<video poster="\"http://content.internetvideoarchive.com/content/photos/014/567_018.jpg\"" preload="\"auto\"" controls="controls" width="300" height="\"448\""><source src="\""" type="\"application/x-mpegURL\"/" /></video>" }, { "Type": "html5-dash", "EmbedHTML": "<video poster="\"http://content.internetvideoarchive.com/content/photos/014/567_018.jpg\"" preload="\"auto\"" controls="controls" width="300" height="\"448\""><source src="\""/" /></video>\"" } ], "ProprietaryCustomerId": -1 } }, { "ID": 635, "ListId": 76, "PublishedId": 50, "Title": "The Fly", "ContextDetail": "David Cronenberg's horrifying tale of a scientist (Jeff Goldblum) who accidentally becomes fused with fly DNA and slowly, inexorably, mutates into a monster.", "SortOrder": 2, "Asset": { "PublishedId": 50, "Title": "The Fly", "isDefault": true, "MediaType": "Movie", "Mature": false, "OriginalVideoWidth": 704, "OriginalVideoHeight": 464, "DurationInSeconds": 104, "AllowAdvertising": true, "EncodeDate": "2009-11-03T00:00:00", "TargetAudience": "en-US", "Images": [ { "URL": "http://content.internetvideoarchive.com/content/photos/000/50_006.jpg", "width": 320, "height": 240 }, { "URL": "", "width": 120, "height": 90 }, { "URL": "", "width": 240, "height": 135 }, { "URL": "", "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 src="\"https://syndication.videodetective.com/widget/inview/player.htm?publishedid=50&autostart=false&randomize=false&mute=false&sub=expressapi\"" width="\"560\"" height="\"315\"" frameborder="\"0\"" allowfullscreen="allowfullscreen"></iframe>" }, { "Type": "html5-mp4", "EmbedHTML": "<video poster="\""" preload="\"auto\"" controls="controls" width="300" height="\"448\""></video>" }, { "Type": "html5-hls", "EmbedHTML": "<video poster="\"http://content.internetvideoarchive.com/content/photos/000/50_006.jpg\"" preload="\"auto\"" controls="controls" width="300" height="\"448\""><source src="\""" type="\"application/x-mpegURL\"/" /></video>" }, { "Type": "html5-dash", "EmbedHTML": "<video poster="\"http://content.internetvideoarchive.com/content/photos/000/50_006.jpg\"" preload="\"auto\"" controls="controls" width="300" height="\"448\""><source src="\"/" /></video>\"" } ], "ProprietaryCustomerId": -1 } }, ] }

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/geteditoriallists/?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/GetEditorialLists',
  ... remaining code ....

Step 4: Entertainment Express Pro Response

Express API will return Editorial List 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.

API Response Objects


List Object

The information in this object is specific to the the editorial list being returned.
PropertyDescription
IDUnique ID to identify this specific list.
CustomerIdFree lists put out by IVA will be listed as 0 any lists created for a customer will contain their customer ID. Customer lists will only get returned for app keys created from their account.
TitleTitle of the list.
DescriptionDescription of the list.
Publishedtrue or false.
CreatedDate Created.
ModifiedDate last modified.
Editorial PhotosArray of photos created by our staff to represent the list. Usually will only contain one unless specified by a paid subscription customer.


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.