Returns the content that is most relevant to a characteristic of TV, movie, or music entertainment. Results change over time with the changing content and popularity of entertainment.
|&apikey=apikey&sig=sig& entitytype=entitytype [&filter=filter] [&include=include] [&formatid=formatid] [&format=format] [&country=country] [&language=language] [&size=size]|
♫ Music-related requests 日 Movie-related requests ⊑⊒ TV-related requests
|apikey||Yes||Access code that authorizes your request for data from Rovi.|
|endpoint||Yes|| Database to search.
|entitytype||Yes|| Type of content to return.
To return data from multiple entity types within an endpoint, specify multiple entitytype parameters like this: entitytype=tvseries&entitytype=movie. Note: The top results may come from just one of the entity types. Order of results is determined by relevance and is not deliberately balanced across the entity types.
|sig||Yes|| A calculated authorization code. To perform the calculation, execute the MD5 function on the concatenation of the following three strings:
Perform the calculation at the time of each request to be sure it's within a five-minute window of the server time. If you're testing the call in a browser, use our online signature generator to perform the calculation.
|attributeid||Conditional|| Rovi Music ID for a music mood, style, theme, genre, or subgenre. Attribute IDs consist of the prefix MA or XA followed by a ten-digit number, specified like this: attributeid=MA0000002504 or attributeid=XA0000001029.
For a list of music moods, see the Music Moods table.
For a list of music themes, see the Music Themes table.
For a list of music genres, subgenres, and styles, call Descriptor/MusicGenres.
You can also grab attribute IDs from responses to the following requests:
Condition: Required for and limited to an endpoint of music.
|descriptorid||Conditional|| A Rovi DVDs ID for a genre or subgenre that applies to movies or TV series.
Descriptor IDs consist of the letter D followed by 6 digits with leading spaces. When using a descriptor ID in a request, replace any spaces in the ID with plus (+) or percent20 (%20) symbols, like this: D+++646.
For a list of those genre and subgenre IDs, call Descriptor/MovieGenres. You can also grab genre and subgenre IDs from responses to the following requests:
Condition: Required for and limited to an endpoint of amgvideo.
|keywordid||Conditional|| Rovi Video ID for a keyword that applies to movies or TV programs.
Condition: Required for and limited to an endpoint of video.
|country||No||Country the language parameter applies to. The current release of the API supports only US.|
|filter||No|| Field content that determines which results are returned. Like a WHERE clause in an SQL statement, this parameter selects only results with fields that meet your criteria.
This parameter requires an endpoint of video.
The selection operators include:
For the And operation, specify another filter parameter like this: filter=releaseyear>:2004&filter=releaseyear<2009.
The following shows which fields you can select for each video entity type. If you specify a filter that does not apply to an entity type, no data will be returned for that entity type.
|format||No|| Format of the returned data: json or xml. The default is JSON.
Alternatively you can specify the response format in an HTTP Accept header with either of these Accept field content types:
If you specify both, the format parameter overrides the Accept header.
|formatid||No|| If you specify All or Images in the include parameter, formatid specifies the size and file format of returned images. Select the format IDs you want from the Format IDs table.
Specify multiple format IDs in a comma-separated list, like this: formatid=36,44,51.
|include||No|| Additional data to include in each result returned. To include cast members in movie results, for example, specify include=cast. For multiple includes, separate the values with commas like this: include=moods,crew. To include all data, specify include=all.
|language||No||Language of the response data. This request supports only en (English).|
|size||No||The number of items you want to be returned. The default is 20.|
|controlSet||ControlSet||The HTTP response status.|
|id||string||Server transaction ID for the response.|
|results||result [ ]||The entertainment content relevant to the characteristic specified in the request, listed in order of most-to-least relevance.|
|totalResultCounts||integer||Number of items available to be returned for the request.|
|400||Incorrect or invalid request. The reason is shown in the Message object in ControlSet.|