Advanced Predictive Search
This request offers insight into some of the custom capabilities available from Rovi Advanced Search. This is one of several Advanced Search requests that show how Rovi can return entertainment content customers are looking for.
Advanced Predictive Search can suggest search words or phrases based on the following filters specified in the request, including the following which are unique to Rovi Advanced Search:
- Additional field-level filters
- Priority settings such as hot, new, fresh, or all-time
Note: The more parameters added to this request, especially boost parameters, the less instantaneous the response.
Syntax
endpoint/autocomplete?apikey=apikey&sig=sig&query=query&entitytype=entitytype [&available‑clu=available‑clu] [&available‑start=available‑start] [&available‑end=available‑end] [&boost=boost] [&filter=filter] [&format=format] [&size=size]
Request Example 1
- Suggest names of hot movies starting with the letter s that first aired after 2010 and are showing on Time Warner Cable in Beverly Hills, California.
Request Example 2
- Suggest names of all-time best songs with a dramatic mood that contain the word love.
Request Example 3
- Suggest names of new albums in the blues genre that contain the word help.
Request Parameters
♫ 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.
| To search in . . . | Specify this endpoint. |
| music | music ♫ |
| movies and TV series (our DVD database) | amgvideo 日 |
| television (our international TV schedule database) | video ⊑⊒ |
|
| entitytype | Yes | Type of content to search for.
| In this endpoint . . . | To search in this area . . . | Specify this entitytype. |
| music ♫ | songs | song |
| | albums | album |
| | compositions | composition |
| | people working in music | artist |
| amgvideo 日 | movies | movie |
| | TV series | tvseries |
| | people working in TV or movies | credit |
| video ⊑⊒ | movies | movie |
| | TV series | tvseries |
| | episode titles | episode |
| | TV programs | onetimeonly |
| | people working in TV or movies | credit |
|
| query | Yes | The search string. Replace spaces with plus (+) or percent20 (%20) symbols. Character case does not affect the results (search is not case-sensitive). |
| 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:
- Your API key.
- The secret key you received with your API key.
- The Unix time. Unix time is a timestamp supported in most development environments, and is generally defined as the number of seconds since January 1, 1970 00:00:00 GMT.
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. |
| available-clu | No | Service ID of a television service to match against. Specified like this: available‑clu=360861. Notes:
- Requires an endpoint of video.
- To check multiple television services, specify multiple parameters like this: available‑clu=360861&available‑clu=20494.
- To limit the broadcast time window to less than the next two weeks, specify the available‑start or available‑end parameters, or both.
- To return only programs title in the broadcast time window, add boost=availability or filter=availability to the request.
- Service IDs for television services are available with calls to Services. Here are some Service IDs you can use for evaluation tests:
- 20419 — Chicago Area Broadcast TV
- 890504 — CanalSat in Paris, France
- 68809 — Shaw Cable in Moose Jaw, Saskatchewan
- 60795 — Time Warner Cable in Southern Manhattan
- 360861 — Time Warner Cable in Beverly Hills, California
|
| 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:
- UTC time: YYYYmmDDhhMMssZ. For example: 20120315140000Z for 2012-03-15 14:00:00 GMT.
- Local time with a UTC offset: YYYYmmDDhhMMss + or - hhMM (positive or negative offset). For example, for the same time specified as US Pacific time: 20120315060000‑0800.
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:
- UTC time: YYYYmmDDhhMMssZ. For example: 20120315140000Z for 2012-03-15 14:00:00 GMT.
- Local time with a UTC offset: YYYYmmDDhhMMss + or - hhMM (positive or negative offset). For example, for the same time specified as US Pacific time: 20120315060000‑0800.
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:
| Factor | Meaning |
|
hot content
recent original release date
new episodes in a TV series
all-time popularity
|
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. |
| 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.
The selection operators include:
| Operator | Meaning |
| : | Is equal to. |
| !: | Is not equal to. |
| < | Is less than. |
| <: | Is less than or equal to. |
| > | Is greater than. |
| >: | Is greater than or equal to. |
| | | Or. |
The following shows which fields you can select.
| You can filter on | Description |
| Filters out content that is not found in available‑clu. Specified without a value, like this: filter=availability. |
| Filters out content based on the most recent date that a movie or TV series was broadcast (YYYYMMDD). For example, to return only shows broadcast in 2010 or later, specify: filter=latestairing>20091231. This filter requires an endpoint of video and an entitytype of movie or tvseries. |
|
| format | No | Format of the returned data: json or xml. The default is XML.
Alternatively you can specify the response format in an HTTP Accept header with either of these Accept field content types:
- application/xml
- application/json
If you specify both, the format parameter overrides the Accept header. |
| size | No | The number of items you want to be returned. The default is 20. |
Response
| Response | Type | Description |
|---|
| controlSet | ControlSet | The HTTP response status. |
| id | string | Server transaction ID for the response. |
Response for Advanced Predictive Search
| Response | Type | Description |
|---|
| results | string [ ] | List of most popular searches. Results change over time as content and popularity changes. |
JSON Response Example
- Here's the response to a request that asks for names of hot movies starting with the letter h that are showing on Time Warner Cable in Beverly Hills, California.
- Requested with http://api.rovicorp.com/snrpreview/v2.1/video/autocomplete?apikey=apikey&sig=sig&
entitytype=movie&boost=hot:0.9&available-clu=360861&filter=availability&size=10&format=json&query=h.
{
"autocompleteResponse":{
"meta:id":"tul1cpgpsrapp9:gwy:3oneeh",
"controlSet":{
"status":"ok",
"code":200,
"messages":null
},
"results":[
"Happy Face Killer",
"Harry Potter and the Deathly Hallows, Part 2",
"The Hobbit: An Unexpected Journey",
"Hitchcock",
"Hello I Must Be Going",
"The Hangover Part III",
"The Heat",
"Hotel Transylvania",
"Horrible Bosses",
"The Hangover Part II"
]
}
}
Error Codes
| Code | Description |
|---|
| 400 | Incorrect or invalid request. The reason is shown in the Message object in ControlSet. |
See Also
↑ Top