API Docs / Directory

One channel

Free keyLive and CompleteMCP: get_channel

One channel's full record: its names, country, languages, categories and the year it launched.

ReturnsOne channel

Up toOne record

FreshUp to 6 hours old

PlanEvery plan, the free key too

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

What it is for

Read everything we hold about a channel from its id: every name it has gone by, the country it belongs to, the languages it broadcasts in, its categories and, where known, the year it launched.

Use it to fill a channel page or to check an id you saved long ago still points where you expect.

A channel page

Head a channel's page with its names and details.

Checking a saved id

Confirm an id still matches the channel you mean.

Filtering by language

Keep only channels in the languages your users read.

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

One channel

Works on the free key

Your key

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

idrequired

https://api.tvschedule.org/v1/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/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, such as ch_jw83a3xg.

Returns

One record under data, with meta beside it.

Field	Type	Example	What it holds
`id`	string	ch_jw83a3xg	Its id, stable and used by every other endpoint
`name`	string	BBC One	Its name
`country`	string	GB	The country, as a two-letter code
`categories`	array	["general"]	Its categories
`owner`	string	BBC	Owner
`network`	string	BBC Television	The network it belongs to
`launched`	integer	1936	The year it launched, or null when not known.
`closed`	string or null	null	Closed
`website`	string	http://www.bbc.co.uk/bbcone/	Website
`in_registry`	boolean	true	In registry
`also_known_as`	array	["BBC1,BBC Television,BBC Televi...	Also known as
`feeds`	integer	28	Feeds

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

{
    "data": {
        "id": "ch_jw83a3xg",
        "name": "BBC One",
        "country": "GB",
        "categories": [
            "general"
        ],
        "owner": "BBC",
        "network": "BBC Television",
        "launched": 1936,
        "closed": null,
        "website": "http://www.bbc.co.uk/bbcone/",
        "in_registry": true,
        "also_known_as": [
            "BBC1,BBC Television,BBC Television Service"
        ],
        "feeds": 28
    },
    "meta": {
        "took_ms": 3
    }
}

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.
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.
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

PreviousFind a channel NextListings guide