General Information

The Entertainment API contains all the metadata about IVA's movie, TV, and game titles. This is the main API developers will work with to ingest and update the metadata available to them via their subscription.

Each subscription is tied to a solution and that solution contains the entirity or a subset of the IVA database. No matter which solution is right for you the implementation will be the same.

The Entertainment API contains endpoints that allow you to run searches or matching against the IVA Entertainment database.

/Entertainment/Search/ Allows you to make simple or complex searches for programs included in your solution.
/Entertainment/Match/ Allows you to take your own data and match it to the titles in your IVA solution. Any titles not included in your solution will not return any data.

Review the examples below to see how to work with the Entertainment API. All metadata and images are intended to be ingested and cached by the customer. Only data records included in your soulution will be returned by the API. If you have any questions please reach out to our support team.

In order to keep a local cache of data synchronized with IVA, we recommend the following steps.

  1. Decide on the data you want to store. Ex: Movies, Shows, Seasons, Episodes, and Game including Descriptions, Releases, Availabilities, etc.
  2. Make the appropriate request to the search endpoint with selecting the data you want and page through the entire data set, keeping track of the time you started.
  3. Once you have stored the data (we suggest storing it in the same form) you should retrieve changes to the data regularly. This could be hourly, daily, whatever meets your needs. It is this step that we recommend handling ingesting images. To do this, you can use the ModifiedRecordsSince parameter passing the date and time of your last update. This will limit the results to only the records that have something changed since that date-time. Additionally, set the parameter IncludeDeleted to true which will return records that have been removed. Using the deleted property in the returned record will determine if the record should be purged from your cache. Important: Since Seasons and Episode Records are child records of Show records, if a Show is deleted, all of the episode and season records under the Show should also be removed from your cache. Episode and Season records are not soft-deleted but rather hard-deleted (removed entirely).

NOTE: In order to specify the response content type, you can use the "format" parameter in your query and pass "json", "xml", "csv", or "html".


Open API/Swagger documentation can be found on the Entertainment API page.


Get All Movie Metadata Records

Get all movie metadata records with paging.

Filter results where ProgramTypes=Movie

Include extra data: Includes=Videos,Images,Descriptions

Paging: Skip=0, Take=50

https://ee.iva-api.com/api/Entertainment/Search/?
      Skip=0
      &Take=50
      &ProgramTypes=Movie
      &Includes=Videos,Images,Descriptions
      &subscription-Key={YourKey} 

Changed Data Since

Retrieve all programs that have changed since a certain date-time.

Filter results where ProgramTypes=Movie,Show

Include deleted for updating.

Include extra data: Includes=Videos,Releases

Paging: Skip=0, Take=10

https://ee.iva-api.com/api/entertainment/Search/?
      Skip=0
      &Take=10
      &ModifiedRecordsSince=2018-06-11%2004:05%20PM
      &Includes=Releases,Videos
      &IncludeDeleted=true
      &ProgramTypes=Movie,Show
      &subscription-key={YourKey} 

Movies Coming Soon to Theaters with Video

Retrieve all movies with more than one video with a Theatrical Wide Release in US greater than a specific date.

Filter results where ProgramTypes=Movie and ReleaseTypes=Theatrical_Wide_Release and HasVideo=true

Include extra data: Includes=Videos,Images,Descriptions

Paging: Skip=0, Take=10

https://ee.iva-api.com/api/entertainment/Search/?
      Skip=0
      &Take=10
      &ProgramTypes=Movie
      &ReleaseTypes=Theatrical_Wide_Release
      &ReleaseCountries=US
      &ReleaseDateRange_Start=2018-07-12
      &Includes=Videos,Images,Descriptions
      &HasVideo=true
      &subscription-key={YourKey} 

Get all seasons and episodes for a Show

Use the ShowId returned in a Show to get seasons and episodes. This will take at least 2 additional requests.

Step 1: Get a Show.

Ids = Show/850

Paging: Skip=0, Take=1

https://ee.iva-api.com/api/entertainment/Search/?
      Skip=0
      &Take=1
      &Ids=Show/850
      &subscription-key={YourKey} 

Step 2: Using the ShowId, get the seasons and episodes.

ShowId = Show/Id

ProgramTypes = Season,Episode.

https://ee.iva-api.com/api/entertainment/Search/?
      Skip=0
      &Take=50
      &ShowId=Show/850
      &subscription-key={YourKey} 

Games released this year

Retrieve all Game programTypes with a Year greater than or equal to 2018.

Filter results where ProgramTypes=Game and YearRange_Start = 2018

Include extra data: Includes=Videos

Paging: Skip=0, Take=10

https://ee.iva-api.com/api/entertainment/Search/?
      Skip=0
      &Take=10
      &ProgramTypes=Game
      &YearRange_Start=2018
      &Includes=Videos
      &subscription-key={YourKey} 
Get Filmography for a Celebrity

Retrieve all movie and show programs that have Id Person/725 (Chris Pratt).

Filter results where ProgramTypes= Movie,Show

Include extra data: Includes=Videos,Images

Paging: Skip=0, Take=50

https://ee.iva-api.com/api/Entertainment/Search/?
      Skip=0
      &Take=50
      &PeopleIds=Person%2F725
      &ProgramTypes=Movie,Show
      &Includes=Videos,Images
      &subscription-key={YourKey}