API Docs / Directory

Find a channel

Free keyLive and CompleteMCP: find_channel

Find a channel by its name, an alias or a call sign, across every country or within one.

ReturnsChannels, best match first

Up to100 a call, 20 by default

FreshUp to 6 hours old

PlanEvery plan, the free key too

GEThttps://api.tvschedule.org/v1/channels/search/{q}

What it is for

When you know a channel by name rather than by id, start here. The search matches the channel's name, the other names it goes by and, for US stations, its call sign, so the name a viewer would type finds it.

Add country to keep the answer to one market, which helps with names used in several countries.

A search box

Behind a "find a channel" field in a guide or a settings page.

Matching feeds

Turn channel names from your own source into our ids.

Answering assistants

An assistant finds the channel, then asks for its day.

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

Find a channel

Works on the free key

Your key

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

qrequired country limit

https://api.tvschedule.org/v1/channels/search/BBC+One

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/search/BBC+One" \
  -H "X-API-Key: <your key>"

Parameters

Name	In	Type	Example	What it does
`q`required	path	string	BBC	A channel name, alias or call sign, two characters or more. Put a space as +.
`country`	query	string	GB	Only channels in this country, as a two-letter code.
`limit`	query	integer	5	How many channels to return, best match first. 20 when left out. 1 to 100

Returns

A list under data, with meta.count 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
`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/channels/search/BBC+One

{
    "data": [
        {
            "id": "ch_jw83a3xg",
            "name": "BBC One",
            "country": "GB",
            "categories": [
                "general"
            ],
            "in_registry": true
        },
        {
            "id": "ch_k1f2134x",
            "name": "BBC One West",
            "country": null,
            "categories": [],
            "in_registry": false
        },
        {
            "id": "ch_gz4nnp40",
            "name": "BBC One East",
            "country": null,
            "categories": [],
            "in_registry": false
        }
    ],
    "meta": {
        "count": 5,
        "took_ms": 41
    }
}

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`	The search has fewer than two characters.	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 channels NextOne channel