Note: The information returned by this request is also returned by requests offered in our Name API Version 1.1. Because future API development around this information will be focused on the Name API, we now recommend using the Name API for future application development instead of this request.
Listings/CelebrityDetails returns information about a celebrity and can optionally include a schedule of upcoming broadcast appearances.
To include upcoming broadcasts, specify the service ID and then limit the results with the following optional parameters:
listings/celebritydetails/info?apikey=apikey&sig=sig&locale=locale&nameid=nameid& include=include [&includecreditsforepisode=includecreditsforepisode] [©type=copytype] [©textformat=copytextformat] [&imagecount=imagecount] [&imageformat=imageformat] [&imageformatid=imageformatid] [&imagehorizontalresolution=imagehorizontalresolution] [&imagetype=imagetype] [&imageverticalresolution=imageverticalresolution] [&serviceid=serviceid] [&sourceid=sourceid] [&startdate=startdate] [&duration=duration] [&inprogress=inprogress] [&format=format]
Click to re-sort
Parameter | Required | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apikey | Yes | Access code that authorizes your request for data from Rovi. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
include | Yes | Data to include in the response:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
locale | Yes | Language and country code of the television service. This is a case-sensitive combination of the ISO 639 language code, a hyphen character, and the ISO 3166 country code, as described in RFC 1766. Valid locales include:
* Includes Wales, Scotland, and Northern Ireland. Note 1: Locale determines the language of program titles and descriptions. If content is not available in that language, a fallback language is chosen according to rules shown in the Language Fallback Sequence table. Note 2: For locales fr-CA and fr-Fr, the following response elements are returned in French:
Note 3: If an invalid locale is specified, en-GB will be used. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nameid | Yes | Database ID of the celebrity. You can get celebrity IDs from responses to Listings/ProgramDetails requests with the include=Credit parameter. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sig | Yes | A calculated, 32-hex-digit authorization code. To perform the calculation, execute the MD5 function on the concatenation of the following three 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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
copytextformat | No | Format of the descriptions of programs, movies, and TV series: PlainText or HTML. Default is PlainText. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
copytype | No | Type of description you want returned for programs, movies, and TV series. If you specify a copy type that has no content, no description is returned.
If you do not specify a copy type, the description chosen is based on category, shown below, and the first copy type in the category that is available:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
duration | No | If you specify a serviceid to include a schedule of broadcasts the celebrity appears in, duration determines the number of minutes the schedule will cover. You can specify 1 to 20160; the default is 20160 (14 days).
Note: The schedule is determined by duration, inprogress, and startdate. A duration shorter than 5 minutes may miss shows starting just before or after a half-hour point. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
format | No | Format of the returned data: json or xml. Default is json. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
imagecount | No | If you request Images in the include parameter, imagecount determines the number of images returned in the Images element. The default is five.
Note: Images returned meet all of the image filters specified in the request:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
imageformat | No | If you request Images in the include parameter, imageformat specifies the file format of images returned in the Images element:
If you request Credits in the include parameter, images returned with credits are limited to image Format ID 34, which is PNG. Note: Images returned meet all of the image filters specified in the request:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
imageformatid | No | If you request Images in the include parameter, imageformatid determines the format ID of images returned in the Images element. Format IDs specify image sizes and file types. The possible image format IDs are shown in the Format IDs table.
Note 1: Images cannot be filtered by Image Format ID 0. Note 2: Images returned meet all of the image filters specified in the request:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
imagehorizontalresolution | No | If you request Images in the include parameter, imagehorizontalresolution determines the exact horizontal resolution (in pixels) of the images returned in the Images element. To return images that meet at least one vertical or horizontal resolution, use the imageformatid parameter instead.
If you request Credits in the include parameter, images returned with credits are limited to image Format ID 34. Note: Images returned meet all of the image filters specified in the request:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
imagetype | No | If you request Images in the include parameter, imagetype determines the type of images returned in the Images element. Image types, shown in the ImageType table, are case-sensitive. Specify spaces in an image type with a plus (+) or percent20 (%20) symbol, like this: imagetype=Gallery:+Key.
Note: Images returned meet all of the image filters specified in the request:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
imageverticalresolution | No | If you request Images in the include parameter, imageverticalresolution determines the exact vertical resolution (in pixels) of the images returned in the Images element. To return images that meet at least one vertical or horizontal resolution, use the imageformatid parameter instead.
If you request Credits in the include parameter, images returned with credits are limited to image Format ID 34. Note: Images returned meet all of the image filters specified in the request:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
includecreditsforepisodes | No | If you request Credits in the include parameter, includecreditsforepisodes determines whether credits for each episode in a series are returned in the response: true or false. Default is false. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
inprogress | No | If you specify a serviceid to include a schedule of broadcasts the celebrity appears in, inprogress determines whether shows that are in progress at the startdate are included in the schedule: true or false. Default is false.
Note: The schedule is determined by duration, inprogress, and startdate. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
serviceid | No | The television service. This must be specified if you want to return a schedule of upcoming broadcasts the celebrity appears in. You can return a list of television services offered to a community with a Listings/Services request. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourceid | No | If you specify a serviceid to include a schedule of broadcasts the celebrity appears in, sourceid determines the channel or channels that will appear on the schedule. You can get the source IDs for channels from responses to Listings/ServiceDetails.
To specify multiple channels, specify a comma-separated list, like this: sourceid=696,873,5,994. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
startdate | No | If you specify a serviceid to include a schedule of broadcasts the celebrity appears in, startdate determines the starting time of the schedule. The date and time must be specified as a DateTime value. The default is the time of the request.
Note: The schedule is determined by duration, inprogress, and startdate. Broadcast information is available for 14 days before and after the time of the request. |
Response | Type | Description |
---|---|---|
Build | String | Software build version of the API. |
EndTimestamp | DateTime | Time the server finished processing the request. |
Errors | Error [ ] | Processing errors or warnings. |
RequestId | String GUID | A generated value that identifies the request and response. |
Status | Status | Processing status, indicating whether the request was successfully processed. |
TimeStamp | DateTime | Time the server started processing the request. |
Response | Type | Description |
---|---|---|
Celebrity | Celebrity | Information about the celebrity. Not returned for the request parameter include=None. |
Schedule | LinearSchedule | Upcoming broadcasts the celebrity appears in, returned only if the request specifies a service ID. |
The following shows the response for Request Example 1, which asks for information about Patrick Stewart along with a schedule of broadcasts on Time Warner Cable in Beverly Hills, California. The response has been edited to reduce the length and formatted with extra spaces and carriage returns to make it easy to read.
The following shows an XML response for Request Example 1, which asks for information about Patrick Stewart along with a schedule of broadcasts on Time Warner Cable in Beverly Hills, California. The response has been edited to reduce.
Code | Name | Description |
---|---|---|
1001 | Core_MandatoryFieldMissing | A mandatory parameter is not specified. |
502001 | Listings_InvalidCopyType | The copytype specified in the request is invalid. |