Examples

Use the queries below to form a better understanding of the types of meta-data you can access via IVA’s OData API 2.0. Here is a list of common queries that will return an abundance of meata-data to support the trailers on your site.

The OData 2.0 API is very flexible and allows you to join many tables to perform complex queries.  The more complex the query, the more resources it takes to process the request.  There is a hard timeout of 30 seconds on queries for this API.  To make your queries run faster, consider limiting the number of results to 100 records at a time.

We have found LINQPad to be a useful tool to help visualize the data and to run queries against the database. Download this free program and read our instructions for setting it up.

Example Ingest Query

This example is a good starting point for anyone looking to ingest IVA’s back catalog of video assets and meta-data. Each implementation is unique so there may be additional filters you wish to apply or data points you want to include. If there is a specific query you would like help with, email our support team.

LINQ

(from v in VideoAssets.expand("EntertainmentProgram, EntertainmentProgram/AlternateIds/AlternateIdType,VideoAssetScreenCapture, CountryTarget,LanguageSpoken, LanguageSubtitled, MediaType,Encodes, RegionRestrictions, Descriptions") where (v.ExpirationDate is nothing or v.ExpirationDate > datetime.now) and v.RequiresIVAPlayer = false and v.OkToEncodeAndServe = true and v.WarningFlag = false and v.AllowAds = true and ((v.LanguageSpokenId = 0 and v.LanguageSubtitledId = -1) or (v.LanguageSubtitledId = 0 and v.LanguageSpokenId > 0)) select v).skip(0).take(250)

URL

http://api.internetvideoarchive.com/2.0/DataService/VideoAssets()?$filter=cast((cast(ExpirationDate eq null,'Edm.Boolean') or ExpirationDate gt datetime'2015-06-18T21:18:04.6407898-04:00') and cast(RequiresIvaPlayer eq false,'Edm.Boolean') and cast(OkToEncodeAndServe eq true,'Edm.Boolean') and cast(WarningFlag eq false,'Edm.Boolean') and cast(AllowAds eq true,'Edm.Boolean') and cast(cast(LanguageSpokenId,'Edm.Int32') eq 0 and cast(LanguageSubtitledId,'Edm.Int32') eq -1 or cast(LanguageSubtitledId,'Edm.Int32') eq 0 and cast(LanguageSpokenId,'Edm.Int32') gt 0,'Edm.Boolean'),'Edm.Boolean')&$skip=0&$top=500&$expand=EntertainmentProgram, EntertainmentProgram/AlternateIds/AlternateIdType,VideoAssetScreenCapture, CountryTarget,LanguageSpoken, LanguageSubtitled, MediaType,Encodes, RegionRestrictions, Descriptions&format=json&developerid=dd9a9172-4fbd-469c-bc92-a0955e9bdd6b

Live Example : View Results

Example Update Query

After you have ingested the data about IVA’s back catalog of video assets, be sure to run updates on new and changed records in the future. The example below will show you only the programs that have been modified since a certain date.

LINQ

((from v in VideoAssets.expand("EntertainmentProgram, EntertainmentProgram/AlternateIds/AlternateIdType,VideoAssetScreenCapture, CountryTarget,LanguageSpoken, LanguageSubtitled, MediaType,Encodes, RegionRestrictions, Descriptions") _where  (v.EntertainmentProgram.AlternateIds.Any(function (y) y.DateAdded >= datetime.now.adddays(-5)) or v.EntertainmentProgram.DateModified > datetime.now.adddays(-3)) _select v).skip(0).take(100))

URL

http://api.internetvideoarchive.com/2.0/DataService/VideoAssets()?$filter=EntertainmentProgram/AlternateIds/any(y:cast(y/DateAdded ge datetime'2015-06-19T15:14:43.7815117-04:00','Edm.Boolean')) or EntertainmentProgram/DateModified gt datetime'2015-06-21T15:14:43.7815117-04:00'&$skip=0&$top=100&$expand=EntertainmentProgram, EntertainmentProgram/AlternateIds/AlternateIdType,VideoAssetScreenCapture, CountryTarget,LanguageSpoken, LanguageSubtitled, MediaType,Encodes, RegionRestrictions, Descriptions&format=json&developerid=dd9a9172-4fbd-469c-bc92-a0955e9bdd6b

