Autocomplete
Predicts search words or phrases for select areas of Rovi Cloud Services and returns results based on popularity and the filters specified in the request.
Syntax
endpoint/autocomplete?apikey=apikey&sig=sig&entitytype=entitytype&query=query [&clu=clu] [&filter=filter] [&format=format] [&country=country] [&language=language] [&size=size]
Request Example 1
- Predict a search for a person involved in music from the character e.
Request Example 2
- Predict a search for an upcoming movie on Time Warner Cable in Beverly Hills from the characters ma.
Request Example 3
- Predict a search for a movie from the characters the end.
Request Example 4
- Predict a search for a one-time TV program from the characters hou, in an XML response.
Request Example 5
- Predict a search for a person involved in television from the characters will, in an XML response.
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. |
| clu | No | Service ID of a television service to match program titles against. Service IDs for television services are available with calls to Services. Notes:
- Requires an endpoint of video.
- To check multiple television services, specify multiple parameters like this: clu=360861&clu=20494.
- To return only titles of programs in the broadcast time window, add filter=availability to the request.
- 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
|
| country | No | Country the language parameter applies to. The current release of the API supports only US. |
| filter | No | If you specify the clu parameter, filter filters out content that is not found on the television service channel lineup. Specified with a value of availability, like this: filter=availability. |
| 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:
- application/xml
- application/json
If you specify both, the format parameter overrides the Accept header. |
| 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
| Response | Type | Description |
|---|
| controlSet | ControlSet | The HTTP response status. |
| id | string | Server transaction ID for the response. |
Response for Autocomplete
| Response | Type | Description |
|---|
| results | string [ ] | List of most popular searches for the query entered. Results change over time as popularity changes. |
Response Example 1
- Here's a response to Request Example 1, which predicts a search for a person involved in music from the letter e. Results are ordered by filters and popularity, so results change over time.
- Requested with http://api.rovicorp.com/search/v2.1/music/autocomplete?apikey=apikey&sig=sig&
entitytype=artist&size=10&query=e.
{
"autocompleteResponse":{
"meta:id":"tul1cpgpsrapp3:gwy:3r1epl",
"controlSet":{
"status":"ok",
"code":200,
"messages":null
},
"results":[
"Ellie Goulding",
"Eminem",
"Emeli Sandé",
"Eric Church",
"El Toro Negro",
"Elton John",
"Elvis Presley",
"Evans, Sara",
"Emmylou Harris",
"Ellington, Duke"
]
}
}
Response Example 2
- Here's a response to Request Example 2, which predicts a search for an upcoming movie on Time Warner Cable in Beverly Hills from the characters ma.
- Requested with http://api.rovicorp.com/search/v2.1/video/autocomplete?apikey=apikey&sig=sig&
entitytype=movie&clu=360861&filter=availability&query=ma.
{
"autocompleteResponse":{
"meta:id":"tul1cpgpsrapp15:gwy:3nc7fk",
"controlSet":{
"status":"ok",
"code":200,
"messages":null
},
"results":[
"Martha Marcy May Marlene",
"Margin Call",
"The Master",
"Master and Commander: The Far Side of the World",
"Madagascar 3: Europe's Most Wanted",
"MASH",
"Margaret",
"Man on a Ledge",
"Marty",
"Magic of Ordinary Days",
"The Mask",
"Married to the Mob",
"Mama",
"The Man With the Iron Fists",
"Mask",
"Man of the House",
"Margot at the Wedding",
"Marley & Me",
"Man of the West",
"Mad Money"
]
}
}
Response Example 3
- Here's a response to Request Example 3, which predicts a search for a movie from the characters the end.
- Requested with http://api.rovicorp.com/search/v2.1/amgvideo/autocomplete?apikey=apikey&sig=sig&
entitytype=movie&size=10&query=the+end.
{
"autocompleteResponse":{
"meta:id":"tul1cpgpsrapp7:gwy:3nv0vg",
"controlSet":{
"status":"ok",
"code":200,
"messages":null
},
"results":[
"The End of the World",
"The End of Time",
"The End",
"The End of the Affair",
"The End of Poverty?",
"The Endless Game",
"The End of Day",
"The End of Innocence",
"The End of Love",
"The End of the Trail"
]
}
}
Response Example 4
- Here's a response to Request Example 4, which predicts a search for a one-time TV program from the characters hou, in an XML response.
- Requested with http://api.rovicorp.com/search/v2.1/video/autocomplete?apikey=apikey&sig=sig&
entitytype=onetimeonly&size=10&format=xml&query=hou.
<autocompleteResponse xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="com.rovicorp.metadataservice" xmlns:meta="com.rovicorp.metadataservice" meta:id="tul1cpgpsrapp14:gwy:3lszpt">
<controlSet>
<status>ok</status>
<code>200</code>
<messages i:nil="true" />
</controlSet>
<results>
<result>Housefly: Everyday Monster</result>
<result>A House Divided</result>
<result>House of Life</result>
<result>Houdini: The Great Escape</result>
<result>House Agriculture Subcommittee: 2013 Farm Bill: Energy & Forestry Conservation</result>
<result>House Agenda for Appropriations and Temporary Spending</result>
<result>House Oversight and Government Reform Subcommittee: Transition of Control in Iraq</result>
<result>House Leadership on Legislative Schedule</result>
<result>House and Senate Race Results</result>
<result>House Democrats Retreat Presser</result>
</results>
</autocompleteResponse>
Response Example 5
- Here's a response to Request Example 5, which predicts a search for a person involved in television from the characters will, in an XML response.
- Requested with http://api.rovicorp.com/search/v2.1/video/autocomplete?apikey=apikey&sig=sig&
entitytype=credit&size=10&format=xml&query=will.
<autocompleteResponse xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="com.rovicorp.metadataservice" xmlns:meta="com.rovicorp.metadataservice" meta:id="tul1cpgpsrapp19:gwy:3qeaq2">
<controlSet>
<status>ok</status>
<code>200</code>
<messages i:nil="true" />
</controlSet>
<results>
<result>Robin Williams</result>
<result>Will Forte</result>
<result>Willa Holland</result>
<result>Will Ferrell</result>
<result>Michelle Williams</result>
<result>William Hurt</result>
<result>William H. Macy</result>
<result>Will Smith</result>
<result>Bruce Willis</result>
<result>Willem Dafoe</result>
</results>
</autocompleteResponse>
Error Codes
| Code | Description |
|---|
| 400 | Incorrect or invalid request. The reason is shown in the Message object in ControlSet. |
See Also
-
↑ Top