---
name: tvguideapi
description: Look up TV listings, what is on now, channels, shows and episodes, and which channels show a sports event live, in any country. Use when someone asks what is on TV, when a show airs, or where to watch a match.
---

# TV Guide API

TV listings for every channel worldwide: what is on now and next, each channel's schedule, shows and episodes, films, and which channels show a sports event live or as a repeat. Operated by DeveloperData.net.

## When to use it

- Use it when someone asks what is on TV, when or where a show airs, or which channel shows a match.
- Do not use it for streaming catalogues, box office figures or reviews: it holds broadcast schedules.

## Access

- A free key: sign in at https://tvguideapi.com/login, then make a key on https://tvguideapi.com/account.
- Base URL `https://api.tvguideapi.com/v1`. Send the key as `Authorization: Bearer <key>` (or `X-API-Key: <key>`). A key in the query string is refused.
- Every answer is JSON `{"data": ..., "meta": ...}`. Every time is UTC. Ids are short codes from the API itself: find a channel with `GET /channels/search?q=`, a show with `GET /shows/search?q=`.

## Common calls

```
curl -H "Authorization: Bearer $KEY" "https://api.tvguideapi.com/v1/now?country=GB"
curl -H "Authorization: Bearer $KEY" "https://api.tvguideapi.com/v1/channels/search?q=bbc+one&country=GB"
curl -H "Authorization: Bearer $KEY" "https://api.tvguideapi.com/v1/channels/{id}/schedule?date=2026-10-09&tz=Europe/London"
curl -H "Authorization: Bearer $KEY" "https://api.tvguideapi.com/v1/events/live?country=GB&sport=football"
```

## Every endpoint

### Channels
- `GET /v1/channels`: Every TV channel in the registry, filtered by country, language, category or logo, with one stable id per channel across all our sources.
- `GET /v1/channels/search`: Find a TV channel by its name, an alias or a call sign, in any country, and get the id every other endpoint takes.
- `GET /v1/channels/{id}`: One TV channel in full: its names, owner, country, languages, categories, logo, website, launch year and the guide feeds behind it.
- `GET /v1/channels/{id}/schedule`: A TV channel's day slot by slot: start and stop in UTC, title, description, category, and the series and episode where we matched it.
- `GET /v1/channels/{id}/now`: What is on a TV channel right now and what comes next, with how far through the current programme it is.
- `GET /v1/channels/{id}/next`: The next programmes on a TV channel, as many as you ask for, each with its times in UTC and its episode where matched.
- `GET /v1/channels/{id}/free-view`: The official free ways to watch a TV channel: the broadcaster's own player, or the FAST service (Pluto TV, Samsung TV Plus, Plex, Roku) that carries it, with the watch page and the country.
- `GET /v1/channels/{id}/history`: Past schedules for a TV channel from the archive, slot by slot over any window of up to 31 days, with the same fields as today. (paid plans)

### Countries
- `GET /v1/countries`: Every country we hold TV listings for, with its channel count, its guide feeds and how many programmes it has today.
- `GET /v1/countries/{cc}`: One country's TV guide at a glance: channels, guide feeds, when its data last changed and how full each field is today.
- `GET /v1/countries/{cc}/channels`: Every TV channel in one country, ordered the way its own guides list them, with ids, names, logos and categories.
- `GET /v1/countries/{cc}/now`: What is on now on every TV channel in a country, with what comes next, in one call.
- `GET /v1/countries/{cc}/tonight`: Prime time tonight on every TV channel in a country, from the local hour you choose, in one grid.
- `GET /v1/countries/{cc}/coverage`: How full the TV data is for a country on a day: the share of programmes with a description, category, episode number and more.

### Guide
- `GET /v1/guide`: A TV guide grid for up to 50 channels over a window you choose, every slot with its times in UTC, ready to draw.
- `GET /v1/now`: What is on now on the TV channels you name, or across a whole country, with what comes next on each.
- `GET /v1/next`: The next programme on each of the TV channels you name, or across a whole country.
- `GET /v1/listings/{id}`: One TV listing slot in full: times, title, sub-title, description, category, rating, flags, its episode and the feeds it came from.
- `GET /v1/listings/search`: Find upcoming TV programmes by words in their title, sub-title or description, in the countries you choose.
- `GET /v1/premieres`: New episodes and first showings on a day, across the TV channels of the countries you choose.
- `GET /v1/live`: TV slots marked live, on now and later today, in the countries you choose.
- `GET /v1/xmltv`: A country or a set of channels as a standard XMLTV file, up to 14 days ahead, for media centres and IPTV players. (paid plans)