Live Example : View Results

Example to get the most relevant program meta data and video assets using “expand”.

OData allows you to join or expand additional related entities. The following example will return the most commonly used meta-data that can be joined from the VideoAssets and EntertainmentProgram entities.

LINQ

(From e in EntertainmentPrograms.expand("Copyrightholder, Country, Director, AlternateIds/AlternateIdType, ProgramToPerformerMaps/Performer ,RelatedEntertainmentPrograms/RelatedEntertainmentPrograms/RelatedEntertainmentPrograms,ReleaseEvents, TitleAkas,VideoAssets, VideoAssets/VideoAssetScreenCapture, VideoAssets/Encodes, VideoAssets/CountryTarget, VideoAssets/LanguageSpoken, VideoAssets/LanguageSubtitled, VideoAssets/MediaType, VideoAssets/Captions, VideoAssets/RegionRestrictions") where e.PublishedId > 0 select e).skip(3000).take(100)

URL

http://api.internetvideoarchive.com/2.0/DataService/EntertainmentPrograms()?$filter=Publishedid gt 0&$skip=3000&$top=100&$expand=Copyrightholder, Country, Director, AlternateIds/AlternateIdType, ProgramToPerformerMaps/Performer ,RelatedEntertainmentPrograms/RelatedEntertainmentPrograms/RelatedEntertainmentPrograms,ReleaseEvents, TitleAkas,VideoAssets, VideoAssets/VideoAssetScreenCapture, VideoAssets/Encodes, VideoAssets/CountryTarget, VideoAssets/LanguageSpoken, VideoAssets/LanguageSubtitled, VideoAssets/MediaType, VideoAssets/Captions, VideoAssets/RegionRestrictions&Developerid=B43BF933-5CB5-434A-B0A8-717FC149FBED

Live Example : View Results

JSON vs. XML Response

Depending on your preference, IVA’s OData API can return XML or JSON. By default the API will return XML. To get a JSON response add the parameter “format=json”.

URL

http://api.internetvideoarchive.com/2.0/DataService/EntertainmentPrograms()?$filter=Publishedid gt 0&format=json&developerid=dd9a9172-4fbd-469c-bc92-a0955e9bdd6b

Live Example : View Results

JSONP supported with the “$callback” feature

JSONP is script tag injection, passing the response from the server in to a user specified function. The following example shows the callback feature. Callback along with the format=json will allow you to pass the API request results back to a function(cb) and allows for cross domain JSON requests.

URL

http://api.internetvideoarchive.com/2.0/DataService/ReleaseEvents()?$top=1&$format=json&$callback=cb&developerid=dd9a9172-4fbd-469c-bc92-a0955e9bdd6b

Paging Example

By default the OData API returns up to 500 records at a time. When requesting more than 500 records write a query to page through the data or get the next set. Below is an example demonstrating one way to do paging using “Top” and “Skip”. Continue the pattern to get all the records.. IVA recommends using a smaller number(100 or so) and page through the results.

LINQ


(From v in VideoAssets where v.MediaId = 0 select v).skip(1500).take(100)

URL

api.internetvideoarchive.com/2.0/DataService/VideoAssets()?$filter=MediaId eq 0&$skip=1500&$top=100&developerid=dd9a9172-4fbd-469c-bc92-a0955e9bdd6b

Live Example : View Results

Additional examples

URL to get first set of records 1 – 500

http://api.internetvideoarchive.com/2.0/DataService/EntertainmentPrograms?$top=500

URL to get second set of records 501 – 1000

http://api.internetvideoarchive.com/2.0/DataService/EntertainmentPrograms?$top=500&$skip=500

URL to get third set of records 1001 – 1500

http://api.internetvideoarchive.com/2.0/DataService/EntertainmentPrograms?$top=500&$skip=1000

Finding assets for a US based Audience

IVA captures international versions of trailers as well as the US versions. The example below filters video assets based on language to give you only assets that would be suitable for an English speaking audience.

LINQ

