Program search
/programs/search
Search for programs by title, description, cast, directors and genres. Optionally include lineupId in search criteria to limit results to programs on schedule. When searching by lineupId each airing will be returned as a separate hit. Note that if titleLang not specified in request, default return is English (en, en-GB) titles only.
For searching by genre, refer to Program Genres method for complete list of genres used by TMS editorial team when categorizing programs.
Request Parameters
Parameter |
Mandatory? |
Description |
q | Yes | Query string. |
queryFields | No | Comma-separated list of program fields to be searched; do not include spaces. If not specified, all valid fields will be searched against. Valid fields are title, description, cast, genres, directors. |
entityType | No |
Filter results by program type. Multiple values may be specified as comma-separated list. Common
Search without lineupId
Search with lineupId
|
genres | No | Filter results by genre name. Multiple values may be specified as comma-separated list. Find valid values using Program Genres API. |
subType | No | Add the ability to filter on program subtype: Feature Film, Short Film, TV Movie, Miniseries, Series, Special, Sports event, Sports non-event, Paid Programming, Theatre Event |
includeAdult | No | Boolean indicating whether to include programs with 'Adults Only' genre in results. Defaults to false. |
titleLang | No | Filter results based on the specified title language. Use IETF language tags (2-letter abbreviations, with optional 2-letter region extensions). Defaults to English (en, en-GB). |
descriptionLang | No | Filter results based on the specified description language. Use IETF language tags (2-letter abbreviations, with optional 2-letter region extensions). |
limit | No | The maximum number of programs to be returned from the query. Valid values are between 1 and 50. |
offset | No | Indicates starting point of response (zero-based index). Used in conjunction with limit to page through results. For example, offset=10 will position results to begin with 11th hit. If not specified, defaults to 0 to start resultset at beginning. |
lineupId | No | Lineup ID. If specified, results will include only programs found in the TV schedule, and airings will be listed under each program summary. If not specified, all programs matching the query will be returned, and no airings will be listed. Note: The hitcount may be higher than 100, but only 100 results will be retrievable. |
startDateTime | No | DateTime to start schedule search (ISO 8601). Only used when lineupId is specified. Must be no earlier than 1 day prior to current dateTime, and no more than 14 days after current dateTime. Defaults to 'now'. See DateTime documentation for tips on formatting. |
endDateTime | No | DateTime to end schedule search (ISO 8601). Only used when lineupId is specified. Must be no more than 14 days after startDateTime. The default endDateTime equals the startDateTime + 14 days. See DateTime documentation for tips on formatting. |
imageSize | No | Valid values are: Sm, Md, Lg, Ms. See Image Sizing for details. If not specified, defaults to Md. If requested image size is not available, generic image will be returned. |
imageAspectTv | No | Requested aspect ratio (horizontal by vertical) for TV show images. Valid values are: 2x3, 3x4, 4x3, 16x9 If not specified, defaults to 2x3. If requested aspect ratio is not available, generic image will be returned. |
imageText | No | Boolean indicating preference for image types with text (banners) or without text (iconics). If requested preference is not available, image selection will continue to next type (banner/iconic), before finally returning generic if no image found. Defaults to true for text preference. |
api_key |
Yes |
24-character key obtained during application registration |
Response Body
Response |
Description |
hitCount | total number of search results |
hits | Collection of program metadata and, if lineupId used in search, schedule metadata. Results are sorted by startTime. One "hit' per airing per channel. If 1 EP record is on three different channels at the same time, that is 3 results. If 1 EP record is on three different channels at different times that is 3 results, scattered through the sort order. No grouping is performed; the sort is purely based on time. |
program | Object with the following properties: |
tmsId | TMS-generated 14-character alphanumeric identifier for program record; first 2 characters generally identify program type (MV=movie, SH=show/series, EP=episode, SP=sports event) |
title | program title; for episode records, this is series title |
titleLang | 2-letter language abbreviation code (e.g., 'en'=English, 'es'=Spanish) |
shortDescription |
program description, maximum 100 characters |
longDescription |
program description, maximum 250 characters for episodes and sports, max 500 characters for movies, max 1000 characters for shows |
descriptionLang |
2-letter language abbreviation code (e.g., 'en'=English, 'es'=Spanish) |
subType | program subType; see Program Metadata for full list of subType values |
genres | comma-separated list of program genres (e.g., Romance, Comedy, News) |
preferredImage | program image; if none found, generic image for program's entity type will be returned; see Image metadata for field details |
topCast | comma-separated list of top cast member names, in billing order |
origAirDate | also known as OAD, date of original TV airing; format is yyyy-mm-dd |
entityType | type of program: movie, show, episode, sports |
rootId | numeric identifier used to connect related program records with different title language, description language, and versions |
seriesId | series or episodes only; numeric identifier corresponding to rootId of series' main program record |
episodeTitle | episodes only; episode-specific title |
seasonNum | episodes only; season number |
episodeNum | episodes only; episode number |
releaseYear | movies only; year of theatrical movie release, formatted yyyy |
qualityRating | movies only; object has these properties: ratingsBody, value; value is a numeric rating; TMS has a 0.5 - 4.0 star rating system |
eventTitle |
sports only; for team events, includes team names and location (e.g., Kansas at Missouri); for non-team events, provides greater detail than common 'Title' field |
gameDate | sports only; format is yyyy-mm-dd |
teams |
|
airings | An array with a single airing object with the following properties (if lineupId specified): |
startTime | specified in UTC, offset must be applied for display in local time |
endTime | specified in UTC, offset must be applied for display in local time |
duration | program duration, in minutes |
ratings | ratings body and code (e.g., body=MPAA, code=PG-13); provided for US and Canadian ratings boards; not available for all airings |
qualifiers | comma-separated list of program qualifiers/notes (e.g., CC, Stereo, Live, New, HDTV) |
channels | Channels on which this program airing will appear |
stationId | unique identifier for station |
Sample Request 1 (search all programs)
http://data.tmsapi.com/v1.1/programs/search?q=dreams&api_key=1234567890
Sample Request 2 (search programs on schedule)
http://data.tmsapi.com/v1.1/programs/search?q=The+Big+Bang+Theory&lineupId=USA-TX42500-X&startDateTime=2015-05-19T22%3A00Z&api_key=1234567890
Sample Response 1 (program metadata)
{
"hitCount":12020,
"hits":[
{
"program":{
"tmsId":"MV000236080000",
"rootId":"49339",
"subType":"Feature Film",
"title":"Dreams",
"releaseYear":1955,
"titleLang":"en",
"descriptionLang":"en",
"entityType":"Movie",
"genres":["Drama"],
"longDescription":"Susanne (Eva Dahlbeck) is a woman in her mid-30s and the owner of a modeling agency in Stockholm. She accompanies her prize model, Doris (Harriet Andersson), on a trip to Gothenburg so that Doris can be photographed. While traveling, both women seek out romance, Susanne with a married lover and Doris with an older gentleman who sees his deceased wife in the young model. The two women struggle to understand their romantic motivations and in the process form an unlikely friendship.",
"shortDescription":"Stockholm model (Harriet Andersson) and her boss (Eva Dahlbeck) have one-day affairs with men.",
"cast":[
{
"billingOrder":"01",
"role":"Actor",
"nameId":"76415",
"personId":"76415",
"name":"Harriet Andersson",
"characterName":"Doris"
},
{
"billingOrder":"02",
"role":"Actor",
"nameId":"162977",
"personId":"162309",
"name":"Eva Dahlbeck",
"characterName":"Susanne"
},
{
"billingOrder":"03",
"role":"Actor",
"nameId":"220068",
"personId":"217708",
"name":"Gunnar Björnstrand",
"characterName":"Otto Sönderby"
},
{
"billingOrder":"04",
"role":"Actor",
"nameId":"244188",
"personId":"240656",
"name":"Ulf Palme",
"characterName":"Mr. Henrik Lobelius"
},
{
"billingOrder":"05",
"role":"Actor",
"nameId":"461183",
"personId":"452308",
"name":"Inga Landgré",
"characterName":"Mrs. Lobelius"
}
],
"crew":[
{
"billingOrder":"01",
"role":"Director",
"nameId":"27549",
"personId":"27549",
"name":"Ingmar Bergman"
}
],
"directors":["Ingmar Bergman"],
"keywords":{
"Mood":["Sultry","Bleak","Fascinating"],
"Time Period":["1950s"],
"Theme":["Forbidden love","Temptation","Discovery"],
"Character":["Model","Businessperson","Gentleman","Lover"],
"Setting":["Gothenburg, Sweden","Stockholm"],
"Subject":["Affair","Photography","Aging","Female bonding"],
"General":["Fashion"]
},
"qualityRating":{
"ratingsBody":"TMS",
"value":"3.5"
},
"ratings":[
{
"code":"12",
"body":"British Board of Film Classification"
}
],
"recommendations":[
{
"tmsId":"MV000004070000",
"root":"12760",
"title":"Jules and Jim"
},
{
"tmsId":"MV000048410000",
"root":"2945",
"title":"Brief Encounter"
},
{
"tmsId":"MV000059260000",
"root":"3534",
"title":"La Strada"
}
],
"runTime":"PT01H26M",
"preferredImage":{
"width":"240",
"height":"360",
"uri":"assets/p49339_i_v5_aa.jpg",
"category":"Iconic",
"primary":"true"
}
}
},
{
{
"program":{
"tmsId":"SH016517190000",
"rootId":"9609063",
"seriesId":"9609063",
"sportsId":"64",
"subType":"Special",
"title":"Dreams",
"origAirDate":"2012-12-22",
"titleLang":"en-GB",
"descriptionLang":"en-GB",
"entityType":"Show",
"genres":[ "Action sports", "Special", "Bicycle racing" ],
"longDescription":"Dreams is the real-life story of Terry Adams, the most innovative, revered and talented flat-ground BMX'er in the world.",
"preferredImage":{
"width":"240",
"height":"360",
"uri":"assets/p9609063_b_v5_aa.jpg",
"category":"Banner-L1",
"text":"yes",
"primary":"true"
}
}
},
... additional hits ...
]
}
Sample Response 2 (program metadata + schedule metadata)
{
"hitCount": 142,
"hits": {
"program" : {
"tmsId" : "EP009311820012",
"rootId" : "3358658",
"seriesId" : "185554",
"subType" : "Series",
"title" : "The Big Bang Theory",
"episodeTitle" : "The Pancake Batter Anomaly",
"releaseYear" : 2008,
"releaseDate" : "2008-03-31",
"origAirDate" : "2008-03-31",
"titleLang" : "en",
"descriptionLang" : "en",
"entityType" : "Episode",
"genres" : [
"Sitcom"
],
"longDescription" : "Leonard and the boys avoid Sheldon when he gets sick, leaving Penny to nurse him back to health.",
"shortDescription" : "Leonard and the boys avoid Sheldon when he gets sick, leaving Penny to nurse him back to health.",
"episodeNum" : 11,
"seasonNum" : 1,
"topCast" : [
"Johnny Galecki",
"Jim Parsons",
"Kaley Cuoco"
],
"directors" : [
"Mark Cendrowski"
],
"ratings" : [
{
"body" : "Canadian Parental Rating",
"code" : "PG"
},
{
"body" : "The Régie du cinéma",
"code" : "13+"
},
{
"body" : "Departamento de Justiça, Classificação, Títulos e Qualificação",
"code" : "12"
},
{
"body" : "USA Parental Rating",
"code" : "TVPG"
}
],
"preferredImage" : {
"width" : "240",
"height" : "360",
"uri" : "assets/p7895966_b_v5_aa.jpg",
"category" : "Banner-L1",
"text" : "yes",
"primary" : "true",
"tier" : "Season"
}
},
"airings" : [
{
"startTime" : "2018-08-03T23:30Z",
"endTime" : "2018-08-04T00:00Z",
"duration" : 30,
"qualifiers" : [
"CC",
"HD 720p",
"HDTV",
"Stereo"
],
"channels" : [
"1206"
],
"ratings" : [
{
"body" : "USA Parental Rating",
"code" : "TVPG"
}
],
"station" : {
"stationId" : "31222",
"callSign" : "KTBCDT",
"affiliateCallSign" : "FOX",
"affiliateId" : "10212",
"preferredImage" : {
"width" : "360",
"height" : "270",
"uri" : "h3/NowShowing/28719/s28719_h3_aa.png",
"category" : "Logo",
"primary" : "true"
},
"channel" : "1206"
}
}
]
}
{
"tmsId" : "EP009311820012",
"rootId" : "3358658",
"seriesId" : "185554",
"subType" : "Series",
"title" : "The Big Bang Theory",
"episodeTitle" : "The Pancake Batter Anomaly",
"releaseYear" : 2008,
"releaseDate" : "2008-03-31",
"origAirDate" : "2008-03-31",
"titleLang" : "en",
"descriptionLang" : "en",
"entityType" : "Episode",
"genres" : [
"Sitcom"
],
"longDescription" : "Leonard and the boys avoid Sheldon when he gets sick, leaving Penny to nurse him back to health.",
"shortDescription" : "Leonard and the boys avoid Sheldon when he gets sick, leaving Penny to nurse him back to health.",
"episodeNum" : 11,
"seasonNum" : 1,
"topCast" : [
"Johnny Galecki",
"Jim Parsons",
"Kaley Cuoco"
],
"directors" : [
"Mark Cendrowski"
],
"ratings" : [
{
"body" : "Canadian Parental Rating",
"code" : "PG"
},
{
"body" : "The Régie du cinéma",
"code" : "13+"
},
{
"body" : "Departamento de Justiça, Classificação, Títulos e Qualificação",
"code" : "12"
},
{
"body" : "USA Parental Rating",
"code" : "TVPG"
}
],
"preferredImage" : {
"width" : "240",
"height" : "360",
"uri" : "assets/p7895966_b_v5_aa.jpg",
"category" : "Banner-L1",
"text" : "yes",
"primary" : "true",
"tier" : "Season"
}
}
[
{
"startTime" : "2018-08-03T23:30Z",
"endTime" : "2018-08-04T00:00Z",
"duration" : 30,
"qualifiers" : [
"CC",
"HD 720p",
"HDTV",
"Stereo"
],
"channels" : [
"1206"
],
"ratings" : [
{
"body" : "USA Parental Rating",
"code" : "TVPG"
}
],
"station" : {
"stationId" : "31222",
"callSign" : "KTBCDT",
"affiliateCallSign" : "FOX",
"affiliateId" : "10212",
"preferredImage" : {
"width" : "360",
"height" : "270",
"uri" : "h3/NowShowing/28719/s28719_h3_aa.png",
"category" : "Logo",
"primary" : "true"
},
"channel" : "1206"
}
}
]
},
... Additional hits ...
]
}