# TV Schedule API

> TV listings, shows and airing patterns by country and channel, as JSON. Every time is UTC. One key, from https://tvschedule.org/account.

- [The whole manual](https://tvschedule.org/documentation/manual.md): every endpoint, parameter and field in one file
- [OpenAPI](https://tvschedule.org/openapi.json)
- [MCP server](https://tvschedule.org/documentation/mcp): https://tvschedule.org/mcp

## Guides
- [Quick start](https://tvschedule.org/documentation/quick-start): A key, the first call and the answer, in five minutes.
- [Authentication](https://tvschedule.org/documentation/authentication): Sending your key, keeping it safe and rotating it.
- [Plans and limits](https://tvschedule.org/documentation/plans): What each plan reads, its pace and its allowance.
- [Pagination](https://tvschedule.org/documentation/pagination): Walking long lists with next_cursor.
- [Errors](https://tvschedule.org/documentation/errors): Every error code, what it means and what to do.
- [MCP server](https://tvschedule.org/documentation/mcp): Adding the API to Claude, ChatGPT, Cursor and Claude Code.
- [Directory guide](https://tvschedule.org/documentation/directory): Countries, channels and the ids every other endpoint takes.
- [Listings guide](https://tvschedule.org/documentation/listings): A channel's day, a country's day and XMLTV, with time zones.
- [Shows guide](https://tvschedule.org/documentation/shows): Finding a show and where it airs next.
- [Patterns guide](https://tvschedule.org/documentation/patterns): Usual slots, airing fingerprints, statistics and the weekly charts.
- [MCP tools](https://tvschedule.org/documentation/mcp-tools): Every tool the MCP server offers, and the endpoint behind it.
- [Changelog](https://tvschedule.org/documentation/changelog): What changed in the API, newest first.

## Endpoints
- [GET /v1/countries](https://tvschedule.org/documentation/countries): Every country with listings, its channel count and programmes today.
- [GET /v1/countries/{cc}/channels](https://tvschedule.org/documentation/country-channels): Every channel in a country, with ids, names and categories.
- [GET /v1/channels/search/{q}](https://tvschedule.org/documentation/channel-search): Find a channel by name, alias or call sign.
- [GET /v1/channels/{id}](https://tvschedule.org/documentation/channel): One channel: names, country, languages, categories and launch year.
- [GET /v1/channels/{id}/schedule/{date}](https://tvschedule.org/documentation/channel-schedule): A channel's day, slot by slot, times in UTC. The date is YYYY-MM-DD, yesterday, today or tomorrow.
- [GET /v1/countries/{cc}/schedule/{date}](https://tvschedule.org/documentation/country-schedule): Every channel in a country for a day, 50 channels a page.
- [GET /v1/xmltv/channels/{id}](https://tvschedule.org/documentation/xmltv): A channel as an XMLTV file, today and the days ahead in your window.
- [GET /v1/shows/search/{q}](https://tvschedule.org/documentation/show-search): Find a show by any of its titles.
- [GET /v1/shows/{id}](https://tvschedule.org/documentation/show): One show: titles, network, genres, status and premiere.
- [GET /v1/shows/{id}/airings](https://tvschedule.org/documentation/show-airings): Where and when a show airs in the days ahead, first runs and repeats.
- [GET /v1/shows/{id}/pattern](https://tvschedule.org/documentation/show-pattern): A show's usual slot, its day by hour fingerprint and repeat share.
- [GET /v1/shows/{id}/stats](https://tvschedule.org/documentation/show-stats): Airing counts by channel, country and year, first and last aired.
- [GET /v1/channels/{id}/stats](https://tvschedule.org/documentation/channel-stats): Days held, programmes a week, genre mix and repeat share for a channel.
- [GET /v1/countries/{cc}/most-aired](https://tvschedule.org/documentation/most-aired): The most aired shows and films in a country last week, with the change.
- [GET /v1/countries/{cc}/repeats](https://tvschedule.org/documentation/repeats): The most repeated shows and films in a country last week.
- [GET /v1/usage](https://tvschedule.org/documentation/usage): Your plan, calls today and this month, limits and the data window. Not counted.