Locates content in Rovi Cloud Services based on field-level criteria and returns results listed in order of relevance. Relevance is a calculated score based on usage data and editorial weighting.
A FilterBrowse request is a Search request without the query. Use FilterBrowse to present custom views of music, movies, or TV, and let the user browse areas of interest and select content.
This request returns a large amount of data, especially if you use the include parameter to return additional data. To speed data transmission, do the following:
endpoint/filterbrowse?apikey=apikey&sig=sig&entitytype=entitytype [&filter=filter] [&include=include] [&facet=facet] [&format=format] [&clu=clu] [&start=start] [&end=end] [&rep=rep] [&country=country] [&language=language] [&offset=offset] [&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 to search.
| |||||||||||||||||||||||||||||||||||||||||||
| entitytype | Yes | Type of content to search 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. | |||||||||||||||||||||||||||||||||||||||||||
| 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 more than one broadcast time, specify the rep parameter. Notes:
| |||||||||||||||||||||||||||||||||||||||||||
| country | No | Country the language parameter applies to. The current release of the API supports only US. | |||||||||||||||||||||||||||||||||||||||||||
| end | No | If you specify the clu parameter, 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. | |||||||||||||||||||||||||||||||||||||||||||
| facet | No | Count of items available to be returned.
| |||||||||||||||||||||||||||||||||||||||||||
| 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.
Examples:
The selection operators include:
For the And operation, specify another filter parameter like this: filter=releasedate>:20070101&filter=releasedate<20080101. A request can contain up to 20 filter parameters. The following shows which fields you can select for each entity type. If you specify a filter that does not apply to an entity type, no data will be returned for that entity type.
* Note: The availability filter is specified without a value, like this: filter=availability. Use this to filter out movies or TV series that are not airing on the television service specified by the clu parameter. | |||||||||||||||||||||||||||||||||||||||||||
| 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. | |||||||||||||||||||||||||||||||||||||||||||
| 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). | |||||||||||||||||||||||||||||||||||||||||||
| offset | No | Counting from zero as the first item in the returned list, the number of the first item you want. The default is zero. The maximum is 3000.
Use the offset and size parameters to paginate the available results. | |||||||||||||||||||||||||||||||||||||||||||
| rep | No | If you specify the clu parameter, rep specifies the maximum number of broadcasts to be reported in the availabilities object. For example, to return up to five broadcasts during the time specified, specify rep=5. Default is 1. | |||||||||||||||||||||||||||||||||||||||||||
| size | No | The number of items you want to be returned. The default is 20. | |||||||||||||||||||||||||||||||||||||||||||
| start | No | If you specify the clu parameter, 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. | |||||||||||||||||||||||||||||||||||||||||||
| Response | Type | Description |
|---|---|---|
| controlSet | ControlSet | The HTTP response status. |
| id | string | Server transaction ID for the response. |
| Response | Type | Description |
|---|---|---|
| facetCounts | facetCounts [ ] | Number of results available to be returned in each genre or entity type, as requested by the facet parameter. |
| results | result [ ] | The results listed in order of popularity and similarity and the filters specified in the request. |
| totalResultCounts | integer | Total number of results found. |
| Code | Description |
|---|---|
| 400 | Incorrect or invalid request. The reason is shown in the Message object in ControlSet. |