(from v in VideoAssets.expand("EntertainmentProgram/AlternateIds, EntertainmentProgram, MediaType, Encodes, VideoAssetScreenCapture") where v.MediaId = 0 _and ((v.LanguageSpokenId = 0 and v.LanguageSubtitledId = -1) or (v.LanguageSubtitledId = 0 and v.LanguageSpokenId > 0))select v).skip(1000).take(100)

URL

http://api.internetvideoarchive.com/2.0/DataService/VideoAssets()?$filter=MediaId eq 0 and (cast(LanguageSpokenId,'Edm.Int32') eq 0 and cast(LanguageSubtitledId,'Edm.Int32') eq -1 or cast(LanguageSubtitledId,'Edm.Int32') eq 0 and cast(LanguageSpokenId,'Edm.Int32') gt 0)&$skip=1000&$top=100&$expand=EntertainmentProgram/AlternateIds, EntertainmentProgram, MediaType, Encodes, VideoAssetScreenCapture&format=json&developerid=dd9a9172-4fbd-469c-bc92-a0955e9bdd6b

Live Example : View Results

Finding video assets matched to a particular data provider.

IVA’s video assets are matched to top tier data providers such as Gracenote, Rovi, IMDB, RedBee, etc. Customers of these data providers can have their ID’s exposed through the API(special access needed). Not using one of these providers, IVA is also matched to additional data sources that are made public through the API. The following example demonstrates how you can filter based on alternate id type allowing you to match video assets to programs with data from The Movie Database.

LINQ

(From x In VideoAssets.Where(Function(x) x.EntertainmentProgram.AlternateIds.Any(Function(y) y.IDType = 68)) where x.PublishedId > -1 select x. Title, x.Publishedid, x.ExpirationDate, x.OkToEncodeAndServe, x.EntertainmentProgram.AlternateIds).skip(10000).take(100)

URL

http://api.internetvideoarchive.com/2.0/DataService/VideoAssets()?$filter=EntertainmentProgram/AlternateIds/any(y:y/IDType eq 68) and Publishedid gt -1&$skip=10000&$top=100&$expand=EntertainmentProgram/AlternateIds&$select=Title,Publishedid,ExpirationDate,OkToEncodeAndServe,EntertainmentProgram/AlternateIds/*&format=json&developerid=dd9a9172-4fbd-469c-bc92-a0955e9bdd6b

Live Example : View Results

Movies releasing in theatres

IVA captures release event information for movies, TV, and video games. Use the dates in the release events table in the API to determine if a program released in the past, recently, or will be released in the future. The example below shows movies coming soon based off the current date.

from re in ReleaseEvents.expand("EntertainmentProgram") where re.ReleaseDate >= #6/1/2015# and re.ReleaseDate < #7/1/2017# and re.ReleaseTypeId = 0 select re

URL

http://api.internetvideoarchive.com/2.0/DataService/ReleaseEvents()?$filter=ReleaseDate ge datetime'2015-06-01' and ReleaseDate lt datetime'2017-07-01' and ReleaseTypeId eq 0&$expand=EntertainmentProgram&Developerid=B43BF933-5CB5-434A-B0A8-717FC149FBED

Live Example : View Results

Dynamic movie lists

Use the query below to get back programs and video assets for the following dynamic lists:

  • ID: 5100 – IVA’s Most Anticipated Movies Coming Soon
  • ID: 5101 – Most Popular Movies Releasing This Weekend

LINQ

from v in ListToProgramMaps.expand("VideoAsset/EntertainmentProgram/AlternateIds") where v.TitleListId = 5100 select v

URL

http://api.internetvideoarchive.com/2.0/DataService/ListToProgramMaps()?$filter=TitleListId eq 5100&$expand=VideoAsset/EntertainmentProgram/AlternateIds&format=json&developerid=dd9a9172-4fbd-469c-bc92-a0955e9bdd6b

Live Example : View Results

List all HD screen captures for a particular performer (ID 8143, Tom Cruise)

IVA tags performers in each screen capture that we create. In this example you can pass an IVA performer ID to get back a list of images the performer is tagged. In order to use these images you need a paid subscription. Use the published ID of the video asset in the response with IVA’s Custom Stills Service. The response contains the source width and height of the master image. If you plan on using a 4×3 image change the query below to return the width and height of the 4×3 master image.

LINQ

