# TV Guide API complete reference > TV guide data for every channel worldwide: listings, now and next, shows and episodes, and the sport on air with live told apart from repeats, under one key. | | | | --- | --- | | Base URL | `https://api.tvguideapi.com/v1` | | Authentication | `Authorization: Bearer ` request header | | Site | https://tvguideapi.com | | Endpoints | 52 | | Generated | 12 October 2026 | | Canonical copy | https://tvguideapi.com/documentation/manual.md | ## Before anything else This is **factual schedule data**: what is on, where and when, as the channels publish it, corrected where a feed runs on the wrong clock. No endpoint carries predictions, ratings, tips or betting advice. What the data does **not** contain, on any plan, at any price: - no video, streams or links to streams; - no audience or viewing figures; - no cable or satellite channel numbers by provider (lineups); - no cast and crew lists; - no parental rating where the channel's own guide does not send one. Every answer is JSON with two keys: `data` (an object, or a list) and `meta` (`count` and `next` on lists, `took_ms` always). Fields we join in, never sent by the channel (the `episode` object, events), sit in their own objects and say how they were matched. Every time is UTC. ## Plans | Plan | Price | What it reads | Calls | | --- | --- | --- | --- | | Free key | Free | Yesterday and today, on every endpoint marked Free key | 500 a day | | Live | $39/month, or $390/year | Every endpoint today and ahead: shows, episodes, films, sport and XMLTV | 300,000 a month | | Archive | $79/month, or $790/year | Everything in Live, with listings back to 2010 and episodes back to 1908 | 750,000 a month | | Complete | $249/month, or $2490/year | Everything in Archive, with XMLTV and CSV exports and the highest limits | 3,000,000 a month | ## Coverage Counted from the data, not claimed, and rounded down: 148 countries, 31,000+ channels, 71M+ listings held, 90,000+ shows with their episodes back to 1908, and 155,000+ sports events found in the listings. `GET /v1/countries` returns the same figures per country, and `GET /v1/countries/{cc}/coverage` how full each field is. ## Endpoints ### Channels (8) The channel registry: one id per channel across every source, with names, owners, logos, launch years and each channel's schedule. #### `GET /v1/channels` **List channels.** Every TV channel in the registry, filtered by country, language, category or logo, with one stable id per channel across all our sources. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/channels` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `country` | query | list | no | Country codes, ISO 3166-1 alpha-2, comma separated. | `GB` | | `lang` | query | list | no | Language codes, ISO 639-3. | `eng` | | `category` | query | string | no | news, sports, kids, movies, music, general... | `sports` | | `has_logo` | query | boolean | no | Only channels with a logo. | `true` | | `limit` | query | integer | no | Page size, 1 to 500. Defaults to 100. | `100` | | `cursor` | query | string | no | The cursor from the previous answer's `meta.next`. See [Paging and fields](https://tvguideapi.com/documentation/paging). | | | `fields` | query | list | no | Only these fields, comma separated. | `start,title,episode` | Errors: `key_missing`, `limit_reached` ```json { "data": [ { "id": "ch_jw83a3xg", "name": "BBC One", "country": "GB", "languages": [ "eng" ], "categories": [ "general" ], "owner": "BBC", "launched": 1936, "website": "https://www.bbc.co.uk/bbcone", "feeds": 3 } ], "meta": { "count": 612, "next": "c_8f21a0", "took_ms": 41 } } ``` #### `GET /v1/channels/search` **Find a channel.** Find a TV channel by its name, an alias or a call sign, in any country, and get the id every other endpoint takes. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/channels/search` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `q` | query | string | yes | Name, alias or call sign. | `bbc one` | | `country` | query | list | no | Country codes, ISO 3166-1 alpha-2, comma separated. | `GB` | | `limit` | query | integer | no | Page size, 1 to 500. Defaults to 100. | `100` | Errors: `bad_parameter`, `key_missing`, `limit_reached` ```json { "data": [ { "id": "ch_jw83a3xg", "name": "BBC One", "country": "GB", "languages": [ "eng" ], "categories": [ "general" ], "owner": "BBC", "launched": 1936, "website": "https://www.bbc.co.uk/bbcone", "feeds": 3 } ], "meta": { "count": 1, "next": null, "took_ms": 41 } } ``` #### `GET /v1/channels/{id}` **Get a channel.** One TV channel in full: its names, owner, country, languages, categories, logo, website, launch year and the guide feeds behind it. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/channels/{id}` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The channel id. Ids come from [Find a channel](https://tvguideapi.com/documentation/channels-search). | `ch_jw83a3xg` | | `fields` | query | list | no | Only these fields, comma separated. | `start,title,episode` | Errors: `key_missing`, `not_found`, `id_merged`, `limit_reached` ```json { "data": { "id": "ch_jw83a3xg", "name": "BBC One", "country": "GB", "languages": [ "eng" ], "categories": [ "general" ], "owner": "BBC", "launched": 1936, "website": "https://www.bbc.co.uk/bbcone", "feeds": 3 }, "meta": { "took_ms": 23 } } ``` #### `GET /v1/channels/{id}/schedule` **A channel's 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. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/channels/{id}/schedule` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The channel id. Ids come from [Find a channel](https://tvguideapi.com/documentation/channels-search). | `ch_jw83a3xg` | | `date` | query | date | no | The day, `YYYY-MM-DD`. Defaults to today. | `2026-10-07` | | `tz` | query | string | no | Which local day to cut, as an IANA zone. The times in the answer stay UTC. See [Times and days](https://tvguideapi.com/documentation/times-and-days). | `Europe/London` | | `fields` | query | list | no | Only these fields, comma separated. | `start,title,episode` | Errors: `key_missing`, `not_found`, `id_merged`, `limit_reached` A day is cut at midnight in the zone you give with `tz`, or UTC. A slot that crosses midnight is in both days. The `episode` object is joined in, never sent by the channel; `episode.matched_by` says how: `airtime`, `episode-number`, `episode-title` or `same-description`. Where the channel's own guide sent no description, episode title, number, picture or category, it is taken from another guide feed's slot for the same programme (same channel, start and title), and `borrowed` lists which fields and from which feed; a slot matched to its TVmaze episode that still had no episode title, number or picture takes them from that episode, marked `tvmaze` in `borrowed`. `genres` gives the same genre names for every feed (news, sport, film, drama, comedy, kids, documentary and so on), mapped from each guide's own categories in its own language, or, where the guide sent none, from the genres of the TVmaze show the slot is joined to. ```json { "data": [ { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z", "title": "EastEnders", "sub_title": "Episode 7012", "category": [ "Soap" ], "episode": { "show_id": "sh_e29nzc1x", "episode_id": "ep_610mmeyh", "season": 41, "number": 157, "name": "Episode 7012", "orig_air": "2026-10-07", "matched_by": "airtime", "source": "tvmaze" }, "flags": { "new": true, "live": false, "repeat": false } }, { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:30:00Z", "stop": "2026-10-07T20:00:00Z", "title": "The One Show", "category": [ "Magazine" ], "flags": { "new": true, "live": true, "repeat": false } } ], "meta": { "count": 38, "next": "c_8f21a0", "took_ms": 41 } } ``` #### `GET /v1/channels/{id}/now` **On a channel now.** What is on a TV channel right now and what comes next, with how far through the current programme it is. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/channels/{id}/now` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The channel id. Ids come from [Find a channel](https://tvguideapi.com/documentation/channels-search). | `ch_jw83a3xg` | Errors: `key_missing`, `not_found`, `id_merged`, `limit_reached` ```json { "data": { "channel": "ch_jw83a3xg", "now": { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z", "title": "EastEnders", "episode": { "show_id": "sh_e29nzc1x", "episode_id": "ep_610mmeyh", "season": 41, "number": 157, "name": "Episode 7012", "orig_air": "2026-10-07", "matched_by": "airtime", "source": "tvmaze" }, "progress": 0.42 }, "next": { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:30:00Z", "stop": "2026-10-07T20:00:00Z", "title": "The One Show" } }, "meta": { "took_ms": 23 } } ``` #### `GET /v1/channels/{id}/next` **Next on a channel.** The next programmes on a TV channel, as many as you ask for, each with its times in UTC and its episode where matched. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/channels/{id}/next` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The channel id. Ids come from [Find a channel](https://tvguideapi.com/documentation/channels-search). | `ch_jw83a3xg` | | `count` | query | integer | no | How many, 1 to 20. Defaults to 3. | `3` | Errors: `key_missing`, `not_found`, `id_merged`, `limit_reached` ```json { "data": [ { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z", "title": "EastEnders", "sub_title": "Episode 7012", "category": [ "Soap" ], "episode": { "show_id": "sh_e29nzc1x", "episode_id": "ep_610mmeyh", "season": 41, "number": 157, "name": "Episode 7012", "orig_air": "2026-10-07", "matched_by": "airtime", "source": "tvmaze" }, "flags": { "new": true, "live": false, "repeat": false } }, { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:30:00Z", "stop": "2026-10-07T20:00:00Z", "title": "The One Show", "category": [ "Magazine" ], "flags": { "new": true, "live": true, "repeat": false } } ], "meta": { "count": 38, "next": "c_8f21a0", "took_ms": 41 } } ``` #### `GET /v1/channels/{id}/free-view` **Watch a channel free.** 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. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/channels/{id}/free-view` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The channel id. Ids come from [Find a channel](https://tvguideapi.com/documentation/channels-search). | `ch_jw83a3xg` | Errors: `key_missing`, `not_found`, `id_merged`, `limit_reached` Watch pages only, never stream addresses. Works for guide-only ids too (`g:...`): most FAST channels are not in the channel registry, and their free watch page is joined to their guide id. ```json { "data": [ { "service": "Pluto TV", "kind": "fast", "country": "US", "watch_url": "https://pluto.tv/live-tv/", "signup": "none", "checked": "2026-10-07" } ], "meta": { "count": 1, "next": null, "took_ms": 41 } } ``` #### `GET /v1/channels/{id}/history`, paid plans **A channel's past schedules.** 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. Plans: paid plans. Data from 2023. Address: `https://api.tvguideapi.com/v1/channels/{id}/history` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The channel id. Ids come from [Find a channel](https://tvguideapi.com/documentation/channels-search). | `ch_jw83a3xg` | | `from` | query | datetime | yes | Window start, UTC. | `2026-10-01T00:00:00Z` | | `to` | query | datetime | yes | Window end, UTC; at most 31 days after `from`. | `2026-10-02T00:00:00Z` | | `cursor` | query | string | no | The cursor from the previous answer's `meta.next`. See [Paging and fields](https://tvguideapi.com/documentation/paging). | | Errors: `bad_parameter`, `key_missing`, `plan_required`, `not_found`, `id_merged`, `limit_reached` Where each country's archive starts is in [Country coverage](https://tvguideapi.com/documentation/countries-country-coverage). ```json { "data": [ { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z", "title": "EastEnders", "sub_title": "Episode 7012", "category": [ "Soap" ], "episode": { "show_id": "sh_e29nzc1x", "episode_id": "ep_610mmeyh", "season": 41, "number": 157, "name": "Episode 7012", "orig_air": "2026-10-07", "matched_by": "airtime", "source": "tvmaze" }, "flags": { "new": true, "live": false, "repeat": false } }, { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:30:00Z", "stop": "2026-10-07T20:00:00Z", "title": "The One Show", "category": [ "Magazine" ], "flags": { "new": true, "live": true, "repeat": false } } ], "meta": { "count": 38, "next": "c_8f21a0", "took_ms": 41 } } ``` ### Countries (6) Everything at once for one country: its channels, what is on now, prime time tonight and how full its data is. #### `GET /v1/countries` **List countries.** Every country we hold TV listings for, with its channel count, its guide feeds and how many programmes it has today. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/countries` Errors: `key_missing`, `limit_reached` ```json { "data": [ { "code": "GB", "name": "United Kingdom", "channels": 612, "feeds": 9, "listings_today": 18400 }, { "code": "TH", "name": "Thailand", "channels": 240, "feeds": 5, "listings_today": 6100 } ], "meta": { "count": 2, "next": null, "took_ms": 41 } } ``` #### `GET /v1/countries/{cc}` **Get a country.** One country's TV guide at a glance: channels, guide feeds, when its data last changed and how full each field is today. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/countries/{cc}` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `cc` | path | string | yes | Country code, ISO 3166-1 alpha-2. | `GB` | Errors: `key_missing`, `not_found`, `id_merged`, `limit_reached` ```json { "data": { "code": "GB", "name": "United Kingdom", "channels": 612, "feeds": 9, "updated": "2026-10-07T10:31:02Z", "fill": { "descr": 92.1, "category": 88.4, "episode_num": 41 } }, "meta": { "took_ms": 23 } } ``` #### `GET /v1/countries/{cc}/channels` **A country's channels.** Every TV channel in one country, ordered the way its own guides list them, with ids, names, logos and categories. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/countries/{cc}/channels` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `cc` | path | string | yes | Country code, ISO 3166-1 alpha-2. | `GB` | | `limit` | query | integer | no | Page size, 1 to 500. Defaults to 100. | `100` | | `cursor` | query | string | no | The cursor from the previous answer's `meta.next`. See [Paging and fields](https://tvguideapi.com/documentation/paging). | | Errors: `key_missing`, `not_found`, `id_merged`, `limit_reached` ```json { "data": [ { "id": "ch_jw83a3xg", "name": "BBC One", "country": "GB", "languages": [ "eng" ], "categories": [ "general" ], "owner": "BBC", "launched": 1936, "website": "https://www.bbc.co.uk/bbcone", "feeds": 3 } ], "meta": { "count": 612, "next": "c_8f21a0", "took_ms": 41 } } ``` #### `GET /v1/countries/{cc}/now` **Now in a country.** What is on now on every TV channel in a country, with what comes next, in one call. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/countries/{cc}/now` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `cc` | path | string | yes | Country code, ISO 3166-1 alpha-2. | `GB` | | `category` | query | string | no | Only this kind of channel. | `sports` | Errors: `key_missing`, `not_found`, `id_merged`, `limit_reached` ```json { "data": [ { "channel": "ch_jw83a3xg", "now": { "title": "EastEnders", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z" }, "next": { "title": "The One Show", "start": "2026-10-07T19:30:00Z" } }, { "channel": "ch_7qk3m2xa", "now": { "title": "Emmerdale", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z" }, "next": { "title": "Coronation Street", "start": "2026-10-07T19:30:00Z" } } ], "meta": { "count": 120, "next": "c_8f21a0", "took_ms": 41 } } ``` #### `GET /v1/countries/{cc}/tonight` **Tonight in a country.** Prime time tonight on every TV channel in a country, from the local hour you choose, in one grid. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/countries/{cc}/tonight` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `cc` | path | string | yes | Country code, ISO 3166-1 alpha-2. | `GB` | | `from_hour` | query | integer | no | Local hour to start from. Defaults to 19. | `19` | Errors: `key_missing`, `not_found`, `id_merged`, `limit_reached` ```json { "data": [ { "channel": "ch_jw83a3xg", "now": { "title": "EastEnders", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z" }, "next": { "title": "The One Show", "start": "2026-10-07T19:30:00Z" } }, { "channel": "ch_7qk3m2xa", "now": { "title": "Emmerdale", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z" }, "next": { "title": "Coronation Street", "start": "2026-10-07T19:30:00Z" } } ], "meta": { "count": 120, "next": "c_8f21a0", "took_ms": 41 } } ``` #### `GET /v1/countries/{cc}/coverage` **Country 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. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/countries/{cc}/coverage` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `cc` | path | string | yes | Country code, ISO 3166-1 alpha-2. | `GB` | | `date` | query | date | no | The day, `YYYY-MM-DD`. Defaults to today. | `2026-10-07` | Errors: `key_missing`, `not_found`, `id_merged`, `limit_reached` ```json { "data": { "country": "GB", "date": "2026-10-07", "slots": 18400, "fill": { "title": 100, "descr": 92.1, "category": 88.4, "episode_num": 41, "sub_title": 38.2, "icon": 52.7 }, "with_join": { "episode_num": 55.3, "sub_title": 47.9 } }, "meta": { "took_ms": 23 } } ``` ### Guide (8) Slots across many channels: grids, now and next, search, premieres, live slots and XMLTV files. #### `GET /v1/guide` **TV guide grid.** A TV guide grid for up to 50 channels over a window you choose, every slot with its times in UTC, ready to draw. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/guide` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `channels` | query | list | yes | Channel ids, comma separated, up to 50. | `ch_jw83a3xg,ch_7qk3m2xa` | | `from` | query | datetime | yes | Window start, UTC. | `2026-10-01T00:00:00Z` | | `to` | query | datetime | yes | Window end, UTC; at most 31 days after `from`. | `2026-10-02T00:00:00Z` | | `fields` | query | list | no | Only these fields, comma separated. | `start,title,episode` | Errors: `bad_parameter`, `key_missing`, `limit_reached` ```json { "data": [ { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z", "title": "EastEnders", "sub_title": "Episode 7012", "category": [ "Soap" ], "episode": { "show_id": "sh_e29nzc1x", "episode_id": "ep_610mmeyh", "season": 41, "number": 157, "name": "Episode 7012", "orig_air": "2026-10-07", "matched_by": "airtime", "source": "tvmaze" }, "flags": { "new": true, "live": false, "repeat": false } }, { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:30:00Z", "stop": "2026-10-07T20:00:00Z", "title": "The One Show", "category": [ "Magazine" ], "flags": { "new": true, "live": true, "repeat": false } } ], "meta": { "count": 38, "next": "c_8f21a0", "took_ms": 41 } } ``` #### `GET /v1/now` **Now on.** What is on now on the TV channels you name, or across a whole country, with what comes next on each. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/now` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `channels` | query | list | no | Channel ids, comma separated, up to 50. | `ch_jw83a3xg,ch_7qk3m2xa` | | `country` | query | string | no | Or a country code instead of channels. | `GB` | Errors: `key_missing`, `limit_reached` ```json { "data": [ { "channel": "ch_jw83a3xg", "now": { "title": "EastEnders", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z" }, "next": { "title": "The One Show", "start": "2026-10-07T19:30:00Z" } }, { "channel": "ch_7qk3m2xa", "now": { "title": "Emmerdale", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z" }, "next": { "title": "Coronation Street", "start": "2026-10-07T19:30:00Z" } } ], "meta": { "count": 120, "next": "c_8f21a0", "took_ms": 41 } } ``` #### `GET /v1/next` **Next on.** The next programme on each of the TV channels you name, or across a whole country. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/next` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `channels` | query | list | no | Channel ids, comma separated, up to 50. | `ch_jw83a3xg,ch_7qk3m2xa` | | `country` | query | string | no | Or a country code instead of channels. | `GB` | Errors: `key_missing`, `limit_reached` ```json { "data": [ { "channel": "ch_jw83a3xg", "now": { "title": "EastEnders", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z" }, "next": { "title": "The One Show", "start": "2026-10-07T19:30:00Z" } }, { "channel": "ch_7qk3m2xa", "now": { "title": "Emmerdale", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z" }, "next": { "title": "Coronation Street", "start": "2026-10-07T19:30:00Z" } } ], "meta": { "count": 120, "next": "c_8f21a0", "took_ms": 41 } } ``` #### `GET /v1/listings/{id}` **Get a listing.** One TV listing slot in full: times, title, sub-title, description, category, rating, flags, its episode and the feeds it came from. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/listings/{id}` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The listing id. | `ls_shr78fcp` | Errors: `key_missing`, `not_found`, `id_merged`, `limit_reached` ```json { "data": { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z", "title": "EastEnders", "sub_title": "Episode 7012", "descr": "Sharon makes a decision about the Vic.", "category": [ "Soap" ], "episode": { "show_id": "sh_e29nzc1x", "episode_id": "ep_610mmeyh", "season": 41, "number": 157, "name": "Episode 7012", "orig_air": "2026-10-07", "matched_by": "airtime", "source": "tvmaze" }, "flags": { "new": true, "live": false, "repeat": false } }, "meta": { "took_ms": 23 } } ``` #### `GET /v1/listings/search` **Search listings.** Find upcoming TV programmes by words in their title, sub-title or description, in the countries you choose. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/listings/search` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `q` | query | string | yes | Words to find. | `eastenders` | | `country` | query | list | no | Country codes, ISO 3166-1 alpha-2, comma separated. | `GB` | | `from` | query | datetime | no | From when, UTC. Defaults to now. | `2026-10-07T00:00:00Z` | | `limit` | query | integer | no | Page size, 1 to 500. Defaults to 100. | `100` | | `cursor` | query | string | no | The cursor from the previous answer's `meta.next`. See [Paging and fields](https://tvguideapi.com/documentation/paging). | | Errors: `bad_parameter`, `key_missing`, `limit_reached` ```json { "data": [ { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z", "title": "EastEnders", "sub_title": "Episode 7012", "category": [ "Soap" ], "episode": { "show_id": "sh_e29nzc1x", "episode_id": "ep_610mmeyh", "season": 41, "number": 157, "name": "Episode 7012", "orig_air": "2026-10-07", "matched_by": "airtime", "source": "tvmaze" }, "flags": { "new": true, "live": false, "repeat": false } }, { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:30:00Z", "stop": "2026-10-07T20:00:00Z", "title": "The One Show", "category": [ "Magazine" ], "flags": { "new": true, "live": true, "repeat": false } } ], "meta": { "count": 38, "next": "c_8f21a0", "took_ms": 41 } } ``` #### `GET /v1/premieres` **Premieres.** New episodes and first showings on a day, across the TV channels of the countries you choose. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/premieres` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `country` | query | list | yes | Country codes, ISO 3166-1 alpha-2, comma separated. | `GB` | | `date` | query | date | no | The day, `YYYY-MM-DD`. Defaults to today. | `2026-10-07` | Errors: `bad_parameter`, `key_missing`, `limit_reached` ```json { "data": [ { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z", "title": "EastEnders", "sub_title": "Episode 7012", "category": [ "Soap" ], "episode": { "show_id": "sh_e29nzc1x", "episode_id": "ep_610mmeyh", "season": 41, "number": 157, "name": "Episode 7012", "orig_air": "2026-10-07", "matched_by": "airtime", "source": "tvmaze" }, "flags": { "new": true, "live": false, "repeat": false } }, { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:30:00Z", "stop": "2026-10-07T20:00:00Z", "title": "The One Show", "category": [ "Magazine" ], "flags": { "new": true, "live": true, "repeat": false } } ], "meta": { "count": 38, "next": "c_8f21a0", "took_ms": 41 } } ``` #### `GET /v1/live` **Live slots.** TV slots marked live, on now and later today, in the countries you choose. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/live` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `country` | query | list | no | Country codes, ISO 3166-1 alpha-2, comma separated. | `GB` | Errors: `key_missing`, `limit_reached` ```json { "data": [ { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z", "title": "EastEnders", "sub_title": "Episode 7012", "category": [ "Soap" ], "episode": { "show_id": "sh_e29nzc1x", "episode_id": "ep_610mmeyh", "season": 41, "number": 157, "name": "Episode 7012", "orig_air": "2026-10-07", "matched_by": "airtime", "source": "tvmaze" }, "flags": { "new": true, "live": false, "repeat": false } }, { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:30:00Z", "stop": "2026-10-07T20:00:00Z", "title": "The One Show", "category": [ "Magazine" ], "flags": { "new": true, "live": true, "repeat": false } } ], "meta": { "count": 38, "next": "c_8f21a0", "took_ms": 41 } } ``` #### `GET /v1/xmltv`, paid plans **XMLTV export.** A country or a set of channels as a standard XMLTV file, up to 14 days ahead, for media centres and IPTV players. Plans: paid plans. Address: `https://api.tvguideapi.com/v1/xmltv` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `country` | query | string | no | A country code. | `GB` | | `channels` | query | list | no | Channel ids, comma separated, up to 50. | `ch_jw83a3xg,ch_7qk3m2xa` | | `days` | query | integer | no | Days ahead, 1 to 14. Defaults to 7. | `7` | Errors: `key_missing`, `plan_required`, `limit_reached` ```xml EastEnders ``` ### Shows and episodes (10) Series and episodes with their ids, and every place and time they air, first run and repeats. #### `GET /v1/shows/search` **Find a show.** Find a TV show by any of its titles and get its id, network, status and premiere date. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/shows/search` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `q` | query | string | yes | A title. | `eastenders` | | `limit` | query | integer | no | Page size, 1 to 500. Defaults to 100. | `100` | Errors: `bad_parameter`, `key_missing`, `limit_reached` ```json { "data": [ { "id": "sh_e29nzc1x", "name": "EastEnders", "network": "BBC One", "country": "GB", "status": "Running", "premiered": "1985-02-19" } ], "meta": { "count": 1, "next": null, "took_ms": 41 } } ``` #### `GET /v1/shows/{id}` **Get a show.** One TV show: its titles, network, genres, status, premiere and its ids at TVmaze, TheTVDB, IMDb and Wikidata. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/shows/{id}` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The show id. Ids come from [Find a show](https://tvguideapi.com/documentation/shows-search). | `sh_e29nzc1x` | Errors: `key_missing`, `not_found`, `id_merged`, `limit_reached` ```json { "data": { "id": "sh_e29nzc1x", "name": "EastEnders", "network": { "name": "BBC One" }, "status": "Running", "premiered": "1985-02-19", "genres": [ "Drama" ], "source": "tvmaze" }, "meta": { "took_ms": 23 } } ``` #### `GET /v1/shows/{id}/episodes` **A show's episodes.** Every episode of a TV show, season by season, with numbers, names and original air dates. Plans: free key and every plan. Data from 1908. Address: `https://api.tvguideapi.com/v1/shows/{id}/episodes` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The show id. Ids come from [Find a show](https://tvguideapi.com/documentation/shows-search). | `sh_e29nzc1x` | | `season` | query | integer | no | One season only. | `41` | Errors: `key_missing`, `not_found`, `id_merged`, `limit_reached` ```json { "data": [ { "show_id": "sh_e29nzc1x", "episode_id": "ep_610mmeyh", "season": 41, "number": 157, "name": "Episode 7012", "orig_air": "2026-10-07", "matched_by": "airtime", "source": "tvmaze" } ], "meta": { "count": 7012, "next": "c_8f21a0", "took_ms": 41 } } ``` #### `GET /v1/shows/{id}/cast` **A show's 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. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/shows/{id}/cast` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The show id. Ids come from [Find a show](https://tvguideapi.com/documentation/shows-search). | `sh_e29nzc1x` | Errors: `key_missing`, `not_found`, `id_merged`, `limit_reached` Cast comes from TVmaze (CC BY-SA). Listing slots joined to the show carry its id, so the cast of what is on now is one call away. ```json { "data": [ { "person": { "id": 1, "name": "Example Actor", "country": "GB" }, "character": "Lead role", "self": false, "voice": false } ], "meta": { "count": 1, "next": null, "took_ms": 41 } } ``` #### `GET /v1/shows/{id}/airings` **Where a show airs.** When and where a TV show airs next, in every country or the ones you choose, first runs and repeats. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/shows/{id}/airings` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The show id. Ids come from [Find a show](https://tvguideapi.com/documentation/shows-search). | `sh_e29nzc1x` | | `country` | query | list | no | Country codes, ISO 3166-1 alpha-2, comma separated. | `GB` | | `days` | query | integer | no | Days ahead, 1 to 14. | `7` | Errors: `key_missing`, `not_found`, `id_merged`, `limit_reached` ```json { "data": [ { "channel": "ch_jw83a3xg", "country": "GB", "start": "2026-10-08T19:00:00Z", "episode_id": "ep_610mmeyh", "kind": "first-run" }, { "channel": "ch_e5n9wc2j", "country": "US", "start": "2026-10-09T23:00:00Z", "episode_id": "ep_610mmeyh", "kind": "repeat" } ], "meta": { "count": 2, "next": null, "took_ms": 41 } } ``` #### `GET /v1/shows/{id}/history`, paid plans **A show's past airings.** Every past airing of a TV show that the archive holds, over a window you choose. Plans: paid plans. Data from 2010. Address: `https://api.tvguideapi.com/v1/shows/{id}/history` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The show id. Ids come from [Find a show](https://tvguideapi.com/documentation/shows-search). | `sh_e29nzc1x` | | `from` | query | datetime | yes | Window start, UTC. | `2026-10-01T00:00:00Z` | | `to` | query | datetime | yes | Window end, UTC; at most 31 days after `from`. | `2026-10-02T00:00:00Z` | | `cursor` | query | string | no | The cursor from the previous answer's `meta.next`. See [Paging and fields](https://tvguideapi.com/documentation/paging). | | Errors: `bad_parameter`, `key_missing`, `plan_required`, `not_found`, `id_merged`, `limit_reached` ```json { "data": [ { "channel": "ch_jw83a3xg", "country": "GB", "start": "2026-10-08T19:00:00Z", "episode_id": "ep_610mmeyh", "kind": "first-run" }, { "channel": "ch_e5n9wc2j", "country": "US", "start": "2026-10-09T23:00:00Z", "episode_id": "ep_610mmeyh", "kind": "repeat" } ], "meta": { "count": 2, "next": null, "took_ms": 41 } } ``` #### `GET /v1/episodes/{id}` **Get an episode.** One TV episode: its show, season, number, name, runtime and original air date. Plans: free key and every plan. Data from 1908. Address: `https://api.tvguideapi.com/v1/episodes/{id}` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The episode id. | `ep_610mmeyh` | Errors: `key_missing`, `not_found`, `id_merged`, `limit_reached` ```json { "data": { "show_id": "sh_e29nzc1x", "episode_id": "ep_610mmeyh", "season": 41, "number": 157, "name": "Episode 7012", "orig_air": "2026-10-07", "matched_by": "airtime", "source": "tvmaze" }, "meta": { "took_ms": 23 } } ``` #### `GET /v1/episodes/{id}/airings`, paid plans **Where an episode aired.** Every showing of one TV episode we hold, the first run and every repeat, on every channel. Plans: paid plans. Data from 2010. Address: `https://api.tvguideapi.com/v1/episodes/{id}/airings` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The episode id. | `ep_610mmeyh` | | `cursor` | query | string | no | The cursor from the previous answer's `meta.next`. See [Paging and fields](https://tvguideapi.com/documentation/paging). | | Errors: `key_missing`, `plan_required`, `not_found`, `id_merged`, `limit_reached` ```json { "data": [ { "channel": "ch_jw83a3xg", "country": "GB", "start": "2026-10-08T19:00:00Z", "episode_id": "ep_610mmeyh", "kind": "first-run" }, { "channel": "ch_e5n9wc2j", "country": "US", "start": "2026-10-09T23:00:00Z", "episode_id": "ep_610mmeyh", "kind": "repeat" } ], "meta": { "count": 2, "next": null, "took_ms": 41 } } ``` #### `GET /v1/networks` **List networks.** TV networks and streaming services, by country, with their ids. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/networks` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `country` | query | string | no | A country code. | `GB` | | `limit` | query | integer | no | Page size, 1 to 500. Defaults to 100. | `100` | | `cursor` | query | string | no | The cursor from the previous answer's `meta.next`. See [Paging and fields](https://tvguideapi.com/documentation/paging). | | Errors: `key_missing`, `limit_reached` ```json { "data": [ { "id": "nw_2szm9pm5", "name": "BBC One", "country": "GB", "kind": "network" } ], "meta": { "count": 400, "next": "c_8f21a0", "took_ms": 41 } } ``` #### `GET /v1/networks/{id}/shows` **A network's shows.** The TV shows of one network or streaming service, running or ended. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/networks/{id}/shows` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The network id. | `nw_2szm9pm5` | | `status` | query | string | no | `running` or `ended`. | `running` | | `limit` | query | integer | no | Page size, 1 to 500. Defaults to 100. | `100` | | `cursor` | query | string | no | The cursor from the previous answer's `meta.next`. See [Paging and fields](https://tvguideapi.com/documentation/paging). | | Errors: `key_missing`, `not_found`, `id_merged`, `limit_reached` ```json { "data": [ { "id": "sh_e29nzc1x", "name": "EastEnders", "status": "Running" } ], "meta": { "count": 120, "next": "c_8f21a0", "took_ms": 41 } } ``` ### Sport and events (11) Sports events found in the listings of every country, joined to fixtures, with each channel showing them and whether it is live or a repeat. #### `GET /v1/sports` **List sports.** The sports with events on TV this week, and how many events each has. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/sports` Errors: `key_missing`, `limit_reached` ```json { "data": [ { "sport": "football", "events_week": 412 }, { "sport": "cricket", "events_week": 38 } ], "meta": { "count": 2, "next": null, "took_ms": 41 } } ``` #### `GET /v1/leagues` **List leagues.** Sports competitions with events on TV, by sport and country, with their ids. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/leagues` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `sport` | query | string | no | A sport: football, cricket, basketball, rugby, tennis... | `football` | | `country` | query | string | no | A country code. | `GB` | Errors: `key_missing`, `limit_reached` ```json { "data": [ { "id": "chinese-professional-baseball-league", "name": "Premier League", "sport": "football", "country": "GB" } ], "meta": { "count": 1, "next": null, "took_ms": 41 } } ``` #### `GET /v1/leagues/{id}/events`, paid plans **A league's events.** A competition's fixtures over a window, each with every channel showing it and whether it is live. Plans: paid plans. Address: `https://api.tvguideapi.com/v1/leagues/{id}/events` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The league id. | `chinese-professional-baseball-league` | | `from` | query | datetime | yes | Window start, UTC. | `2026-10-01T00:00:00Z` | | `to` | query | datetime | yes | Window end, UTC; at most 31 days after `from`. | `2026-10-02T00:00:00Z` | Errors: `bad_parameter`, `key_missing`, `plan_required`, `not_found`, `id_merged`, `limit_reached` ```json { "data": [ { "id": "ev_d2bh99ey", "sport": "football", "league": { "id": "chinese-professional-baseball-league", "name": "Premier League" }, "home": "Arsenal", "away": "Chelsea", "start": "2026-10-18T16:30:00Z", "venue": { "name": "Emirates Stadium", "country": "GB" }, "round": "Matchweek 8", "live_on": 2 } ], "meta": { "count": 10, "next": "c_8f21a0", "took_ms": 41 } } ``` #### `GET /v1/events`, paid plans **Events.** Sports events on TV by sport, league and day, in every country or only those on air where you are. Plans: paid plans. Address: `https://api.tvguideapi.com/v1/events` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `sport` | query | string | no | A sport: football, cricket, basketball, rugby, tennis... | `football` | | `league` | query | string | no | A league id. | `chinese-professional-baseball-league` | | `date` | query | date | no | The day, `YYYY-MM-DD`. Defaults to today. | `2026-10-07` | | `country` | query | string | no | Only events on air in this country. | `TH` | Errors: `key_missing`, `plan_required`, `limit_reached` ```json { "data": [ { "id": "ev_d2bh99ey", "sport": "football", "league": { "id": "chinese-professional-baseball-league", "name": "Premier League" }, "home": "Arsenal", "away": "Chelsea", "start": "2026-10-18T16:30:00Z", "venue": { "name": "Emirates Stadium", "country": "GB" }, "round": "Matchweek 8", "live_on": 3 } ], "meta": { "count": 12, "next": "c_8f21a0", "took_ms": 41 } } ``` #### `GET /v1/events/{id}`, paid plans **Get an event.** One sports event: its teams, league, round, venue and start time, with the channels showing it. Plans: paid plans. Address: `https://api.tvguideapi.com/v1/events/{id}` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The event id. Ids come from [Events](https://tvguideapi.com/documentation/events). | `ev_d2bh99ey` | Errors: `key_missing`, `plan_required`, `not_found`, `id_merged`, `limit_reached` ```json { "data": { "id": "ev_d2bh99ey", "sport": "football", "league": { "id": "chinese-professional-baseball-league", "name": "Premier League" }, "home": "Arsenal", "away": "Chelsea", "start": "2026-10-18T16:30:00Z", "venue": { "name": "Emirates Stadium", "country": "GB" }, "round": "Matchweek 8", "broadcasts": [ { "country": "GB", "channel": "ch_3vd81kpz", "start": "2026-10-18T16:30:00Z", "kind": "live" }, { "country": "TH", "channel": "ch_b62tq0we", "start": "2026-10-18T16:30:00Z", "kind": "live" } ] }, "meta": { "took_ms": 23 } } ``` #### `GET /v1/events/{id}/broadcasts`, paid plans **Where to watch an event.** Every TV channel showing a sports event, country by country, and whether each showing is live, delayed or a repeat. Plans: paid plans. Address: `https://api.tvguideapi.com/v1/events/{id}/broadcasts` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The event id. Ids come from [Events](https://tvguideapi.com/documentation/events). | `ev_d2bh99ey` | | `country` | query | list | no | Country codes, ISO 3166-1 alpha-2, comma separated. | `GB` | Errors: `key_missing`, `plan_required`, `not_found`, `id_merged`, `limit_reached` `kind` is `live`, `delayed` or `repeat`. A showing the guide marks as a repeat, or one that starts after the match has ended, is never counted as live. ```json { "data": [ { "country": "GB", "channel": "ch_3vd81kpz", "start": "2026-10-18T16:30:00Z", "kind": "live" }, { "country": "TH", "channel": "ch_b62tq0we", "start": "2026-10-18T16:30:00Z", "kind": "live" }, { "country": "GB", "channel": "ch_m0x4hs7r", "start": "2026-10-18T22:00:00Z", "kind": "repeat" } ], "meta": { "count": 3, "next": null, "took_ms": 41 } } ``` #### `GET /v1/events/live`, paid plans **Live events now.** Sports events live on TV right now, in a country or everywhere, with the channels showing them. Plans: paid plans. Address: `https://api.tvguideapi.com/v1/events/live` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `country` | query | string | no | A country code. | `GB` | | `sport` | query | string | no | A sport: football, cricket, basketball, rugby, tennis... | `football` | Errors: `key_missing`, `plan_required`, `limit_reached` ```json { "data": [ { "id": "ev_d2bh99ey", "sport": "football", "league": { "id": "chinese-professional-baseball-league", "name": "Premier League" }, "home": "Arsenal", "away": "Chelsea", "start": "2026-10-18T16:30:00Z", "venue": { "name": "Emirates Stadium", "country": "GB" }, "round": "Matchweek 8", "live_on": 3 } ], "meta": { "count": 1, "next": null, "took_ms": 41 } } ``` #### `GET /v1/events/upcoming`, paid plans **Upcoming events.** The next sports events on TV with their channels, soonest first, over the hours ahead you choose. Plans: paid plans. Address: `https://api.tvguideapi.com/v1/events/upcoming` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `country` | query | string | no | A country code. | `TH` | | `hours` | query | integer | no | Hours ahead, 1 to 168. | `24` | Errors: `key_missing`, `plan_required`, `limit_reached` ```json { "data": [ { "id": "ev_d2bh99ey", "sport": "football", "league": { "id": "chinese-professional-baseball-league", "name": "Premier League" }, "home": "Arsenal", "away": "Chelsea", "start": "2026-10-18T16:30:00Z", "venue": { "name": "Emirates Stadium", "country": "GB" }, "round": "Matchweek 8", "live_on": 3 } ], "meta": { "count": 40, "next": "c_8f21a0", "took_ms": 41 } } ``` #### `GET /v1/events/{id}/replays`, paid plans **An event's replays.** Later showings of a sports event: repeats, highlights and delayed broadcasts, on every channel. Plans: paid plans. Address: `https://api.tvguideapi.com/v1/events/{id}/replays` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The event id. Ids come from [Events](https://tvguideapi.com/documentation/events). | `ev_d2bh99ey` | Errors: `key_missing`, `plan_required`, `not_found`, `id_merged`, `limit_reached` ```json { "data": [ { "country": "GB", "channel": "ch_m0x4hs7r", "start": "2026-10-18T22:00:00Z", "kind": "repeat" } ], "meta": { "count": 1, "next": null, "took_ms": 41 } } ``` #### `GET /v1/teams/{id}/events`, paid plans **Where a team is on.** Where a team's matches are shown on TV, in every country or the ones you choose. Plans: paid plans. Address: `https://api.tvguideapi.com/v1/teams/{id}/events` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | yes | The team id. | `india` | | `country` | query | list | no | Country codes, ISO 3166-1 alpha-2, comma separated. | `GB` | Errors: `key_missing`, `plan_required`, `not_found`, `id_merged`, `limit_reached` ```json { "data": [ { "id": "ev_d2bh99ey", "sport": "football", "league": { "id": "chinese-professional-baseball-league", "name": "Premier League" }, "home": "Arsenal", "away": "Chelsea", "start": "2026-10-18T16:30:00Z", "venue": { "name": "Emirates Stadium", "country": "GB" }, "round": "Matchweek 8", "broadcasts": [ { "country": "GB", "channel": "ch_3vd81kpz", "start": "2026-10-18T16:30:00Z", "kind": "live" }, { "country": "TH", "channel": "ch_b62tq0we", "start": "2026-10-18T16:30:00Z", "kind": "live" }, { "country": "GB", "channel": "ch_m0x4hs7r", "start": "2026-10-18T22:00:00Z", "kind": "repeat" } ] } ], "meta": { "count": 1, "next": null, "took_ms": 41 } } ``` #### `GET /v1/rights`, paid plans **Broadcast rights history.** Who held the TV rights to a competition, by country and season, from the yearly versions of public broadcaster lists. Plans: paid plans. Address: `https://api.tvguideapi.com/v1/rights` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `competition` | query | string | yes | The competition. | `Premier League` | | `country` | query | string | no | A country code. | `TH` | | `season` | query | string | no | A season. | `2019-20` | Errors: `bad_parameter`, `key_missing`, `plan_required`, `limit_reached` Before the listings began, this is the only record we hold of who showed what. ```json { "data": [ { "competition": "Premier League", "country": "TH", "season": "2019-20", "holders": [ "TrueVisions" ], "source": "wikipedia" } ], "meta": { "count": 1, "next": null, "took_ms": 41 } } ``` ### Venue plans (2) For bars and venues: what to put on the screens tonight and in the week ahead, live first. #### `GET /v1/venue/tonight`, paid plans **Tonight's screens.** Tonight's sport for a bar or venue: live events first, one row per event with every channel you receive that has it. Plans: paid plans. Address: `https://api.tvguideapi.com/v1/venue/tonight` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `country` | query | string | yes | The venue's country. | `GB` | | `sports` | query | list | no | Sports to show. | `football,rugby` | | `channels` | query | list | no | Channel ids, comma separated, up to 50. | `ch_jw83a3xg,ch_7qk3m2xa` | Errors: `bad_parameter`, `key_missing`, `plan_required`, `limit_reached` `channels` limits the answer to what your venue receives. ```json { "data": [ { "start": "2026-10-18T16:30:00Z", "local": "17:30", "event": "Arsenal v Chelsea", "league": "Premier League", "live": true, "channels": [ "ch_3vd81kpz" ] } ], "meta": { "count": 1, "next": null, "took_ms": 41 } } ``` #### `GET /v1/venue/week`, paid plans **The week ahead.** The week ahead for a bar or venue, day by day, live events first, on the channels you receive. Plans: paid plans. Address: `https://api.tvguideapi.com/v1/venue/week` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `country` | query | string | yes | The venue's country. | `GB` | | `sports` | query | list | no | Sports to show. | `football,rugby` | | `channels` | query | list | no | Channel ids, comma separated, up to 50. | `ch_jw83a3xg,ch_7qk3m2xa` | Errors: `bad_parameter`, `key_missing`, `plan_required`, `limit_reached` ```json { "data": [ { "day": "2026-10-18", "events": 6, "live": 5 } ], "meta": { "count": 1, "next": null, "took_ms": 41 } } ``` ### Account and meta (5) Your plan, keys and usage, the freshness of every source, field fill by country, and the sources with their licences. #### `GET /v1/me` **Your account.** Your plan, your keys by prefix and label, and your daily limit. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/me` Errors: `key_missing`, `limit_reached` ```json { "data": { "plan": "free", "keys": [ { "prefix": "tvg_live_7Qk2", "label": "laptop", "last_used": "2026-10-07T10:30:11Z" } ], "limits": { "calls_day": 50 } }, "meta": { "took_ms": 23 } } ``` #### `GET /v1/usage` **Your usage.** Your calls per day and per endpoint over the days you choose. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/usage` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `days` | query | integer | no | Days back, 1 to 90. | `30` | Errors: `key_missing`, `limit_reached` ```json { "data": [ { "date": "2026-10-07", "calls": 31 }, { "date": "2026-10-06", "calls": 50 } ], "meta": { "count": 2, "next": null, "took_ms": 41 } } ``` #### `GET /v1/status` **Status.** How fresh every source is right now, and whether the API is answering normally. No key needed. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/status` Errors: `busy` ```json { "data": { "ok": true, "updated": "2026-10-07T10:31:02Z", "live_lag_s": 1 }, "meta": { "took_ms": 23 } } ``` #### `GET /v1/fields` **Field fill.** How full each listing field is today, country by country. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/fields` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `country` | query | list | no | Country codes, ISO 3166-1 alpha-2, comma separated. | `GB` | Errors: `key_missing`, `limit_reached` ```json { "data": { "country": "GB", "date": "2026-10-07", "slots": 18400, "fill": { "title": 100, "descr": 92.1, "category": 88.4, "episode_num": 41, "sub_title": 38.2, "icon": 52.7 }, "with_join": { "episode_num": 55.3, "sub_title": 47.9 } }, "meta": { "took_ms": 23 } } ``` #### `GET /v1/sources` **Sources and licences.** Every source behind the data, the fields it supplies, its licence and the credit it asks for. Plans: free key and every plan. Address: `https://api.tvguideapi.com/v1/sources` Errors: `key_missing`, `limit_reached` ```json { "data": [ { "name": "TVmaze", "fields": [ "episode.*", "show.*" ], "licence": "CC BY-SA", "credit": "Data from TVmaze.com" }, { "name": "Wikidata", "fields": [ "channel.launched" ], "licence": "CC0" } ], "meta": { "count": 2, "next": null, "took_ms": 41 } } ``` ### Agents (2) The MCP server and the agent skill index. #### `POST /mcp` **MCP endpoint.** The Model Context Protocol server: the same data as tools for Claude, ChatGPT and other assistants. Plans: free key and every plan. Address: `https://api.tvguideapi.com/mcp` | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `Authorization` | header | string | yes | Your key as a bearer token. | `Bearer tvg_live_...` | Errors: `key_missing`, `limit_reached` Streamable HTTP. The same key and limits as the API; one tool call counts as one call. See [MCP server](https://tvguideapi.com/documentation/mcp). ```json { "jsonrpc": "2.0", "id": 1, "result": { "tools": [ { "name": "whats_on_now" }, { "name": "channel_day" }, { "name": "where_to_watch" }, { "name": "next_airing" } ] } } ``` #### `GET /.well-known/agent-skills/index.json` **Agent skill index.** The index agents read to find the tvguideapi.com skill. No key needed. Plans: free key and every plan. Address: `https://tvguideapi.com/.well-known/agent-skills/index.json` Errors: `busy` ```json { "skills": [ { "name": "tvguideapi", "url": "https://tvguideapi.com/.well-known/agent-skills/tvguideapi/SKILL.md" } ] } ``` ## Guides ### Quick start *A key and your first call in a minute.* https://tvguideapi.com/documentation/quick-start ### 1. Get a key Sign in at [your account](https://tvguideapi.com/account). Your key starts with `tvg_live_` and is shown once: we store it hashed and keep only its first characters, so your account can show which key made which call. ### 2. Ask for a channel's day ```bash curl -H "Authorization: Bearer $TVG_KEY" \ "https://api.tvguideapi.com/v1/channels/ch_jw83a3xg/schedule?date=2026-10-07" ``` ### 3. Read the answer Every list comes back as `data` and `meta`. Each slot has `start` and `stop` in UTC, the title as the channel sent it and, where we matched it, an `episode` object with the series, season, number and original air date. ```json { "data": [ { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:00:00Z", "stop": "2026-10-07T19:30:00Z", "title": "EastEnders", "sub_title": "Episode 7012", "category": [ "Soap" ], "episode": { "show_id": "sh_e29nzc1x", "episode_id": "ep_610mmeyh", "season": 41, "number": 157, "name": "Episode 7012", "orig_air": "2026-10-07", "matched_by": "airtime", "source": "tvmaze" }, "flags": { "new": true, "live": false, "repeat": false } }, { "id": "ls_shr78fcp", "channel": "ch_jw83a3xg", "start": "2026-10-07T19:30:00Z", "stop": "2026-10-07T20:00:00Z", "title": "The One Show", "category": [ "Magazine" ], "flags": { "new": true, "live": true, "repeat": false } } ], "meta": { "count": 38, "next": "c_8f21a0", "took_ms": 41 } } ``` Next: [the schedule endpoint in full](https://tvguideapi.com/documentation/channels-id-schedule), or [use it from Claude](https://tvguideapi.com/documentation/claude-and-agents). ### Authentication *Keys, bearer tokens and keeping them safe.* https://tvguideapi.com/documentation/authentication Every call carries your key as a bearer token: ```http Authorization: Bearer tvg_live_7Qk2... ``` Keys are made, named and revoked in your account. A key can be limited to a list of addresses, and revoking it takes effect on the next call. ### Keep it on the server Never put a key in a web page or an app people download. Call us from your server and pass on only what the page needs. ### No key needed [Status](https://tvguideapi.com/documentation/status) and [the agent skill index](https://tvguideapi.com/documentation/agent-skills-index) answer without a key. ### Free key *What the free key reads, and its daily limit.* https://tvguideapi.com/documentation/free-key The free key reads real listings for yesterday and today, for every country, with up to 500 calls a day. No card. It opens every endpoint marked **Free key** in the menu. History, events and XMLTV files need a paid plan: their pages say so, and a free key gets a clear `403 upgrade_required` answer instead of data. ### Times and days *UTC everywhere, and how a local day is cut.* https://tvguideapi.com/documentation/times-and-days Every time in every answer is UTC, written as ISO 8601 with a Z: `2026-10-07T19:00:00Z`. ### Asking for a local day Endpoints that take `date` also take `tz`, an IANA zone such as `Asia/Bangkok`. The day is then cut at local midnight, and the times in the answer stay UTC, so nothing you store needs converting twice. A slot that crosses midnight appears in both days. Use its id to keep one copy. ### Channel and show ids *One id per channel and show across every source.* https://tvguideapi.com/documentation/ids Every channel has one id across all our sources, taken from the open iptv-org registry where it has one, such as `ch_jw83a3xg`. A channel that sends its guide under different names in different feeds still has one id. Shows and episodes carry the TVmaze ids, so you can join them to anything else that uses those. When two channels or shows turn out to be one, the old id answers `410 id_merged` with the new one in `meta.moved_to`. ### Paging and fields *Cursors, limits and asking for fewer fields.* https://tvguideapi.com/documentation/paging Lists return up to `limit` items (default 100, at most 500). When there are more, `meta.next` holds a cursor: pass it as `cursor` for the next page, until it is null. A cursor fixes the result set, so pages never shift while you read them. Ask for fewer fields with `fields=start,title,episode`: smaller answers, faster. ### Use with Claude and agents *Connect the MCP server, the agent skill and the manual.* https://tvguideapi.com/documentation/claude-and-agents Three ways to hand the whole API to an assistant: - **MCP server** at `https://api.tvguideapi.com/mcp`: add it to Claude, ChatGPT or any MCP client and the tools answer from live data. See [MCP server](https://tvguideapi.com/documentation/mcp) and [MCP tools](https://tvguideapi.com/documentation/mcp-tools). - **Agent skill** at [/.well-known/agent-skills/tvguideapi/SKILL.md](https://tvguideapi.com/.well-known/agent-skills/tvguideapi/SKILL.md): teaches an agent our endpoints, ids and limits. Also at [/skill.md](https://tvguideapi.com/skill.md). - **The manual, one file** at [/documentation/manual.md](https://tvguideapi.com/documentation/manual.md): every endpoint, parameter, sample and guide to paste in one go. The short index is [/llms.txt](https://tvguideapi.com/llms.txt). ### Claude Add `https://api.tvguideapi.com/mcp` to Claude as a custom connector, with your key. Then ask, for example: *what football is on in Bangkok tonight, and on which channels?* ### MCP server *The Model Context Protocol endpoint and how to connect.* https://tvguideapi.com/documentation/mcp The MCP server speaks Streamable HTTP at `https://api.tvguideapi.com/mcp`. It takes the same key as the API and counts one tool call as one API call. ```json { "mcpServers": { "tvguideapi": { "url": "https://api.tvguideapi.com/mcp", "headers": { "Authorization": "Bearer tvg_live_..." } } } } ``` See [the tools](https://tvguideapi.com/documentation/mcp-tools) for what it answers. ### MCP tools *Every tool the MCP server offers, with its inputs.* https://tvguideapi.com/documentation/mcp-tools | Tool | Inputs | Answers with | | --- | --- | --- | | `whats_on_now` | country or channels | Now and next on each channel | | `channel_day` | channel, date, tz | A channel's day, slot by slot | | `find_channel` | name, country | Matching channels with their ids | | `where_to_watch` | team or event, country | Every channel showing it, live or repeat | | `next_airing` | show, country | When and where a show airs next | | `venue_tonight` | country, sports, channels | Tonight's screens, live first | | `coverage` | country | How full the data is for a country | ### Errors *Every error code, what it means and the fix.* https://tvguideapi.com/documentation/errors Every error has the same shape: ```json { "error": { "code": "plan_required", "message": "History needs a paid plan.", "doc_url": "https://tvguideapi.com/documentation/errors" } } ``` | HTTP | Code | When | The fix | | --- | --- | --- | --- | | 400 | `bad_parameter` | A parameter is missing or not in the form the endpoint page shows | The message names the parameter; check its row in the parameter table | | 401 | `key_missing` | No key, or not sent as a bearer token | Send `Authorization: Bearer tvg_live_...` | | 403 | `plan_required` | The endpoint or the date range needs a paid plan | The message names what opens it | | 404 | `not_found` | No channel, show, episode or event with that id | Find it first with a search endpoint | | 410 | `id_merged` | The id was merged into another | Use `meta.moved_to`; the old id keeps answering 410 for a year | | 429 | `limit_reached` | Today's calls are used up | Wait for `Retry-After`, or move to a paid plan | | 503 | `busy` | Try again shortly; nothing was counted | Retry with backoff | ### Limits and headers *Daily calls, the headers that count them, and caching.* https://tvguideapi.com/documentation/rate-limits Calls are counted per key per UTC day. Every answer says where you stand: | Header | Meaning | | --- | --- | | `X-Calls-Limit` | Calls your plan allows per day | | `X-Calls-Left` | Calls left today | | `X-Calls-Reset` | When the count resets, UTC | | `X-Data-Updated` | When the data in this answer last changed | | `X-Request-Id` | Quote it to support | | `ETag` | Send it back as `If-None-Match`; an unchanged answer is a 304 and is not counted | ### Sources and licences *Where the data comes from and the credit it asks for.* https://tvguideapi.com/documentation/data-sources | Fields | Source | Licence | What it asks of you | | --- | --- | --- | --- | | listings, start, stop, title, descr | Broadcasters' published guides and open XMLTV feeds, collected and corrected by us | Our licence to you | Nothing beyond your plan's terms | | episode.*, show.* | TVmaze | CC BY-SA | Credit TVmaze with a link; what you build from these fields is shared under the same licence | | channel.launched, channel.owner | Wikidata | CC0 | Nothing | | channel.id, channel.logo | iptv-org database | Public domain dedication | Nothing; logos stay their owners' marks | | event.*, broadcasts.* | Found in the listings by us, joined to fixtures | Our licence to you | Nothing beyond your plan's terms | [Sources and licences](https://tvguideapi.com/documentation/sources) returns this table for your code. ### Changelog *What changed, newest first.* https://tvguideapi.com/documentation/changelog | Date | Change | | --- | --- | | 2026-10-07 | Episodes are matched by episode number and by description as well as by air time and title | | 2026-10-06 | Whole feeds that ran on the wrong clock were moved to the right time, every row | ## Errors Every error is `{"error": {"code", "message", "doc_url"}}` with the HTTP status below. The full list with the fix for each: https://tvguideapi.com/documentation/errors | HTTP | Code | When | | --- | --- | --- | | 400 | `bad_parameter` | A parameter is missing or not in the form the endpoint page shows | | 401 | `key_missing` | No key, or not sent as a bearer token | | 403 | `plan_required` | The endpoint or the date range needs a paid plan | | 404 | `not_found` | No channel, show, episode or event with that id | | 410 | `id_merged` | The id was merged into another | | 429 | `limit_reached` | Today's calls are used up | | 503 | `busy` | Try again shortly; nothing was counted | ## About this document Generated from the endpoint registry, the guides and the plan configuration that the documentation pages themselves render from. The date at the top is the date of those sources, so two copies with the same date are identical, and an older date means a stale copy: check it against https://tvguideapi.com/documentation/manual.md. Machine-readable alternatives: `https://tvguideapi.com/openapi.json` for the OpenAPI description, `https://api.tvguideapi.com/mcp` for the Model Context Protocol server, and `https://tvguideapi.com/skill.md` for the agent skill.