This getting started guide is provided as an overview of how to implement the OData 2.0 API + Video. The steps below will link you tospecific documentation and guide you towards getting IVA’s trailer content up and streaming.
- For best results, work with one of the data companies listed here for getting rich metadata and program information. IVA’s trailers can be linked to your existing data from 3rd Party IDs (like Gracenote, Rovi, IMDB, etc). If you are not working with a data company, it’s fine, you are more than welcome to use our metadata.
- PAID or FREE? If you would like to display IVA’s content without ads, want to insert your own advertising, or need more than 500 requests per hour, you will need a subscription to IVA. Contact sales for more information. Not ready for a subscription just yet? IVA offers limited access to our OData API and allows the use of our Ad Supported Free Trailer Player to display IVA’s content. Either option will allow you access to unlimited video plays.
STEP 1: Get Access to the Data
Subscription clients and test accounts are issued developer ID’s by our customer service team once a test account has been set up. If you are not interested in a subscription, use our free developer sign-up form and you will be emailed a developer ID.
Developer ID’s associated to your subscription account will have request limits of 3,000 requests per hour. These DeveloperID’s can also be allowed access to 3rd party ID’s (Gracenote, Rovi, TMS, IMDB, etc…) inside the API (3rd party subscription required).
* Video requests per hour: Unlimited
Developer ID’s not associated to a paid subscription are limited to 500 requests per hour.
* Video requests per hour: Unlimited
STEP 2: Fetch the data from the OData API
Start by deciding what data is important to you. OData is extremely flexible and able to provide the specific data you need to work with IVA’s contet. Review the data dictionary for available metadata. Store and update this data as often as possible.
Start with an ingest query to get the current catalog.
(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(500)
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 &developerid=dd9a9172-4fbd-469c-bc92-a0955e9bdd6b&format=json
Live Example : View Results
((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))
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
Be sure to pay extra close attention to the following fields.
- LanguageSpoken – Tells you the language spoken in the trailer.
- LanguageSubtitled – Tells you the language subtitled in the trailer. Some movie trailers have many alternate trailers that are spoken in English and subtitled in various different languages. Be sure to handle for those if you do not want to display them.
- ExpirationDate – On some assets, mostly related to TV content, the copyright holder will impose an expiration date. Pay close attention to this field to avoid broken links.
- OkToEncode AndServe – If set to false the video will not stream and should not be used.
- RequiresIVAPlayer – These assets must be played back using the IVA player.
- TargetCountry – If a trailer is targeted to a specific country it will be reflected in this value. Anything set to -1 should be considered as the US trailer or for world wide use.
- Media Type – Describes the type of video asset (Interview, Behind the Scene, Alternate, etc…).
- Sequence – For TV season records this will be the season number and for episodic records this will be the episode number for the season.
- Overall Sequence – Applies to the episodic records and will be the overall episode number of the series.
- DefaultVideoAsset – If you are displaying multiple trailers for the user to choose, the default video asset should be displayed first. This is the most recent trailer added for a particular program.
- AllowAds – In rare instances copyright holders will restrict the use of ads around a particular piece of content. This field denotes whether or not an asset has this restriction.
Step 3: Video Options
IVA offers video options for every platform and device including adaptive bitrates for next generation set top boxes and mobile devices, baseline profile mp4 videos for compatibility with first generation devices and high definition 1080P video for visually stunning video at full screen.
Use the published ID’s of the video assets stored in your database with either our Cross Platform Player or our Video API to generate direct links to the video formats of your choice. (HLS, HDS, DASH, HSS, MP4,etc) for use in your own player or in the device’s native player (ex: IOS Media Player).
Use the video asset’s published ID with our Free Trailer Player. The player is loaded inside an iframe and contains IVA’s branded video as well as Pre-Roll advertising.