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.
Valid values are movie, episode, sports, show. (Episodes are not included in the default search results due to large returns. You must specifiy this entityType if you want them included in your returns.)

Common

  • entityType = movie, returns MV only
  • entiType = sports, returns SP only
  • entityType = episode, returns EP only

Search without lineupId

  • entityType = series or show, returns SH only
  • entityType not specified, defaults to MV and SH only.

Search with lineupId

  • entityType = series or show, returns both SH and EP. With lineups implies all airings of Simpsons.
  • entityType = episode, EP only returned. Will disregard entries where station listed the show but did not choose a specific episode.
  • entityType = not specified, searches all SH, EP, MV and SP records. Search results are restrained to lineup so all types are included.
genres No Filter results by genre name. Multiple values may be specified as comma-separated list.
Find valid values using Program Genres API. 
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
    sports only
  • name: team name (e.g., Kansas)
  • teambrandId: resource identifier for team
  • isHome: only shown when true; indicates team plays at home
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=Modern+Family&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": 126,
   "hits": [
      {
         "program": {
            "tmsId": "EP011581240003",
            "rootId": "7855636",
            "seriesId": "3560360",
            "subType": "Series",
            "title": "Modern Family",
            "episodeTitle": "The Bicycle Thief",
            "releaseYear": 2009,
            "releaseDate": "2009-09-30",
            "origAirDate": "2009-09-30",
            "titleLang": "en",
            "descriptionLang": "en",
            "entityType": "Episode",
            "genres": [
               "Sitcom"
            ],
            "longDescription": "Phil is determined to help Luke prove he is responsible enough to have a new bike; Jay and Manny have some father and son time.",
            "shortDescription": "Phil is determined to help Luke prove he is responsible enough to have a new bike.",
            "episodeNum": 2,
            "seasonNum": 1,
            "topCast": [
               "Ed O'Neill",
               "Julie Bowen",
               "Ty Burrell"
            ],
            "directors": [
               "Jason Winer"
            ],
            "preferredImage": {
               "width": "240",
               "height": "360",
               "uri": "assets/p7894659_b1t_v5_aa.jpg",
               "category": "Banner-L1T",
               "text": "yes",
               "primary": "true",
               "tier": "Season"
            }
         },
         "airings": [
            {
               "startTime": "2015-06-19T23:00Z",
               "endTime": "2015-06-19T23:30Z",
               "duration": 30,
               "qualifiers": [
                  "Stereo",
                  "CC"
               ],
               "channels": [
                  "066"
               ],
               "ratings": [
                  {
                     "body": "USA Parental Rating",
                     "code": "TVPG"
                  }
               ],
               "station": {
                  "stationId": "11207",
                  "callSign": "USA",
                  "preferredImage": {
                     "width": "360",
                     "height": "270",
                     "uri": "h3/NowShowing/11207/s11207_h3_aa.png",
                     "category": "Logo",
                     "primary": "true"
                  },
                  "channel": "066"
               }
            }
         ]
      },
      {
         "program": {
            "tmsId": "EP011581240003",
            "rootId": "7855636",
            "seriesId": "3560360",
            "subType": "Series",
            "title": "Modern Family",
            "episodeTitle": "The Bicycle Thief",
            "releaseYear": 2009,
            "releaseDate": "2009-09-30",
            "origAirDate": "2009-09-30",
            "titleLang": "en",
            "descriptionLang": "en",
            "entityType": "Episode",
            "genres": [
               "Sitcom"
            ],
            "longDescription": "Phil is determined to help Luke prove he is responsible enough to have a new bike; Jay and Manny have some father and son time.",
            "shortDescription": "Phil is determined to help Luke prove he is responsible enough to have a new bike.",
            "episodeNum": 2,
            "seasonNum": 1,
            "topCast": [
               "Ed O'Neill",
               "Julie Bowen",
               "Ty Burrell"
            ],
            "directors": [
               "Jason Winer"
            ],
            "preferredImage": {
               "width": "240",
               "height": "360",
               "uri": "assets/p7894659_b1t_v5_aa.jpg",
               "category": "Banner-L1T",
               "text": "yes",
               "primary": "true",
               "tier": "Season"
            }
         },
         "airings": [
            {
               "startTime": "2015-06-19T23:00Z",
               "endTime": "2015-06-19T23:30Z",
               "duration": 30,
               "qualifiers": [
                  "Stereo",
                  "CC"
               ],
               "channels": [
                  "101"
               ],
               "ratings": [
                  {
                     "body": "USA Parental Rating",
                     "code": "TVPG"
                  }
               ],
               "station": {
                  "stationId": "11207",
                  "callSign": "USA",
                  "preferredImage": {
                     "width": "360",
                     "height": "270",
                     "uri": "h3/NowShowing/11207/s11207_h3_aa.png",
                     "category": "Logo",
                     "primary": "true"
                  },
                  "channel": "101"
               }
            }
         ]
      },
... Additional hits ...
   ]
}