API Docs / Directory

A country's channels

Free keyLive and CompleteMCP: country_channels

Every channel in one country, with the stable id the listings and statistics endpoints take.

ReturnsChannels, A to Z

Up to500 a page, 100 by default

FreshUp to 6 hours old

PlanEvery plan, the free key too

GEThttps://api.tvschedule.org/v1/countries/{cc}/channels

What it is for

Ask for a country by its two-letter code and get each of its channels: the id, the name, the country and its categories, such as general, news, sports, kids or movies. The list is in name order and long countries come in pages; follow meta.next_cursor to read the rest.

Most builds call this once a day and keep the ids. A channel's id never changes, so a saved list stays good even when a channel is renamed.

A channel line-up

Show a country's channels grouped by category.

Mapping your own list

Match channels you already carry to our ids, once.

Choosing what to fetch

Pick the channels you want before asking for their days.

/v1/countries/{cc}/channelsthen/v1/channels/{id}/schedule/{date}/v1/channels/{id}/v1/channels/{id}/stats

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 country's channels

Works on the free key

Your key

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

ccrequired limit

https://api.tvschedule.org/v1/countries/US/channels

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/countries/US/channels" \
  -H "X-API-Key: <your key>"

Parameters

Name	In	Type	Example	What it does
`cc`required	path	string	GB	The country as a two-letter code, such as GB, US or DE. UK also works and answers as GB.
`limit`	query	integer	50	How many channels a page, 100 when left out. 1 to 500
`cursor`	query	string		The next_cursor from the page before, to read the next page.

Returns

A list under data, with meta.count beside it and meta.next_cursor for the next page.

Field	Type	Example	What it holds
`id`	string	ch_012re0ya	Its id, stable and used by every other endpoint
`name`	string	00s Replay	Its name
`country`	string	US	The country, as a two-letter code
`categories`	array	["movies"]	The channel's categories, such as general, news, sports, kids or movies.
`in_registry`	boolean	true	In registry

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/countries/US/channels

{
    "data": [
        {
            "id": "ch_012re0ya",
            "name": "00s Replay",
            "country": "US",
            "categories": [
                "movies"
            ],
            "in_registry": true
        },
        {
            "id": "ch_zygef1xg",
            "name": "21 Jump Street",
            "country": "US",
            "categories": [
                "series"
            ],
            "in_registry": true
        },
        {
            "id": "ch_z07k6m3c",
            "name": "24 Hour Free Movies",
            "country": "US",
            "categories": [
                "movies"
            ],
            "in_registry": true
        }
    ],
    "meta": {
        "count": 5,
        "took_ms": 79,
        "next_cursor": "bzUuMDVhODU5Zjg"
    }
}

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

PreviousEvery country NextFind a channel