Implementation Guide - Shows

Recommended Implementation

When implementing shows using the API IVA recommends the following approach:

  1. Use /Shows/All endpoint to get and cache all the Show objects. Be sure to include any additonal objects as needed. If Season and Episode details are not important but the videos are you can include SeasonVideos and EpisodeVideos as well as Videos in your API call. This will give you all the videos for a show.
  2. Use the /Changes/Shows/History endpoint to get Show IDs of any Show object that has changes.
  3. Use the /Shows/{Id} endpoint to get the updated show object and replace what is stored in cache.
  4. (Optional): Use one of the /ExternalId/ endpoints to get a list of 3rd party Id and IVA Show ID pairs. This allows developers to link 3rd party ids to the IVA Show IDs, Image IDs, People IDs, and Video IDs. Some 3rd party IDs require special permissions (Gracenote, Tivo, Webedia, etc.).
Alternate Methods

These alternate methods are only recommended for testing and small data sets. IVA does impose rate limits to the API on a per customer basis starting at 5/second. If you are unsure of your rate limit please contact us.

  • /Find/Show - Can be used with a 3rd party ID to look up an IVA Show.
  • /Shows/SearchAndDiscover - Can be used to search Title, Director, Alternate Titles, Cast, etc.
  • /Shows/Match - Can be used to match based on title, year, director, and cast information. Contact us if you are interested in setting up matching.

Get All Shows

Start with GetAllShows(/Shows/All) paging through all the results. Include any additional objects (Videos, SeasonVideos, EpisodeVideos, Images, Genres, Descriptions, etc.) to be returned. Store each show object in a database for easy updating.


Usage and SDK Samples

curl -X get -H "Ocp-Apim-Subscription-Key: [[apiKey]]" ""
Get Updated Show Id's

Use one of the Changes APIs, GetShowChangeHistory(/Changes/Shows/History) or GetShowChangeHistoryWithEntity(/Changes/Shows/HistoryWithEntity) to keep the data up-to-date. IVA's staff is continually updating the data, adding images, and adding video. IVA recommends updating once an hour or more.


Usage and SDK Samples

curl -X get -H "Ocp-Apim-Subscription-Key: [[apiKey]]" ""

Update Show

For each ShowId that has been updated, update the data in your database by calling GetShow(/Shows/{Id}) and replacing the full object. Developers are encouraged to check for updates often to keep the data fresh and to be aware of new video assets and images added to the library.


Usage and SDK Samples

curl -X get -H "Ocp-Apim-Subscription-Key: [[apiKey]]" "{Id}?includes="