# TV Schedule API manual TV listings, shows and airing patterns by country and channel, as JSON over HTTPS. Base URL: https://api.tvschedule.org/v1. Every time is UTC with a Z. Docs: https://tvschedule.org/documentation ## Authentication Send your key as `Authorization: Bearer ` or `X-API-Key: `. A key in the address is refused with 400. Get a free key at https://tvschedule.org/account. ## Plans - **Free key** (free): reads yesterday's listings and the directory. 30 calls a minute, 200 calls a day, 1 key. - **Live** ($39 a month or $390 a year): reads 7 days back to 7 days ahead, shows, and 90 days of patterns and statistics. 120 calls a minute, 300,000 calls a month, 1 key. - **Complete** ($79 a month or $790 a year): reads 7 days back to 7 days ahead, shows, and all time of patterns and statistics. 600 calls a minute, no monthly limit, 5 keys. Every answer is `{"data": ..., "meta": {...}}`. Errors are `{"error": {"code", "message", "docs"}}`. Long lists carry `meta.next_cursor`; pass it back as `cursor`. ## Endpoints ### GET /v1/countries Every country with listings, its channel count and programmes today. Plan: free key and up. MCP tool: `list_countries`. - Returns: `code`, `name`, `channels`, `channels_on_air_today`, `programmes_today` ``` curl "https://api.tvschedule.org/v1/countries" -H "Authorization: Bearer $TVS_KEY" ``` ### GET /v1/countries/{cc}/channels Every channel in a country, with ids, names and categories. Plan: free key and up. MCP tool: `country_channels`. - `cc` (path, required): The country, as a two-letter code such as GB. - `limit` (query, integer, 1 to 500): How many to return. - `cursor` (query, string): The next_cursor from the page before, to read the next page. - Returns: `id`, `name`, `country`, `categories`, `in_registry` ``` curl "https://api.tvschedule.org/v1/countries/US/channels" -H "Authorization: Bearer $TVS_KEY" ``` ### GET /v1/channels/search/{q} Find a channel by name, alias or call sign. Plan: free key and up. MCP tool: `find_channel`. - `q` (path, required): A channel name, alias or call sign, two characters or more. - `country` (query, string, A two-letter country code): Only channels or airings in this country. - `limit` (query, integer, 1 to 100): How many to return. - Returns: `id`, `name`, `country`, `categories`, `in_registry` ``` curl "https://api.tvschedule.org/v1/channels/search/BBC+One" -H "Authorization: Bearer $TVS_KEY" ``` ### GET /v1/channels/{id} One channel: names, country, languages, categories and launch year. Plan: free key and up. MCP tool: `get_channel`. - `id` (path, required): The channel id, from a country's channels or channel search. - Returns: `id`, `name`, `country`, `categories`, `owner`, `network`, `launched`, `closed`, `website`, `in_registry`, `also_known_as`, `feeds` ``` curl "https://api.tvschedule.org/v1/channels/ch_jw83a3xg" -H "Authorization: Bearer $TVS_KEY" ``` ### GET /v1/channels/{id}/schedule/{date} A channel's day, slot by slot, times in UTC. The date is YYYY-MM-DD, yesterday, today or tomorrow. Plan: free key and up. MCP tool: `channel_schedule`. - `id` (path, required): The channel id, from a country's channels or channel search. - `date` (path, required): The day: YYYY-MM-DD, yesterday, today or tomorrow. - `tz` (query, string, A time zone name, such as Europe/London): Which local day to cut, as a time zone name. Times in the answer stay UTC. - Returns: `id`, `channel`, `start`, `stop`, `title`, `sub_title`, `description`, `category`, `episode_num`, `lang`, `rating`, `flags`, `episode`, `film` ``` curl "https://api.tvschedule.org/v1/channels/ch_jw83a3xg/schedule/yesterday" -H "Authorization: Bearer $TVS_KEY" ``` ### GET /v1/countries/{cc}/schedule/{date} Every channel in a country for a day, 50 channels a page. Plan: Live and Complete. MCP tool: `country_schedule`. - `cc` (path, required): The country, as a two-letter code such as GB. - `date` (path, required): The day: YYYY-MM-DD, yesterday, today or tomorrow. - `cursor` (query, string): The next_cursor from the page before, to read the next page. - `tz` (query, string, A time zone name, such as Europe/London): Which local day to cut, as a time zone name. Times in the answer stay UTC. - Returns: `id`, `channel`, `start`, `stop`, `title`, `sub_title`, `description`, `category`, `episode_num`, `lang`, `rating`, `flags`, `episode`, `film` ``` curl "https://api.tvschedule.org/v1/countries/US/schedule/yesterday" -H "Authorization: Bearer $TVS_KEY" ``` ### GET /v1/xmltv/channels/{id} A channel as an XMLTV file, today and the days ahead in your window. Plan: Live and Complete. - `id` (path, required): The channel id, from a country's channels or channel search. - `days` (query, integer, 1 to 7): How many days ahead to cover, within your plan. - Returns: an XMLTV file (application/xml). ``` curl "https://api.tvschedule.org/v1/xmltv/channels/ch_jw83a3xg" -H "Authorization: Bearer $TVS_KEY" ``` ### GET /v1/shows/search/{q} Find a show by any of its titles. Plan: Live and Complete. MCP tool: `find_show`. - `q` (path, required): Any title of the show, two characters or more. - `limit` (query, integer, 1 to 100): How many to return. - Returns: `id`, `name`, `type`, `status`, `premiered`, `network` ``` curl "https://api.tvschedule.org/v1/shows/search/EastEnders" -H "Authorization: Bearer $TVS_KEY" ``` ### GET /v1/shows/{id} One show: titles, network, genres, status and premiere. Plan: Live and Complete. MCP tool: `get_show`. - `id` (path, required): The show id, from show search. - Returns: `id`, `name`, `type`, `status`, `premiered`, `network`, `ended`, `language`, `genres`, `runtime`, `country`, `official_site`, `imdb` ``` curl "https://api.tvschedule.org/v1/shows/sh_sdkgxsfs" -H "Authorization: Bearer $TVS_KEY" ``` ### GET /v1/shows/{id}/airings Where and when a show airs in the days ahead, first runs and repeats. Plan: Live and Complete. MCP tool: `show_airings`. - `id` (path, required): The show id, from show search. - `country` (query, string, A two-letter country code): Only channels or airings in this country. - `days` (query, integer, 1 to 7): How many days ahead to cover, within your plan. - Returns: `channel`, `start`, `stop`, `title`, `episode`, `flags` ``` curl "https://api.tvschedule.org/v1/shows/sh_sdkgxsfs/airings" -H "Authorization: Bearer $TVS_KEY" ``` ### GET /v1/shows/{id}/pattern A show's usual slot, its day by hour fingerprint and repeat share. Plan: Live and Complete. MCP tool: `show_pattern`. - `id` (path, required): The show id, from show search. - Returns: `usual`, `grid`, `main_channel`, `airings`, `channels`, `repeat_share`, `window_days` ``` curl "https://api.tvschedule.org/v1/shows/sh_sdkgxsfs/pattern" -H "Authorization: Bearer $TVS_KEY" ``` ### GET /v1/shows/{id}/stats Airing counts by channel, country and year, first and last aired. Plan: Live and Complete. MCP tool: `show_stats`. - `id` (path, required): The show id, from show search. - Returns: `airings`, `first_runs`, `repeats`, `channels`, `first_seen`, `last_seen` ``` curl "https://api.tvschedule.org/v1/shows/sh_sdkgxsfs/stats" -H "Authorization: Bearer $TVS_KEY" ``` ### GET /v1/channels/{id}/stats Days held, programmes a week, genre mix and repeat share for a channel. Plan: Live and Complete. MCP tool: `channel_stats`. - `id` (path, required): The channel id, from a country's channels or channel search. - Returns: `programmes`, `shows`, `repeat_share`, `top_genres`, `first_seen`, `last_seen` ``` curl "https://api.tvschedule.org/v1/channels/ch_jw83a3xg/stats" -H "Authorization: Bearer $TVS_KEY" ``` ### GET /v1/countries/{cc}/most-aired The most aired shows and films in a country last week, with the change. Plan: Live and Complete. MCP tool: `most_aired`. - `cc` (path, required): The country, as a two-letter code such as GB. - `limit` (query, integer, 1 to 50): How many to return. - Returns: `rank`, `id`, `kind`, `name`, `genre`, `airings`, `change` ``` curl "https://api.tvschedule.org/v1/countries/GB/most-aired" -H "Authorization: Bearer $TVS_KEY" ``` ### GET /v1/countries/{cc}/repeats The most repeated shows and films in a country last week. Plan: Live and Complete. MCP tool: `repeats`. - `cc` (path, required): The country, as a two-letter code such as GB. - `limit` (query, integer, 1 to 50): How many to return. - Returns: `rank`, `id`, `kind`, `name`, `genre`, `airings`, `change` ``` curl "https://api.tvschedule.org/v1/countries/GB/repeats" -H "Authorization: Bearer $TVS_KEY" ``` ### GET /v1/usage Your plan, calls today and this month, limits and the data window. Not counted. Plan: free key and up. MCP tool: `check_usage`. - Returns: `plan`, `plan_name`, `key_prefix`, `calls_today`, `calls_month`, `limits`, `resets`, `window` ``` curl "https://api.tvschedule.org/v1/usage" -H "Authorization: Bearer $TVS_KEY" ``` ## Errors - `bad_request` (400): 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. - `unauthorized` (401): No key was sent, or it is not an active TV Schedule key. Send it as Authorization: Bearer or X-API-Key. Your keys are in your account. - `upgrade_required` (403): 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. - `not_found` (404): Nothing has that id, or there is no endpoint at that address. Take ids from the search and directory endpoints. Every address is listed in these docs. - `unknown_parameter` (422): A query parameter this endpoint does not take. The message lists the ones it does take. - `rate_limited` (429): Faster than your plan's pace per minute. Wait for Retry-After seconds. The X-RateLimit headers show where you are. - `quota_exceeded` (429): 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. - `server_error` (500): 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. ## MCP server Address: https://tvschedule.org/mcp (Streamable HTTP). Sign in with OAuth from Claude or ChatGPT, or send your key as `Authorization: Bearer `. Tools: - `check_usage`: Your plan, calls today and this month, limits and the data window. Not counted. - `list_countries`: Every country with listings, its channel count and programmes today. - `country_channels`: Every channel in a country, with ids, names and categories. - `find_channel`: Find a channel by name, alias or call sign. - `get_channel`: One channel: names, country, languages, categories and launch year. - `channel_schedule`: A channel's day, slot by slot, times in UTC. The date is YYYY-MM-DD, yesterday, today or tomorrow. - `country_schedule`: Every channel in a country for a day, 50 channels a page. Live and Complete plans. - `find_show`: Find a show by any of its titles. Live and Complete plans; the free key gets an empty answer with a note. - `get_show`: One show: titles, network, genres, status and premiere. Live and Complete plans; the free key gets an empty answer with a note. - `show_airings`: Where and when a show airs in the days ahead, first runs and repeats. Live and Complete plans; the free key gets an empty answer with a note. - `show_pattern`: A show's usual slot, its day by hour fingerprint and repeat share. Live and Complete plans; the free key gets an empty answer with a note. - `show_stats`: Airing counts by channel, country and year, first and last aired. Live and Complete plans; the free key gets an empty answer with a note. - `channel_stats`: Days held, programmes a week, genre mix and repeat share for a channel. Live and Complete plans; the free key gets an empty answer with a note. - `most_aired`: The most aired shows and films in a country last week, with the change. Live and Complete plans. - `repeats`: The most repeated shows and films in a country last week. Live and Complete plans.