(from p in PerformerMappingToHdPhotos where p.PerformerId = 8143 and p.HdTitlePhoto.AspectRatioId = "16x9" order by p.HdTitlePhoto.publishedId select new with {p.HdTitlePhoto.publishedId, p.HdTitlePhoto.Width, p.HdTitlePhoto.Height} )

URL

http://api.internetvideoarchive.com/2.0/DataService/PerformerMappingToHdPhotos()?$filter=PerformerId eq 8143 and HdTitlePhoto/AspectRatioId eq '16x9'&$orderby=HdTitlePhoto/publishedId&$expand=HdTitlePhoto&$select=HdTitlePhoto/publishedId,HdTitlePhoto/Width,HdTitlePhoto/Height&format=json&developerid=dd9a9172-4fbd-469c-bc92-a0955e9bdd6b

Live Example : View Results

Get single performer photo URL (public)

IVA does offer one free 320×240 image of the performer. Use the example below to get the image URL.

LINQ

from o in PerformerScreenCaptures where o.PerformerId = 8143 select o

URL

http://api.internetvideoarchive.com/2.0/DataService/PerformerScreenCaptures()?$filter=PerformerId eq 8143&Developerid=B43BF933-5CB5-434A-B0A8-717FC149FBED

Live Example : View Results

Find video assets based on source quality

IVA receives video from over 1200 suppliers. Each supplier has different standards of video quality that they make available. IVA asks for and uses the highest quality available from the sources to make our mezzanine files and encode the video assets into our standardized formats. Developers can filter by the source video width to help determine the quality. The example below looks at video assets with a source width greater than 1000 and only at video assets related to movies.

LINQ

from v in VideoAssets where v.SourceWidth > 1000 and (v.MediaId = 0 or v.MediaId = 5 or v.MediaId = 6 or v.MediaId = 10 or v.MediaId = 20) select v

URL

http://api.internetvideoarchive.com/2.0/DataService/VideoAssets()?$filter=cast(SourceWidth,'Edm.Int32') gt 1000 and (MediaId eq 0 or MediaId eq 5 or MediaId eq 6 or MediaId eq 10 or MediaId eq 20)&format=json&developerid=dd9a9172-4fbd-469c-bc92-a0955e9bdd6b

Live Example : View Results

Select All EntertainmentPrograms where the MovieCategory = Drama

This simple example returns programs with the movie category of Drama.

LINQ

From o In EntertainmentPrograms where o.MovieCategory.Category = "Drama" Select o

URL

http://api.internetvideoarchive.com/2.0/DataService/EntertainmentPrograms()?$filter=MovieCategory/Category eq 'Drama'&Developerid=B43BF933-5CB5-434A-B0A8-717FC149FBED

Live Example : View Results

Query to get a matching table to ingest IVA Published ID’s based on Title, First Released Year and Director Name

This example looks at the main program for movies only. Modify this query to get all the related video assets.

LINQ

(From o In VideoAssets 
where o.DefaultVideoAsset = "true" and o.OkToEncodeAndServe = true and o.MediaId = 0 
Select o.PublishedId, o.Title, o.EntertainmentProgram.FirstReleasedYear, o.EntertainmentProgram.Director.FullName).skip(2000).take(100)

URL

http://api.internetvideoarchive.com/2.0/DataService/VideoAssets()?$filter=((DefaultVideoAsset eq 'true') and (OkToEncodeAndServe eq true)) and (MediaId eq 0)&$skip=2000&$top=100&$expand=EntertainmentProgram,EntertainmentProgram/Director&$select=Publishedid,Title,EntertainmentProgram/FirstReleasedYear,EntertainmentProgram/Director/FullName&format=json&developerid=dd9a9172-4fbd-469c-bc92-a0955e9bdd6b

Live Example : View Results

Search by title using a string (like)

LINQ

Example of a basic title search. IVA recommends working with a data provider we are matched to and using their ID’s to match to IVA’s video assets.

from e in EntertainmentPrograms where e.Title.contains("Dark Knight") select e

URL

http://api.internetvideoarchive.com/2.0/DataService/EntertainmentPrograms()?$filter=substringof('Dark Knight',Title)&developerid=B43BF933-5CB5-434A-B0A8-717FC149FBED

Live Example : View Results