API Docs / Patterns

A channel's statistics

Live and CompleteFree key: empty with a noteMCP: channel_stats

What a channel puts out: programmes a week, distinct shows, its genre mix and how much of it is repeats.

ReturnsThe channel's counts

Up toOne record

FreshUp to an hour old

PlanLive and Complete

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

What it is for

This counts a channel's output across our history: how many programmes it aired, how many distinct shows, its biggest genres with their share, its repeat share, and the first and last day we hold for it.

Use it to profile channels, compare them, or keep only the ones that air the kind of content your users want.

Channel profiles

Show a channel's genre mix as a bar or a ring.

Comparing channels

See which channels lean on repeats.

Filtering

Keep channels that are mostly sport, news or film.

/v1/channels/{id}/statsthen/v1/channels/{id}/schedule/{date}/v1/channels/{id}/v1/countries/{cc}/most-aired

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 channel's statistics

Needs Live or Complete

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/stats

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/stats" \
  -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.

Returns

One record under data, with meta beside it.

Field	Type	Example	What it holds
`programmes`	integer	2140	Programmes counted in the window.
`shows`	integer	318	Distinct shows among them.
`repeat_share`	number	0.41	The share of programmes that were repeats, from 0 to 1.
`top_genres`	array	[{"genre":"Drama","share":0.22}]	Its biggest genres with their share, largest first.
`first_seen`	string	2023-01-01	The first day in our data
`last_seen`	string	2026-10-28	The latest day in our data

Example answer

The example answer appears here as soon as this endpoint's data is live. Run above shows a real answer with your key.

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

PreviousA show's statistics NextMost aired last week