Overview

TV Schedules Service (TVSS) is a read-only API which exposes listing metadata in a simple, easy-to-use format, and allows you to create applications that use TV Schedules metadata. As of October 9, 2018, Gracenote is our data source for TV Schedules programs, listings, and headends, replacing longtime provider, TiVo/Rovi. See the available Production API Endpoints section below, for details.

Listing results typically contain two weeks of schedule information.

Technical Details

General: Django, Python 3, PostgreSQL
API: JSON, SSL + Basic Auth, Read

Related Pages

Available Content

Types of content available in the read-only API:

  • Listing data (today and by date)
  • Program information
  • Episode information
  • Station feeds
  • Station headends/providers
  • Listing search
  • PBS KIDS programming
  • PBS-hosted Gracenote images for select endpoints

Access

If you are a PBS station or producer, and are not already using the TVSS API, you can request a read-only API key from the Support team. The TVSS API is not available to the general public, or non-PBS entities.

Authentication & Request Header

Some of the endpoints are protected by a private key, and are noted below.

For endpoints requiring authentication: In order to do a successful request a client must include in the HTTP request a special header named X-PBSAUTH with your secret key.

General Error Handling & Special Cases

PlaceholderGuidelinesExamples
<callsign>

The callsign is case-insensitive (except when returning JSONP use all lowercase) however, the API endpoint will redirect all requests that don't have a lowercase callsign to an equivalent URL that does.  Querying using an nonexistent callsign will return a 404 Not found.

weta, KAKM
<date>

Format: YYYYMMDD.  Using an invalid date will return a 404 Not found.

20181009

<zip_code>ZIP code must have five characters (if smaller, left pad with 0s).  Using an invalid ZIP code will return a 404 Not found.22202, 00123

Query Parameters

Parameter nameValueDescription
fetch-imagesN/A

For the applicable endpoints (below), the fetch-images parameter will return related, Gracenote images for the object, when available.

Applicable endpoints include:

  1. Listings (by callsign, date): https://services.pbs.org/tvss/<callsign>/day/<yyyymmdd>/?fetch-images
  2. KIDS listings (by callsign, date): https://services.pbs.org/tvss/<callsign>/day/<yyyymmdd>/kids/?fetch-images
  3. Listings for today (by callsign): https://services.pbs.org/tvss/<callsign>/today/?fetch-images
  4. KIDS listings for today (by callsign): https://services.pbs.org/tvss/<callsign>/today/kids/?fetch-images

Note: All /upcoming/ endpoints do not require the fetch-images parameter, and will return Gracenote images by default, when they are available.

Production API Endpoints

  • Please note all hyperlinks are https:// not http://
  • If you are using the http:// protocol, please update your code to use https://
  • Using the http:// protocol will redirect to https:// but will initially return a 301 status code, prior to the 200 you'll receive from the redirected URL


Base Endpoint

https://services.pbs.org/tvss/

DescriptionRequires Auth?Endpoint
Listings (by callsign, date)Yes

https://services.pbs.org/tvss/<callsign>/day/<yyyymmdd>/

NEW: Response now includes TMS ID:

  • For a program, we have: program_external_id={SH TMS ID}
  • For an episode, we have:
    • show_external_id= {EP TMS ID}
    • program_external_id= {parent SH TMS ID}
  • For a one time only, we have: show_external_id= {MV or SP TMS ID}
NEW: Listings (by callsign, date) with Gracenote imagesYeshttps://services.pbs.org/tvss/<callsign>/day/<yyyymmdd>/?fetch-images
KIDS listings (by callsign, date)Yes

https://services.pbs.org/tvss/<callsign>/day/<yyyymmdd>/kids/

NEW: Response now includes TMS ID:

  • For a program, we have: program_external_id={SH TMS ID}
  • For an episode, we have:
    • show_external_id= {EP TMS ID}
    • program_external_id= {parent SH TMS ID}
  • For a one time only, we have: show_external_id= {MV or SP TMS ID}
NEW: KIDS listings (by callsign, date) with Gracenote imagesYeshttps://services.pbs.org/tvss/<callsign>/day/<yyyymmdd>/kids/?fetch-images
Listings for today (by callsign)Yes

https://services.pbs.org/tvss/<callsign>/today/

NEW: Response now includes TMS ID:

  • For a program, we have: program_external_id={SH TMS ID}
  • For an episode, we have:
    • show_external_id= {EP TMS ID}
    • program_external_id= {parent SH TMS ID}
  • For a one time only, we have: show_external_id= {MV or SP TMS ID}
NEW: Listings for today (by callsign) with Gracenote imagesYeshttps://services.pbs.org/tvss/<callsign>/today/?fetch-images
KIDS listings for today (by callsign)Yes

https://services.pbs.org/tvss/<callsign>/today/kids/

NEW: Response now includes TMS ID:

  • For a program, we have: program_external_id={SH TMS ID}
  • For an episode, we have:
    • show_external_id= {EP TMS ID}
    • program_external_id= {parent SH TMS ID}
  • For a one time only, we have: show_external_id= {MV or SP TMS ID}
NEW: KIDS listings for today (by callsign) with Gracenote imagesYeshttps://services.pbs.org/tvss/<callsign>/today/kids/?fetch-images

Upcoming program listings (by callsign, program_id OR tms_id)

  • program_id = PBS internal primary key
  • tms_id = Gracenote (program) ID
  • NEW: Response now includes Gracenote images by default, when available
Yes

https://services.pbs.org/tvss/<callsign>/upcoming/program/<program_id>/

OR

