This request offers insight into some of the custom capabilities available from Rovi Advanced Recommendations. This is one of several requests that show how Rovi can generate entertainment recommendations for your customers.
Advanced Item-Based Recommendations returns items that are similar to an item specified in the request in order of similarity and the priorities specified in the request parameters, including the following which are unique to Rovi Advanced Recommendations:
| endpoint/similar? | nameid=nameid trackid=trackid albumid=albumid amgvideoid= amgvideoid cosmoprogramid= cosmoprogramid |
&apikey=apikey&sig=sig&entitytype=entitytype [&include=include] [&filter=filter] [&boost=boost] [&available‑clu=available‑clu] [&available‑start=available‑start] [&available‑end=available‑end] [&format=format] [&country=country] [&language=language] [&size=size] |
♫ Music-related requests 日 Movie-related requests ⊑⊒ TV-related requests
| Parameter | Required | Description | |||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| apikey | Yes | Access code that authorizes your request for data from Rovi. | |||||||||||||||||||||||||||||||||||||||||||
| endpoint | Yes | Database of the item.
| |||||||||||||||||||||||||||||||||||||||||||
| entitytype | Yes | Type of content to look for.
| |||||||||||||||||||||||||||||||||||||||||||
| sig | Yes | A calculated, 32-hex-digit authorization code. To perform the calculation, execute the MD5 function on the concatenation of the following three ASCII strings:
Express the alpha hex digits as lower case. 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. | |||||||||||||||||||||||||||||||||||||||||||
| albumid | Conditional | Rovi Music ID for an album, consisting of the prefix MW followed by a ten-digit number. For a request with an album ID, specify an endpoint of music. Here are some album IDs you can use for evaluation tests:
Condition: The request must contain just one of these parameters:
| |||||||||||||||||||||||||||||||||||||||||||
| amgvideoid | Conditional | All Media Guide (AMG) database ID for a movie or TV series, consisting of a ten-character string that starts with V and is followed by 9 digits with leading spaces. For a request with an amgvideo ID, specify an endpoint of amgvideo. Here are some amgvideo IDs you can use for evaluation tests:
Condition: The request must contain just one of these parameters:
| |||||||||||||||||||||||||||||||||||||||||||
| cosmoprogramid | Conditional | Cosmo database ID for a movie or television series. For a request with a Cosmo ID, specify an endpoint of video. Here are some Cosmo IDs you can use for evaluation tests:
Condition: The request must contain just one of these parameters:
| |||||||||||||||||||||||||||||||||||||||||||
| nameid | Conditional | Rovi Name ID for a person or group that has worked in music, consisting of the prefix MN followed by a ten-digit number. For a request with a name ID, specify an endpoint of music. Here are some name IDs you can use for evaluation tests:
Condition: The request must contain just one of these parameters:
| |||||||||||||||||||||||||||||||||||||||||||
| trackid | Conditional | Rovi Music ID for a song, consisting of the prefix MT followed by a ten-digit number. For a request with a track ID, specify an endpoint of music. Here are some track IDs you can use for evaluation tests:
Condition: The request must contain just one of these parameters:
| |||||||||||||||||||||||||||||||||||||||||||
| available-clu | No | Service ID of a television service that has upcoming movies or TV series you want to match against. Service IDs for television services are available with calls to Services.
Broadcast times of programs are returned in availabilities objects. To return multiple broadcast times, specify the maximum number of broadcasts as serviceID,number like this: available‑clu=360861,5. Notes:
| |||||||||||||||||||||||||||||||||||||||||||
| available-end | No | If you specify the available‑clu parameter, available‑end specifies the end of the broadcast time window in one of the following formats:
If not specified, the end time is two weeks after the time of the request. | |||||||||||||||||||||||||||||||||||||||||||
| available-start | No | If you specify the available‑clu parameter, available‑start specifies the start of the broadcast time window in one of the following formats:
If not specified, the start time is the time of the request. | |||||||||||||||||||||||||||||||||||||||||||
| boost | No | Sort-order priorities you can increase or decrease by a decimal value between -1 and 1. To boost the priority of new content by 50%, for example, specify boost=new:0.5. The priorities you can increase and decrease are:
To boost multiple factors, specify multiple parameters: boost=new:0.5&boost=alltime:‑0.4. Note: The sum of the absolute values of all factors must be less than or equal to 1. That is, add all of the absolute values together and make sure the total is less than or equal to 1. If you are using the available-clu parameter, you can also use the boost parameter to filter out results that are not available on the television service. Specified without a value, like this: boost=availability. | |||||||||||||||||||||||||||||||||||||||||||
| 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 only filters content with a video endpoint.
Examples:
The selection operators include:
For the And operation, specify another filter parameter like this: filter=releaseyear>:2004& 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. | |||||||||||||||||||||||||||||||||||||||||||
| 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. | |||||||||||||||||||||||||||||||||||||||||||
| Response | Type | Description |
|---|---|---|
| controlSet | ControlSet | The HTTP response status. |
| id | string | Server transaction ID for the response. |
| Response | Type | Description |
|---|---|---|
| results | result [ ] | Information about items that are similar to the items specified in the request, listed in order of similarity and the priorities specified in the request. |
| Code | Description |
|---|---|
| 400 | Incorrect or invalid request. The reason is shown in the Message object in ControlSet. |