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.
Shows
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.

/Shows/All

Usage and SDK Samples

curl -X get -H "Ocp-Apim-Subscription-Key: [[apiKey]]" "https://ee.iva-api.com/Shows/All?take=&skip=&includes="

import ee.examples.dto;
import net.servicestack.client.JsonServiceClient;

public class EE_Samples {

  public static void main(String[] args) {
  // TODO Auto-generated method stub
  
  // Ensure that all requests include the subscription key
  JsonServiceClient.GlobalRequestFilter = conn -> conn.setRequestProperty("Ocp-Apim-Subscription-Key", "XXXXXXXXXXXXXXXXXXXXXXXXX");
  
  // Instantiate the client and base URL.
  JsonServiceClient client = new JsonServiceClient("http://ee.iva-api.com");
  
    dto.AllShowsResponse shows = client.get("/Shows/all?includes=Videos,SeasonVideos,EpisodicVideos&skip=0&take=100", dto.AllShowsResponse.class);
    System.out.println(shows.getResult().get(0).Title);
    
  //Example of getting all Shows 100 at a time.
  
    int pageSize = 100;
    int item = 0;
    int resultCount = 100;
    while(resultCount == 100) {
    
      System.out.println("Fetching new list of titles from /Shows/all?take=100&skip=" + item );
      dto.AllShowsResponse allshows = client.get("/Shows/all?take=100&skip=" + item, dto.AllShowsResponse.class);
      
        for(dto.Show thisShow : allshows.Result){
        
          item++;

  // Save this title to your cache / database
  System.out.println("Working on Item: " + item + ", pageSize: " + pageSize + ", title: (" + thisShow.Id + ") " + thisShow.Title);
  
      }
      
      resultCount = allshows.Result.size();
      
      }
      
     }

}

    
}
Coming Soon!
Coming Soon!
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.

/Changes/Shows/History/

Usage and SDK Samples

curl -X get -H "Ocp-Apim-Subscription-Key: [[apiKey]]" "https://ee.iva-api.com/Changes/Shows/History/?date=&skip=&take="
import ee.examples.dto;

import net.servicestack.client.JsonServiceClient;


public class EE_Samples {

	private static final JsonServiceClient Unirest = null;

	public static void main(String[] args) {
		// TODO Auto-generated method stub
		

		// Ensure that all requests include the subscription key
				JsonServiceClient.GlobalRequestFilter = conn -> conn.setRequestProperty("Ocp-Apim-Subscription-Key", "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
				
				// Instantiate the client and base URL.
				JsonServiceClient client = new JsonServiceClient("http://ee.iva-api.com");
				
                	// get changes for shows
				
				String showsPullDate = "2017-09-13T08%3A00%3A00.0000000Z";
				
				dto.ShowChangeHistoryResponse[] showchanges = client.get("/Changes/Shows/History/?Date=" + showsPullDate +"&Skip=0&Take=1000", dto.ShowChangeHistoryResponse[].class);
				System.out.println("Number of shows with changes: " + showchanges.length);
				System.out.println("Example Show ID with changes:" + showchanges[0].ShowId);
				
				
					
					}
					
			}
                                
Coming Soon!
Coming Soon!
                                  
                              

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.

/Shows/{Id}

Usage and SDK Samples

curl -X get -H "Ocp-Apim-Subscription-Key: [[apiKey]]" "https://ee.iva-api.com/Shows/{Id}?includes="

import ee.examples.dto;
import net.servicestack.client.JsonServiceClient;

public class EE_Samples {

  public static void main(String[] args) {
  // TODO Auto-generated method stub
  
  // Ensure that all requests include the subscription key
  JsonServiceClient.GlobalRequestFilter = conn -> conn.setRequestProperty("Ocp-Apim-Subscription-Key", "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx");
  
  // Instantiate the client and base URL.
  JsonServiceClient client = new JsonServiceClient("http://ee.iva-api.com");
  
  // Use Client to fetch Show with ID 871 and include SeasonVideos and EpisodeVideos
  dto.ShowResponse show = client.get("/shows/871?includes=Videos,EpisodeVideos,SeasonVideos", dto.ShowResponse.class);
    
    System.out.println("Show Title:" + show.Title);
    System.out.println("Series Videos:" + show.Videos.size());
    System.out.println("Season Videos:" + show.SeasonVideos.size());
    System.out.println("Episode Videos:" + show.EpisodeVideos.size());
    
    }
}
Coming Soon!
                                  
Coming Soon!