### Shows and episodes
- `GET /v1/shows/search`: Find a TV show by any of its titles and get its id, network, status and premiere date.
- `GET /v1/shows/{id}`: One TV show: its titles, network, genres, status, premiere and its ids at TVmaze, TheTVDB, IMDb and Wikidata.
- `GET /v1/shows/{id}/episodes`: Every episode of a TV show, season by season, with numbers, names and original air dates.
- `GET /v1/shows/{id}/cast`: Who is in a show: each person with the character they play, whether they appear as themselves or as a voice, their country and a picture.
- `GET /v1/shows/{id}/airings`: When and where a TV show airs next, in every country or the ones you choose, first runs and repeats.
- `GET /v1/shows/{id}/history`: Every past airing of a TV show that the archive holds, over a window you choose. (paid plans)
- `GET /v1/episodes/{id}`: One TV episode: its show, season, number, name, runtime and original air date.
- `GET /v1/episodes/{id}/airings`: Every showing of one TV episode we hold, the first run and every repeat, on every channel. (paid plans)
- `GET /v1/networks`: TV networks and streaming services, by country, with their ids.
- `GET /v1/networks/{id}/shows`: The TV shows of one network or streaming service, running or ended.

### Sport and events
- `GET /v1/sports`: The sports with events on TV this week, and how many events each has.
- `GET /v1/leagues`: Sports competitions with events on TV, by sport and country, with their ids.
- `GET /v1/leagues/{id}/events`: A competition's fixtures over a window, each with every channel showing it and whether it is live. (paid plans)
- `GET /v1/events`: Sports events on TV by sport, league and day, in every country or only those on air where you are. (paid plans)
- `GET /v1/events/{id}`: One sports event: its teams, league, round, venue and start time, with the channels showing it. (paid plans)
- `GET /v1/events/{id}/broadcasts`: Every TV channel showing a sports event, country by country, and whether each showing is live, delayed or a repeat. (paid plans)
- `GET /v1/events/live`: Sports events live on TV right now, in a country or everywhere, with the channels showing them. (paid plans)
- `GET /v1/events/upcoming`: The next sports events on TV with their channels, soonest first, over the hours ahead you choose. (paid plans)
- `GET /v1/events/{id}/replays`: Later showings of a sports event: repeats, highlights and delayed broadcasts, on every channel. (paid plans)
- `GET /v1/teams/{id}/events`: Where a team's matches are shown on TV, in every country or the ones you choose. (paid plans)
- `GET /v1/rights`: Who held the TV rights to a competition, by country and season, from the yearly versions of public broadcaster lists. (paid plans)

### Venue plans
- `GET /v1/venue/tonight`: Tonight's sport for a bar or venue: live events first, one row per event with every channel you receive that has it. (paid plans)
- `GET /v1/venue/week`: The week ahead for a bar or venue, day by day, live events first, on the channels you receive. (paid plans)

### Account and meta
- `GET /v1/me`: Your plan, your keys by prefix and label, and your daily limit.
- `GET /v1/usage`: Your calls per day and per endpoint over the days you choose.
- `GET /v1/status`: How fresh every source is right now, and whether the API is answering normally. No key needed.
- `GET /v1/fields`: How full each listing field is today, country by country.
- `GET /v1/sources`: Every source behind the data, the fields it supplies, its licence and the credit it asks for.

### Agents
- `POST /mcp`: The Model Context Protocol server: the same data as tools for Claude, ChatGPT and other assistants.
- `GET /.well-known/agent-skills/index.json`: The index agents read to find the tvguideapi.com skill. No key needed.

## MCP server

`https://tvguideapi.com/mcp`, streamable HTTP, the same key as a bearer token. Tools: `whats_on_now`, `channel_day`, `find_channel`, `search_listings`, `tonight`, `find_show`, `next_airing`, `show_episodes`, `sport_today`, `where_to_watch`, `live_sport_now`, `my_usage`. One tool call counts as one API call.

## Limits

- Free key: 60 calls a minute, 500 a day.
- Live: 120 calls a minute, 300,000 a month.
- Archive: 180 calls a minute, 750,000 a month.
- Complete: 600 calls a minute, 3,000,000 a month.
- The free key reads yesterday and today; shows, films and events come back empty with a note in `meta.notes`. Paid plans from Archive up read back to 2010.
- Headers on every answer: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-Quota-Remaining`.

## Errors

Every error is `{"error": {"code": "...", "message": "...", "docs": "..."}}`.

- `400 bad_request`: a parameter is missing or malformed.
- `401 unauthorized`: no key, or a key that is not active.
- `403 upgrade_required`: the endpoint needs a paid plan; tell the person so.
- `404 not_found`: no such id or route.
- `422 unknown_parameter`: the answer lists the parameters the endpoint takes.
- `429 rate_limited` or `429 quota_exceeded`: wait for `Retry-After` before asking again.

## Workflow

1. Find the id: `GET /channels/search?q=` for a channel, `GET /shows/search?q=` for a show, `GET /events?sport=&date=` for a match.
2. Ask for the day with `date` and `tz`; the answer stays UTC, so convert times for the person you are answering.
3. Follow `meta.next_cursor` as `cursor` until it is null.
4. A broadcast with `kind` `repeat` is never live: say so when someone asks where to watch a match live.
5. Fields under `episode` and `show` come from TVmaze (CC BY-SA): credit TVmaze when you show them.

Full reference: https://tvguideapi.com/documentation/manual.md