General Information

The Entertainment API contains all the metadata about Fabric Origin'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 entirety or a subset of the Fabric Origin 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 Fabric Origin 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 Fabric Origin solution. Any titles not included in your solution will not return any data. See the Metadata Match Guide for more details.

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 solution 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 Fabric Origin, we recommend the following steps (using the Entertainment Search endpoint).

1. Initial Ingestion

   • Determine which Program Types (Movies, Shows, Seasons, Episodes, and/or Games) you want to store. If you would like to limit the types returned, pass a comma-separated list to the ProgramTypes parameter.

   • Determine which sub-objects (Descriptions, Releases, Contributors, ProgramTrends, Themes, etc.) you would like included nested in your Entertainment Programs (NOTE: It is recommended to only request what you need, the more sub-objects included, the more of a potential performance impact on the responses.). Pass a comma-separated list of these sub-objects to the Includes parameter.

   • Paginate through the entire dataset (using the "Paging Greater than 10,000 Items with NextPageToken" guidance below) and keep track of exactly when you started.

2. Regular Data Updates

   • Once you have established your initial data storage (we recommend storing the items in their original form) you should retrieve changes to the data regularly (whatever meets your needs from hourly to daily, etc.).

   • Pass the datetime of the beginning of your last update to the ModifiedRecordsSince parameter to receive back only the items that have changed since that datetime. (NOTE: The "Modified" field in the response only reflects changes to the top-level object whereas the "Timestamp" field represents changes to ANY part of the program - the ModifiedRecordsSince parameter uses the "Timestamp" field.)

   • 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) so their absence indicates that they should be purged from your cache.

   • Paginate through the returned dataset of changed items (using the "Paging Greater than 10,000 Items with NextPageToken" guidance below if needed) and keep track of exactly when you started.

   • Repeat this process on your schedule.

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

Related API Guides: Metadata Match Guide, Trending On Guide, Celebrity API, Video API, Image API

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

Paging Greater than 10,000 Items with NextPageToken

In order to improve performance and streamline ingestion, any requests that return more than 10,000 items will not allow paging beyond 10,000 using the Skip and Take parameters.

The improved alternative is the NextPageToken, which is returned at the top-level of any queries utilizing "TimeStamp", "TimeStampAsc", "ReleaseDate", or "IvaRating" for the SortBy parameter (one of these MUST be passed to SortBy to use this method).

The NextPageToken in the response can be passed to the NextPageToken parameter coupled with the Take in order to receive back the next page of results (the Skip parameter is ignored if passed). This can be used to paginate through an entire result set, regardless of its size.

In the example response below, we passed the following parameters:

Include extra data: Includes=Videos,Images,Descriptions

Sort data by TimeStampAsc: SortBy=TimeStampAsc

Get back 50 items: Take=50

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

Contained in the response will be a NextPageToken such as the example below:

"NextPageToken":"eyJTb3J0IjoiVGltZVN0YW1wQXNjIiwiU29ydFZhbHVlIjoiMjAxNi0wMy0xNVQxNTo0MTowMC4wMDAwMDAwWiIsIlRpZUJyZWFrZXIiOiIyMDE1LTEyLTA4VDEyOjIwOjAwLjAwMDAwMDBaIn0="

In order to get the next page of results, we will pass this value to the NextPageToken parameter, leaving all other parameters the same.

https://ee.iva-api.com/api/Entertainment/Search/?Take=50 
&SortBy=TimeStampAsc 
&Includes=Videos,Images,Descriptions 
&NextPageToken=eyJTb3J0IjoiVGltZVN0YW1wQXNjIiwiU29ydFZhbHVlIjoiMjAxNi0wMy0xNVQxNTo0MTowMC4wMDAwMDAwWiIsIlRpZUJyZWFrZXIiOiIyMDE1LTEyLTA4VDEyOjIwOjAwLjAwMDAwMDBaIn0= 
&subscription-Key={YourKey}

Continue to fetch the new NextPageToken on the current page of results and pass it to the NextPageToken parameter to continue to paginate.

Changed Data Since

Retrieve all programs that have changed since a certain datetime.

NOTE: The "Modified" field in the response only reflects changes to the top-level object whereas the "Timestamp" field represents changes to ANY part of the program - the ModifiedRecordsSince parameter uses the "Timestamp" field.

Filter results where ProgramTypes=Movie,Show

Include deleted for updating.

Include extra data: Includes=Videos,Releases

Paging: Skip=0, Take=10

The ProgramChangeEntities parameter may also be used to specify what part(s) of the program had been changed. Look for any movies/shows with a newly added trailer, for example. Alternatively, if you are interested in all program change entities except for availabilities, you simply need to select all the ProgramChangeEntities except availabilities.

Here is where you will find the list of ProgramChangeEntities values. Scroll down until you see the ProgramChangeEntities parameter.

The following example will demonstrate how to fetch a list of Movies and Shows with newly added video(s) since 2023-02-08.

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

There are about 30,000 changes on average per day in our database. In an effort to reduce the count of records to evaluate for changes we have added ProgramChangeEntities filtering to allow you to select what specific changes you are interested in.

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}