API Docs / Listings

A channel's schedule

Free key: yesterdayLive and Complete: 7 days back to 7 aheadMCP: channel_schedule

A channel's day, programme by programme, with start and end times, episodes and new, live and repeat flags.

ReturnsProgrammes, in time order

Up toThe whole day

FreshUp to 10 minutes old

PlanFree key reads yesterday

GEThttps://api.tvschedule.org/v1/channels/{id}/schedule/{date}

What it is for

This is the core of the listings. Ask for a channel and a day and get every programme: when it starts and ends in UTC, its title, its categories, the show and episode where we matched one, and whether it is new, live or a repeat.

The free key reads yesterday on every channel, so you can build against real rows from the first call. Live reads 7 days back to 7 days ahead. Pass tz to cut the day at local midnight rather than UTC midnight; the times in the answer stay UTC.

A TV guide grid

Lay out a channel's evening slot by slot.

What is on now

Find the programme whose start and stop cover this minute.

Alerts

Notice a new episode or a live event before it starts.

/v1/channels/{id}/schedule/{date}then/v1/countries/{cc}/schedule/{date}/v1/shows/{id}/airings /v1/xmltv/channels/{id}

Try it

Calls the real API with your key and shows the answer below. Your key stays in this browser and fills in on every docs page.

A channel's schedule

Works on the free key

Your key

No key yet? Get a free key. It fills in here by itself once made.

idrequired daterequired tz

https://api.tvschedule.org/v1/channels/ch_jw83a3xg/schedule/yesterday

Uses 1 call from your plan.

Calling

Code

Built from the form above, with your key in place. The language you pick is remembered.

curl "https://api.tvschedule.org/v1/channels/ch_jw83a3xg/schedule/yesterday" \
  -H "X-API-Key: <your key>"

Parameters

Name	In	Type	Example	What it does
`id`required	path	string	ch_jw83a3xg	The channel id, from a country's channels or channel search.
`date`required	path	string	yesterday	The day: YYYY-MM-DD, yesterday, today or tomorrow. The free key reads yesterday. YYYY-MM-DDyesterdaytodaytomorrow
`tz`	query	string	Europe/London	Cut the day at this time zone's midnight, such as Europe/London. Times stay UTC.

Returns

A list under data, with meta.count beside it.

Field	Type	Example	What it holds
`id`	string	ls_6pvwmmde	The programme's own id, stable for that airing.
`channel`	string	ch_jw83a3xg	The channel id it airs on.
`start`	datetime	2026-10-27T23:40:00Z	When it starts, UTC, as 2026-10-28T19:30:00Z.
`stop`	datetime	2026-10-28T00:10:00Z	When it ends, UTC.
`title`	string	Clickbait Clinic with Stacey Doo...	The programme title as the channel lists it.
`sub_title`	string	Can Dog Deworming Tablets Cure C...	Sub title
`description`	string	Stacey meets stage four cancer p...	Description
`category`	array	["documentaire","gezondheid"]	The programme's categories, such as Drama or News.
`episode_num`	string	onscreen:S1 E6	Episode num
`lang`	string	nl	Lang
`rating`	string or null	null	Rating
`flags`	object	{"new":false,"live":false}	new, live and repeat, each true or false.
`episode`	object	{"show_id":"sh_mh9by5qp","episod...	Where matched: show_id, season and number, so you can follow the show.
`film`	string or null	null	Film

Example answer

A real answer from our data, cut to three rows, so you can see the shape before you run anything.

200 OKhttps://api.tvschedule.org/v1/channels/ch_jw83a3xg/schedule/yesterday

{
    "data": [
        {
            "id": "ls_6pvwmmde",
            "channel": "ch_jw83a3xg",
            "start": "2026-10-27T23:40:00Z",
            "stop": "2026-10-28T00:10:00Z",
            "title": "Clickbait Clinic with Stacey Dooley",
            "sub_title": "Can Dog Deworming Tablets Cure Cancer?",
            "description": "Stacey meets stage four cancer patient Mel, who hopes an unverified viral trend offers a cure, despite medical warnings that the substance is unapproved for human use.",
            "category": [
                "documentaire",
                "gezondheid"
            ],
            "episode_num": "onscreen:S1 E6",
            "lang": "nl",
            "rating": null,
            "flags": {
                "new": false,
                "live": false
            },
            "episode": {
                "show_id": "sh_mh9by5qp",
                "episode_id": "ep_n0zvhcw3",
                "season": 1,
                "number": 6,
                "name": "Can dog deworming tablets cure cancer?",
                "orig_air": "2026-10-12"
            },
            "film": null
        },
        {
            "id": "ls_a02pwb9y",
            "channel": "ch_jw83a3xg",
            "start": "2026-10-28T00:10:00Z",
            "stop": "2026-10-28T00:55:00Z",
            "title": "Wisdom of the Crowd",
            "sub_title": "Aflevering 6",
            "description": "Do you think you spend too much of your working day procrastinating or too much time online? Find out as the crowd take on three more individuals in an attempt to bank up to £30,000.",
            "category": [
                "spelshow"
            ],
            "episode_num": "onscreen:S1 E6",
            "lang": "nl",
            "rating": null,
            "flags": {
                "new": false,
                "live": false
            },
            "episode": null,
            "film": null
        },
        {
            "id": "ls_1fvqz5n9",
            "channel": "ch_jw83a3xg",
            "start": "2026-10-28T00:55:00Z",
            "stop": "2026-10-28T01:00:00Z",
            "title": "Weather for the Week Ahead",
            "sub_title": null,
            "description": "Detailed weather forecast.",
            "category": [
                "weer"
            ],
            "episode_num": "onscreen:E565439742",
            "lang": "nl",
            "rating": null,
            "flags": {
                "new": false,
                "live": false
            },
            "episode": null,
            "film": null
        }
    ],
    "meta": {
        "count": 38,
        "took_ms": 7,
        "date": "2026-10-28"
    }
}

Errors

Status	Code	When	What to do
401	`unauthorized`	No key was sent, or it is not an active TV Schedule key.	Send it as Authorization: Bearer <key> or X-API-Key. Your keys are in your account.
403	`upgrade_required`	The day is outside your plan's window (the free key reads yesterday only).	The message names the plan that does. Upgrade on the same key at /pricing.
404	`not_found`	No channel has that id.	Take ids from the search and directory endpoints. Every address is listed in these docs.
400	`bad_request`	The date is not YYYY-MM-DD, yesterday, today or tomorrow.	Fix the value the message names and send it again.
422	`unknown_parameter`	A query parameter this endpoint does not take.	The message lists the ones it does take.
429	`rate_limited`	Faster than your plan's pace per minute.	Wait for Retry-After seconds. The X-RateLimit headers show where you are.
429	`quota_exceeded`	Your plan's allowance for the day or month is used.	It resets at the time in the message, or upgrade for a bigger allowance.
500	`server_error`	Something went wrong on our side, or the data was out of reach for a moment.	Try again in a minute. It has been logged, and /status shows the state of the service.

Next calls

PreviousListings guide NextA country's schedule