One show
One show's full record: its titles, network, genres, whether it is still running and when it began.
What it is for
Read a show from its id: the main title and the other titles it goes by, the network that made it famous, its genres, whether it is running or has ended, and the day it first aired.
Use it to head a show page, to check a saved id, or to decide whether an ended show still needs following.
A show page
Head the page with its titles, network and genres.
Watch lists
Mark which saved shows have ended.
Checking a saved id
Confirm an id still points to the show you mean.
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 show
Needs Live or CompleteNo key yet? Get a free key. It fills in here by itself once made.
Code
Built from the form above, with your key in place. The language you pick is remembered.
curl "https://api.tvschedule.org/v1/shows/sh_sdkgxsfs" \ -H "X-API-Key: <your key>"
Parameters
| Name | In | Type | Example | What it does |
|---|---|---|---|---|
idrequired | path | string | sh_sdkgxsfs | The show id, from show search, such as sh_e29nzc1x. |
Returns
One record under data, with meta beside it.
| Field | Type | Example | What it holds |
|---|---|---|---|
id | string | sh_sdkgxsfs | Its id, stable and used by every other endpoint |
name | string | EastEnders | Its name |
type | string | Scripted | Type |
status | string | Running | running or ended. |
premiered | string | 1985-02-19 | The day it first aired, YYYY-MM-DD. |
network | object | {"id":"wb_fd1z1qvj","name":"BBC ... | The network it belongs to |
ended | string or null | null | Ended |
language | string | English | Language |
genres | array | ["Drama"] | Its genres |
runtime | integer | 30 | Runtime |
country | string | GB | The country, as a two-letter code |
official_site | string | http://www.bbc.co.uk/programmes/... | Official site |
imdb | string | tt0088512 | Imdb |
Example answer
A real answer from our data, cut to three rows, so you can see the shape before you run anything.
{
"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"
},
"ended": null,
"language": "English",
"genres": [
"Drama"
],
"runtime": 30,
"country": "GB",
"official_site": "http://www.bbc.co.uk/programmes/b006m86d",
"imdb": "tt0088512"
},
"meta": {
"took_ms": 1
}
}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. |
| 404 | not_found | No show 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. |