https://services.pbs.org/tvss/<callsign>/upcoming/program/<tms_id>/

Notes:

  • Must be a Gracenote TMS ID for a program, which contains the "SH" prefix
  • Program TMS IDs can be found in TVSS API and for some programs (known as "shows"), in Media Manager

Upcoming show listings (by callsign and either episode_id or onetimeonly_id)

  • NEW: Response now includes Gracenote images by default, when available
Yes

https://services.pbs.org/tvss/<callsign>/upcoming/show/<episode_id>/

or

https://services.pbs.org/tvss/<callsign>/upcoming/show/<onetimeonly_id>/

(Note: Gracenote does not have the concept of a "movie" for PBS listings, so there is no 'movie_id')

Upcoming episode listings (by callsign and Gracenote TMS ID for episodes)

  • NEW: Response now includes Gracenote images by default, when available
Yes

https://services.pbs.org/tvss/<callsign>/upcoming/episode/<tms_id>/

Notes:

  • Must be a Gracenote TMS ID for an episode, which contains the "EP" prefix
  • Episode TMS IDs can be found in TVSS API

Upcoming one time only (OTO) listings (by callsign and Gracenote TMS ID for OTO)

  • NEW: Response now includes Gracenote images by default, when available


Yes

https://services.pbs.org/tvss/<callsign>/upcoming/onetimeonly/<tms_id>/

Notes:

  • Must be a Gracenote TMS ID for an episode, which contains the "MV" or "SP" prefix
  • OTO TMS IDs can be found in TVSS API
KIDS search listings (by callsign, search term/s)Yeshttps://services.pbs.org/tvss/<callsign>/search-kids/<search-term>/
Feed info for a single station (by station_id)Yes

https://services.pbs.org/stations/<station_id>/

How to find the <station_id>

Note: URL does not include "/tvss/"

Search listings (by callsign, search term/s)Nohttps://services.pbs.org/tvss/<callsign>/search/<search_term>/
Search listings (by search term/s only)Nohttps://services.pbs.org/tvss/search/<search_term>/
Channel/Feed lookup (by callsign, zipcode)Nohttps://services.pbs.org/tvss/<callsign>/channels/zip/<zip_code>/
Channel/Feed lookup (by callsign only)Nohttps://services.pbs.org/tvss/<callsign>/channels/
Full program listNohttps://services.pbs.org/tvss/programs/

How to Find Station ID

Look up the station_id using the sample (WETA) link below. Append the station flagship call sign to the end and in the response, look for the "id" field. https://station.services.pbs.org/api/public/v1/stations/?call_sign=WETA

Use this value for the TVSS /stations/<station_id>/ endpoint.

Important Fields

FieldsDescriptionExample 
short_nameThis is the internal, short name for a feed, which is provided and managed by Gracenote. Updates to this name should be submitted to the station's Gracenote contact. Changes typically only occur when a stations switches feeds/lineups.WETADT3
full_nameThis is the station-provided name for a feed, which is displayed to end users. Changes to this name should be submitted to the PBS Digital support team.WETA Kids
external_idUnique, numeric Gracenote ID.32050
start_time

A localized start time for the show. The localization is based on the feed timezone. The feed timezone is based on the timezone of the call sign (or transmitter) for which you want to access shows. For instance, if a call sign in California wants to access WETA shows on the east coast, California must adjust the time to reflect Eastern Standard Time. If 0000 = midnight, a California call sign would adjust the time to 2100 for east coast airtimes.

The value has the following format: HHMM where "H" represents hours and "M" minutes. The hour value is between 00 and 24.

0100 
duration
The show duration. The value has the following format: HHMM where "H" represents hours and "M" minutes.130  (one hour, 30 min.), 330 (three hours, 30 min.)
minutes
The show length in minutes.60 
type

One of the following values 'episode', 'onetimeonly'.

episode 
episode_title
Only present when type is 'episode'.Magic in the Air; Everyone Loves Clifford 
title
If type is 'onetimeonly', this is the title for the onetimeonly. When type is 'episode', this is the episode's parent program title.

If type is 'onetimeonly': Doctor Zhivago

If type is 'episode': Antiques Roadshow

program_id
Only present when type is 'episode' and can be used to identify the program related to this episode in other endpoints.75 
show_id
This will be used to identify the 'episode' and 'onetimeonly' resources and uses the following convention: {type}_{id}. Ex: episode_1234, onetimeonly_1234episode_6692 
closed_captions_available
For this listing, does it have closed captioning?true, false
airing_type
For this listing, is it a re-run or the first time this show is broadcast?Taped
broadcast_hd
For this listing, is it in High Definition (HD)?true
broadcast_stereo
For this listing, is the audio in stereo?false
broadcast_animated
For this listing, is this an animated show?true, false
nola_root
NOLA root (PBS program ID).  Short alpha (4 chars)AUCL
nola_episode
NOLA episode (PBS episode ID.  Short positive integer (6 chars)390401
episode_description
Only present when type is 'episode'.Jessica and Hector\'s plan ... 
description

If type is 'episode' this is the program description.

A revival of the classic ... 
timezone
Timezone for requested station.
America/New_York, America/Anchorage
images

Array of Gracenote-provided images hosted by PBS (ITS), when available.

Value/Array will be empty when there are no images available from Gracenote.

"type": "image/jpeg",
"image": "https://image.pbs.org/gracenote/pbsd.tmsimg.com/assets/p15694932_b_h9_aa.jpg",
"width": "1440",
"height": "1080",
"caption": "",
"updated_at": "2018-08-31T20:05:00Z",
"external_profile": "Banner-L2"