API Docs / Listings

XMLTV for a channel

Live and Complete

A channel as an XMLTV file, today and the days ahead, ready for media players and EPG software.

ReturnsAn XMLTV file

Up toUp to 7 days

FreshUp to 30 minutes old

PlanLive and Complete

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

What it is for

XMLTV is the file format TV software reads: Plex, Jellyfin, Kodi, TVHeadend, Channels DVR and most set-top EPG tools take it directly. This endpoint gives one channel's programmes from today forward as a ready file.

Point your player at the address with your key in a header, or fetch it on a schedule and save it. The days ahead follow your plan's window.

Plex and Jellyfin

Feed a home server's guide from our listings.

Set-top boxes

Load an EPG on hardware that only reads XMLTV.

Nightly files

Save each channel's file on a schedule for offline use.

/v1/xmltv/channels/{id}then/v1/channels/{id}/schedule/{date}/v1/countries/{cc}/channels /v1/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.

XMLTV for a channel

Needs Live or Complete

Your key

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

idrequired days

https://api.tvschedule.org/v1/xmltv/channels/ch_jw83a3xg

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/xmltv/channels/ch_jw83a3xg" \
  -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.
`days`	query	integer	3	How many days from today to include, within your plan. 1 to 7

Returns

An XMLTV file (application/xml): a <channel> element for the channel, then a <programme> for each slot with its start, stop, title, description, categories and episode number where known, today and the days ahead in your plan's window.

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`	XMLTV is on Live and Complete.	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`	A value is the wrong shape: a date that is not YYYY-MM-DD, a two-character search, a key sent in the address.	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

PreviousA country's schedule NextShows guide