API Docs / Shows

Find a show

Live and CompleteFree key: empty with a noteMCP: find_show

Search every show we hold by any of its titles, and get back the stable show id the rest of the API uses.

ReturnsShows, best match first

Up to100 a call, 20 by default

FreshUp to 6 hours old

PlanLive and Complete

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

What it is for

Most work with shows starts here. You know a title, as a viewer would type it, and you need the show's id. The search matches the main title and every other title we hold for the show, including titles in other languages and older names.

Each result carries enough to tell close matches apart: the network, the genres and the day it first aired. Take the id of the one you want and use it with the show endpoints below.

A search box

Behind a "find a programme" field in a TV guide, a watch list or a second-screen app.

Matching your own list

Turn titles you already hold into show ids, once, then follow those ids.

Answering "when is it on"

An assistant finds the show here, then asks where it airs next.

/v1/shows/search/{q}then/v1/shows/{id}/airings /v1/shows/{id}/pattern /v1/shows/{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.

Find a show

Needs Live or Complete

Your key

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

qrequired limit

https://api.tvschedule.org/v1/shows/search/EastEnders

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/shows/search/EastEnders" \
  -H "X-API-Key: <your key>"

Parameters

Name	In	Type	Example	What it does
`q`required	path	string	EastEnders	Any title of the show, two characters or more. Case and accents do not matter. Put a space as +.
`limit`	query	integer	5	How many shows 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	sh_sdkgxsfs	The show's id. Stable for good, and used by every show endpoint.
`name`	string	EastEnders	The show's main title, as its home country knows it.
`type`	string	Scripted	Type
`status`	string	Running	Running or ended
`premiered`	string	1985-02-19	The day it first aired, YYYY-MM-DD, or null when not known.
`network`	object	{"id":"wb_fd1z1qvj","name":"BBC ...	The channel or network it first aired on.

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/shows/search/EastEnders

{
    "data": [
        {
            "id": "sh_sdkgxsfs",
            "name": "EastEnders",
            "type": "Scripted",
            "status": "Running",
            "premiered": "1985-02-19",
            "network": {
                "id": "wb_fd1z1qvj",
                "name": "BBC iPlayer",
                "country": "GB",
                "kind": "web"
            }
        },
        {
            "id": "sh_0g9tb1k4",
            "name": "EastEnders: The Six",
            "type": "Talk Show",
            "status": "Ended",
            "premiered": "2023-12-11",
            "network": {
                "id": "wb_fd1z1qvj",
                "name": "BBC iPlayer",
                "country": "GB",
                "kind": "web"
            }
        },
        {
            "id": "sh_y0c623yj",
            "name": "EastEnders: Secrets from the Square",
            "type": "Reality",
            "status": "Ended",
            "premiered": "2020-06-22",
            "network": {
                "id": "nw_tb1qjbfz",
                "name": "BBC One",
                "country": "GB",
                "kind": "network"
            }
        }
    ],
    "meta": {
        "count": 5,
        "took_ms": 14
    }
}

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`	Your plan does not read this: a day outside its window, or an endpoint on Live and Complete.	The message names the plan that does. Upgrade on the same key at /pricing.
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

PreviousShows guide NextOne show