---
title: "TVSS API"
canonical: "https://docs.pbs.org/space/tvsapi/3964930/TVSS%20API"
format: markdown
---
## Overview

The TV Schedules Service (TVSS) API is a **read-only** API that exposes PBS broadcast listing metadata in a simple JSON format, so you can build applications that use TV schedule data. Listing results typically contain about two weeks of future schedule information. (~30 days of past listing data is retained.)

Gracenote is the data source for TVSS programs, listings, and headends.

The TVSS API is available to **PBS stations, producers, and approved partners only** — not to the general public or non-PBS entities.

### What you can retrieve

- Listings — for today or by date
- Program and episode information
- Upcoming airings — by program, show, episode, or one-time-only
- Search across programs and episodes
- Station feeds and headends/providers
- Channel/feed lookup by ZIP code
- PBS KIDS programming
- PBS-hosted Gracenote images (on supported endpoints)

## Getting Started

### 1. Request an API key

If you are a PBS station or producer and don't already have access, request a TVSS API key from the [PBS Digital Support team](https://digitalsupport.pbs.org/). The API is read-only; there are no write credentials.

### 2. Authenticate

Endpoints that require authentication expect your secret key in a custom HTTP header named `X-PBSAUTH`. Not all endpoints require auth — see the **Endpoints** page, where the requirement is noted per endpoint.

```
X-PBSAUTH: <your-secret-key>
```

A missing or invalid key on a protected endpoint returns `403 Forbidden`.

### 3. Make your first request

Retrieve today's listings for a station by call sign:

```
curl https://tvss.services.pbs.org/tvss/weta/today/ \
  -H "X-PBSAUTH: <your-secret-key>"
```

A successful request returns `200 OK` with a JSON body of listings. See the **HTTP Response Status Codes** page for error handling.

## Conventions

### Base endpoint

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

A few endpoints (station feed info and sibling-callsign search) live under `/stations/` instead of `/tvss/` — these are noted on the Endpoints page.

### Always use HTTPS

Requests over `http` are served via redirect to `https`. Call `https` directly to avoid the extra round trip.

### Trailing slash

All endpoint URLs require a trailing slash.

### Path parameters

| Parameter | Format | Notes |
| --- | --- | --- |
| `<callsign>` | Station call sign (e.g., `weta`, `KAKM`) | Case-insensitive. Requests with a non-lowercase call sign are redirected to the lowercase URL. Use all lowercase when requesting JSONP. A nonexistent call sign returns `404`. |
| `<date>` | `YYYYMMDD` (e.g., `20261031`) | An invalid date returns `404`. |
| `<zip_code>` | 5 digits (e.g., `22202`, `00123`) | Left-pad with `0`s if shorter than 5. An invalid ZIP returns `404`. |
| `<feed_cid>` | Feed CID | A station feed identifier; accepts any valid feed CID. Used to scope listings/search to a single feed (channel). |
| `<station_id>` | Numeric station ID | Look up via the Station Manager public endpoint — see Endpoints → Stations & Feeds. |

### Query parameters

| Parameter | Value | Description |
| --- | --- | --- |
| `fetch-images` | flag (no value) | On supported endpoints, returns PBS-hosted Gracenote images for the object when available. **Not needed on **`/upcoming/` endpoints, which return images by default. |

## Endpoints

[View Endpoints](https://docs.pbs.org/space/tvsapi/1851588610/TVSS+API:+Endpoints)

## HTTP Response Status Codes

[View HTTP Response Status Codes](https://docs.pbs.org/space/tvsapi/1850802191/TVSS+API:+HTTP+Response+Status+Codes)

## Changelog

[View the TVSS API changelog](https://docs.pbs.org/space/CHAN/5638435/TV+Schedule+Service+(TVSS)+API+Changelog)