TV Schedule API documentation
Every channel's day and every show's slot, under one keyListings for the week, every show and the pattern of when it airs, across 179 countries, as JSON over HTTPS. One key, one shape, the same ids everywhere and every time in UTC.
$ curl https://api.tvschedule.org/v1/channels/ch_jw83a3xg/schedule/yesterday
Start here
Three steps from nothing to a real answer. The key you paste is kept in this browser for every docs page.
Get a key
Sign in with Google. Your free key is made at once and shown on your account page.
Get a free keyYour first call
Works on the free keyNo key yet? Get a free key. It fills in here by itself once made.
Subjects
Each subject has a guide that explains how its records link, and a page for every endpoint in it.
Directory
Free keyCountries, their channels and one stable id per channel, which every other endpoint takes.
GETEvery country/v1/countries GETA country's channels/v1/countries/{cc}/channels GETFind a channel/v1/channels/search/{q} GETOne channel/v1/channels/{id}Listings
Free key: yesterdayA channel's day slot by slot, a whole country's day, and XMLTV for players. Times are UTC; pick the local day with tz.
GETA channel's schedule/v1/channels/{id}/schedule/{date} GETA country's schedule/v1/countries/{cc}/schedule/{date} GETXMLTV for a channel/v1/xmltv/channels/{id}Shows
Live and CompleteFind a show by title, read what it is and where it airs in the days ahead, first runs told apart from repeats.
GETFind a show/v1/shows/search/{q} GETOne show/v1/shows/{id} GETWhere a show airs/v1/shows/{id}/airingsPatterns
Live and CompleteA show's usual slot and weekday by hour fingerprint, airing counts, and the weekly most aired and repeated charts.
GETA show's airing pattern/v1/shows/{id}/pattern GETA show's statistics/v1/shows/{id}/stats GETA channel's statistics/v1/channels/{id}/stats GETMost aired last week/v1/countries/{cc}/most-aired GETMost repeated last week/v1/countries/{cc}/repeatsPopular calls
The calls people make most, from the API's own counts, each ready to open.
| What it does | The call | |
|---|---|---|
| Every channel in a country for a day, 50 channels a page. | /v1/countries/US/schedule/yesterday | Open |
| Yesterday on one channel, slot by slot | /v1/channels/ch_jw83a3xg/schedule/yesterday | Open |
| Every channel in a country and its id | /v1/countries/US/channels | Open |
| Find a show's id by title | /v1/shows/search/EastEnders | Open |
| When a show usually airs, and how often it repeats | /v1/shows/sh_sdkgxsfs/pattern | Open |
For assistants and agents
The same API as tools and one-file manuals, generated from the API itself so they always match it.
MCP server
Add it to Claude, ChatGPT, Cursor or Claude Code and sign in once. Your assistant reads with your plan.
https://tvschedule.org/mcpThe manual
Every endpoint, parameter and field in one markdown file, to paste into an assistant or a prompt.
https://tvschedule.org/documentation/manual.mdllms.txt and OpenAPI
The short index an assistant reads first, and the OpenAPI file for code generators and API tools.
https://tvschedule.org/llms.txtPlans in short
Read from the same settings the API enforces. Prices and upgrades are on pricing; every limit is in plans and limits.
- Yesterday's listings and the directory
- 30 calls a minute, 200 calls a day
- 1 key
- 7 days back to 7 days ahead, shows, and 90 days of patterns and statistics
- 120 calls a minute, 300,000 calls a month
- 1 key
- 7 days back to 7 days ahead, shows, and all time of patterns and statistics
- 600 calls a minute, no monthly limit
- 5 keys
What is new
Every change is in the changelog.
The rest
Questions people ask
Why does the free key only read yesterday?
It is real data to build and test against. Today and the week ahead are what live products pay for, on Live. See plans and limits.
Which time zone are the times in?
Every time is UTC with a Z. The tz parameter only chooses which local day is cut, so a UK evening is not split across two dates. See the listings guide.
Do ids change?
No. A channel or show id stays the same, so you can store it. Take ids from the directory and show search.
Can I use it from an assistant?
Yes. Add the MCP server to Claude, ChatGPT, Cursor or Claude Code; it reads with your plan. See the MCP guide.