General Information

The Trending On content is an enrichment of the metadata in the Entertainment API with the newest trends in the entertainment industry. Use this metadata to create charts, stack your search results by what is hot, make sure the best content is in front of your clients, and so much more!

Review the definitions and examples below to see how to work with the Trending On data within the Entertainment API. If you have any questions please reach out to our support team.

Related API Guides: Entertainment API

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

Entertainment Search Parameters

The Entertainment Search endpoint has several parameters offering options to explore the Trending On metadata. Those parameters are detailed below:

TrendSourceIds - A comma-separated list of TrendSourceIds that allows you to create a "Trend Recipe" by selecting which Trend Source lists you would like to be included to form the list of programs returned in the API response. See below for details on the Trend Sources.

TrendBrands - A comma-separated list of TrendBrands. These are the brands that are behind the Trend Source lists that power the Trending On data. The API interprets this selection as equivalent to selecting the TrendSourceIds of ALL Trend Source lists for that brand. See below for details on the Trend Sources.

TrendClassifiers - A comma-separated list of TrendClassifiers. These are the classifiers that describe the Trend Source lists that power the Trending On data. The API interprets this selection as equivalent to selecting the TrendSourceIds of ALL Trend Source lists for that classifier. Examples include "AVOD" and "Trailers". See below for details on the Trend Sources.

TrendCountries - A comma-separated list of TrendCountries. These are the countries from which the Trend Source lists that power the Trending On data originate. The API interprets this selection as equivalent to selecting the TrendSourceIds of ALL Trend Source lists for that country. NOTE: At launch, the only available option is "US". We may be adding select countries in the future.

SortBy=CalculatedTrendRank - A new option to pass to the SortBy parameter is called CalculatedTrendRank. This sorting algorithm takes into account each of the requested TrendSourceIds in your "Trend Recipe" (set by any of the parameters above) and calculates an average aggregate rank to sort the programs returned in the response. This algorithm makes use of a "max + 1" policy to assign a rank of the maximum rank + 1 per list for which a title is NOT present. (i.e. If you requested 8 Trend Source lists in your "Trend Recipe", when "Title X" is passed through the sorting algorithm if "Title X" is only on 7 of 8 lists then "Title X" will receive a rank of MaxRank+1 for the 8th list for purposes of calculation.) The titles will be returned in the order of their Calculated Trend Rank - the first program returned is Rank 1, the second Rank 2, etc. NOTE: This is a homebrew sorting algorithm that has produced some great results. However, the details of the ranking for each ProgramTrend list on each program will be included in the API response - feel free to design your own ranking system!

Entertainment Search Response - ProgramTrends

Making use of the "Includes" parameter of the Entertainment Search endpoint by setting "Includes=ProgramTrends" will return the ProgramTrends array on each program that is trending on at least one Trend Source list. An example of a ProgramTrends array in an API response is below:

"ProgramTrends": [
  { 
   "Id": 16, 
   "Name": "Youtube Hot New Trailers", 
   "Brand": "Youtube", 
   "Country": "US", 
   "Classifiers": [ "Trailers" ], 
   "Modified": "2019-04-04T00:00:00.0000000Z", 
   "Rank": 3, 
   "ListUrl": "https://www.youtube.com/playlist?list=PLrEnWoR732-CvU2EIng1mKhlXJHvaiAVM", 
   "TitleUrl": "https://www.youtube.com/watch?v=KCSNFZKbhZE" 
  } 
]

There are several metadata fields that make up a ProgramTrend object. They are described below:

Id - Integer representing the TrendSourceId of the Trend Source List.

Name - String representing the Name of the Trend Source List.

Brand - String representing the Brand behind the Trend Source List.

Country - 2-character string representing the Country in which the Trend Source List is based.

Classifiers - List of Strings representing the Classifiers of the Trend Source List.

Modified - Date representing the last date the Trend Source List was updated.

Rank - Integer representing the Rank the program occupies on the Trend Source List.

ListUrl - String representing the URL of the Trend Source List itself. NOTE: This field will not be present in the event the list is not accessible via a URL.

TitleUrl - String representing the URL of the program on the Trend Source list's site. NOTE: This field will not be present in the event the program is not accessible via a URL.

Trend Sources

There are many Trend Sources that power the lists behind the Trending On data. This list has the potential to grow and change so we have added an endpoint to the Common Metadata API called TrendSources. Use the query below to get the most up-to-date list of Trend Sources available.

https://ee.iva-api.com/api/Common/TrendSources/?subscription-key={YourKey}

The response will include top-level information on each Trend Source including Item Count, Id, Name, Brand, Classifiers, Modified, List Url, and an Active status.

NOTE: In the event a Trend Source is no longer being updated, the "Active" boolean found in this response will be set to "false" for that Trend Source. It is best practice to check this often.