API Docs / Patterns

Most aired last week

Live and CompleteMCP: most_aired

The shows and films a country aired most last week, ranked, with how far each moved on the week before.

ReturnsA ranked chart

Up to50 a call, 20 by default

FreshUp to an hour old

PlanLive and Complete

GEThttps://api.tvschedule.org/v1/countries/{cc}/most-aired

What it is for

Each week we count every airing in a country and rank the shows and films by how often they aired. Each row has its rank, whether it is a show or a film, its main genre, its count and its change in places on the week before.

It is a ready-made weekly chart for a country, and a quick read on what fills a market's schedules.

Weekly charts

Publish "the most aired shows in the UK this week".

Trends

Watch which shows climb or fall week on week.

Programming research

See what fills a country's schedules.

/v1/countries/{cc}/most-airedthen/v1/countries/{cc}/repeats /v1/shows/{id}/stats /v1/countries/{cc}/schedule/{date}

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.

Most aired last week

Needs Live or Complete

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/GB/most-aired

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/GB/most-aired" \
  -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.
`limit`	query	integer	10	How many rows of the chart, 20 when left out. 1 to 50

Returns

A list under data, with meta.count beside it.

Field	Type	Example	What it holds
`rank`	integer	1	Its place in the chart, 1 first.
`id`	string	sh_8f2k1m0q	The show or film id.
`kind`	string	show	show or film.
`name`	string	Homes Under the Hammer	Its name
`genre`	string	Factual	Its main genre
`airings`	integer	412	How many times it aired that week.
`change`	integer	2	Places up (positive) or down (negative) on the week before.

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`	The weekly charts are on Live and Complete.	The message names the plan that does. Upgrade on the same key at /pricing.
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

PreviousA channel's statistics NextMost repeated last week