Entertainment API Docs
General Information
The Entertainment API contains all the metadata about Origin Nexus'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 Origin Nexus 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 Origin Nexus 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 Origin Nexus 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.
You can find our Initial Ingest Documentation here. In order to keep a local cache of data synchronized with Origin Nexus, we recommend the following steps (using the Entertainment Search endpoint).
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" 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 . 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 10 items: Take=10
https://ee.iva-api.com/api/Entertainment/Search/?Take=10
&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=10
&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.
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}
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=10
&ShowId=Show/850
&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=10
&PeopleIds=Person%2F725
&ProgramTypes=Movie,Show
&Includes=Videos,Images
&subscription-key={YourKey}
Type field
This is a third party added field, used when data is available. Given the value null or blank, it means it is unknown.
Shows:
Scripted: television programs that follow a script, usually starring professional actors; reference: https://en.wikipedia.org/wiki/Television_show
Reality: television programs that document purportedly unscripted real-life situations, often starring ordinary people rather than professional actors; reference: https://en.wikipedia.org/wiki/Reality_television
Documentary: non-fiction television program that explores a specific topic or subject in depth; reference: https://en.wikipedia.org/wiki/Television_documentary
News: television program that delivers news reports to the public; reference: https://en.wikipedia.org/wiki/News_broadcasting
Talk Show: television program where a host engages in conversation with guests; reference: https://en.wikipedia.org/wiki/Talk_show
Game Show: television program where contestants compete in a game for rewards; reference: https://en.wikipedia.org/wiki/Game_show
Soap / Soap operas: television programs that serialize drama that typically revolve around the personal and interpersonal lives of a group of characters; reference: https://en.wikipedia.org/wiki/Soap_opera
Movies:
Movie: associated with theatrical release movies
TV Movie: associated with originally released for tv or VOD releases (if never released theatrically) movies
Video Movie: associated with one off programs, typically direct video
TV Special: associated with seasonal or standalone programs; reference: https://en.wikipedia.org/wiki/Television_special
Last updated