API Docs / Patterns

A show's airing pattern

Live and CompleteFree key: empty with a noteMCP: show_pattern

A show's usual slot, worked out from every airing we hold, as a weekday by hour grid with its repeat share.

ReturnsThe show's fingerprint

Up toOne record

FreshUp to an hour old

PlanLive and Complete

GEThttps://api.tvschedule.org/v1/shows/{id}/pattern

What it is for

We count every time a show aired and turn it into its fingerprint: the slot it usually takes in words ("Mon to Thu around 19:30"), the channel that airs it most, a 7 by 24 grid of airings by weekday and hour, and how many of those airings were repeats.

Live reads the last 90 days and Complete reads all time. It is how you show "usually on" without waiting for this week's listings, or spot a show moved to a new slot.

"Usually on"

Show the regular slot on a show page.

Heatmaps

Draw the grid as a weekday by hour heatmap.

Spotting moves

Notice when a show leaves its usual slot.

/v1/shows/{id}/patternthen/v1/shows/{id}/stats /v1/shows/{id}/airings /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.

A show's airing pattern

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/shows/sh_sdkgxsfs/pattern

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/sh_sdkgxsfs/pattern" \
  -H "X-API-Key: <your key>"

Parameters

Name	In	Type	Example	What it does
`id`required	path	string	sh_sdkgxsfs	The show id, from show search.

Returns

One record under data, with meta beside it.

Field	Type	Example	What it holds
`usual`	object	Mon to Thu around 19:30	Its usual slot in words, such as "Mon to Thu around 19:30". Empty when it has no regular slot.
`grid`	array		Airings by weekday (7 rows, Monday first) and hour (24 columns), in the show's home country's local time.
`main_channel`	object		The channel that airs it most: id and name.
`airings`	integer	1912	How many times it aired
`channels`	integer	4	How many channels
`repeat_share`	number	0.38	The share of airings that were repeats, from 0 to 1.
`window_days`	integer	90	The days counted: 90 on Live, all time on Complete.

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

Next calls

PreviousPatterns guide NextA show's statistics