{ "openapi": "3.1.0", "info": { "title": "TV Guide API", "version": "2026.10.12", "description": "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." }, "servers": [ { "url": "https://api.tvguideapi.com/v1" } ], "security": [ { "bearer": [] } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" } } }, "paths": { "/channels": { "get": { "operationId": "channels", "summary": "List channels", "description": "Every TV channel in the registry, filtered by country, language, category or logo, with one stable id per channel across all our sources.", "tags": [ "Channels" ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "Country codes, ISO 3166-1 alpha-2, comma separated.", "schema": { "type": "string" }, "example": "GB" }, { "name": "lang", "in": "query", "required": false, "description": "Language codes, ISO 639-3.", "schema": { "type": "string" }, "example": "eng" }, { "name": "category", "in": "query", "required": false, "description": "news, sports, kids, movies, music, general...", "schema": { "type": "string" }, "example": "sports" }, { "name": "has_logo", "in": "query", "required": false, "description": "Only channels with a logo.", "schema": { "type": "boolean" }, "example": "true" }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 500. Defaults to 100.", "schema": { "type": "integer" }, "example": "100" }, { "name": "cursor", "in": "query", "required": false, "description": "The cursor from the previous answer's meta.next. See Paging and fields.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "required": false, "description": "Only these fields, comma separated.", "schema": { "type": "string" }, "example": "start,title,episode" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/channels" } } }, "/channels/search": { "get": { "operationId": "channels_search", "summary": "Find a channel", "description": "Find a TV channel by its name, an alias or a call sign, in any country, and get the id every other endpoint takes.", "tags": [ "Channels" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Name, alias or call sign.", "schema": { "type": "string" }, "example": "bbc one" }, { "name": "country", "in": "query", "required": false, "description": "Country codes, ISO 3166-1 alpha-2, comma separated.", "schema": { "type": "string" }, "example": "GB" }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 500. Defaults to 100.", "schema": { "type": "integer" }, "example": "100" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/channels-search" } } }, "/channels/{id}": { "get": { "operationId": "channels_id", "summary": "Get a channel", "description": "One TV channel in full: its names, owner, country, languages, categories, logo, website, launch year and the guide feeds behind it.", "tags": [ "Channels" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The channel id. Ids come from Find a channel.", "schema": { "type": "string" }, "example": "ch_jw83a3xg" }, { "name": "fields", "in": "query", "required": false, "description": "Only these fields, comma separated.", "schema": { "type": "string" }, "example": "start,title,episode" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/channels-id" } } }, "/channels/{id}/schedule": { "get": { "operationId": "channels_id_schedule", "summary": "A channel's schedule", "description": "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.", "tags": [ "Channels" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The channel id. Ids come from Find a channel.", "schema": { "type": "string" }, "example": "ch_jw83a3xg" }, { "name": "date", "in": "query", "required": false, "description": "The day, YYYY-MM-DD. Defaults to today.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-07" }, { "name": "tz", "in": "query", "required": false, "description": "Which local day to cut, as an IANA zone. The times in the answer stay UTC. See Times and days.", "schema": { "type": "string" }, "example": "Europe/London" }, { "name": "fields", "in": "query", "required": false, "description": "Only these fields, comma separated.", "schema": { "type": "string" }, "example": "start,title,episode" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/channels-id-schedule" } } }, "/channels/{id}/now": { "get": { "operationId": "channels_id_now", "summary": "On a channel now", "description": "What is on a TV channel right now and what comes next, with how far through the current programme it is.", "tags": [ "Channels" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The channel id. Ids come from Find a channel.", "schema": { "type": "string" }, "example": "ch_jw83a3xg" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/channels-id-now" } } }, "/channels/{id}/next": { "get": { "operationId": "channels_id_next", "summary": "Next on a channel", "description": "The next programmes on a TV channel, as many as you ask for, each with its times in UTC and its episode where matched.", "tags": [ "Channels" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The channel id. Ids come from Find a channel.", "schema": { "type": "string" }, "example": "ch_jw83a3xg" }, { "name": "count", "in": "query", "required": false, "description": "How many, 1 to 20. Defaults to 3.", "schema": { "type": "integer" }, "example": "3" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/channels-id-next" } } }, "/channels/{id}/free-view": { "get": { "operationId": "channels_id_free_view", "summary": "Watch a channel free", "description": "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.", "tags": [ "Channels" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The channel id. Ids come from Find a channel.", "schema": { "type": "string" }, "example": "ch_jw83a3xg" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/channels-id-free-view" } } }, "/channels/{id}/history": { "get": { "operationId": "channels_id_history", "summary": "A channel's past schedules", "description": "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.", "tags": [ "Channels" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The channel id. Ids come from Find a channel.", "schema": { "type": "string" }, "example": "ch_jw83a3xg" }, { "name": "from", "in": "query", "required": true, "description": "Window start, UTC.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "to", "in": "query", "required": true, "description": "Window end, UTC; at most 31 days after from.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-02T00:00:00Z" }, { "name": "cursor", "in": "query", "required": false, "description": "The cursor from the previous answer's meta.next. See Paging and fields.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/channels-id-history" } } }, "/countries": { "get": { "operationId": "countries", "summary": "List countries", "description": "Every country we hold TV listings for, with its channel count, its guide feeds and how many programmes it has today.", "tags": [ "Countries" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/countries" } } }, "/countries/{cc}": { "get": { "operationId": "countries_country", "summary": "Get a country", "description": "One country's TV guide at a glance: channels, guide feeds, when its data last changed and how full each field is today.", "tags": [ "Countries" ], "parameters": [ { "name": "cc", "in": "path", "required": true, "description": "Country code, ISO 3166-1 alpha-2.", "schema": { "type": "string" }, "example": "GB" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/countries-country" } } }, "/countries/{cc}/channels": { "get": { "operationId": "countries_country_channels", "summary": "A country's channels", "description": "Every TV channel in one country, ordered the way its own guides list them, with ids, names, logos and categories.", "tags": [ "Countries" ], "parameters": [ { "name": "cc", "in": "path", "required": true, "description": "Country code, ISO 3166-1 alpha-2.", "schema": { "type": "string" }, "example": "GB" }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 500. Defaults to 100.", "schema": { "type": "integer" }, "example": "100" }, { "name": "cursor", "in": "query", "required": false, "description": "The cursor from the previous answer's meta.next. See Paging and fields.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/countries-country-channels" } } }, "/countries/{cc}/now": { "get": { "operationId": "countries_country_now", "summary": "Now in a country", "description": "What is on now on every TV channel in a country, with what comes next, in one call.", "tags": [ "Countries" ], "parameters": [ { "name": "cc", "in": "path", "required": true, "description": "Country code, ISO 3166-1 alpha-2.", "schema": { "type": "string" }, "example": "GB" }, { "name": "category", "in": "query", "required": false, "description": "Only this kind of channel.", "schema": { "type": "string" }, "example": "sports" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/countries-country-now" } } }, "/countries/{cc}/tonight": { "get": { "operationId": "countries_country_tonight", "summary": "Tonight in a country", "description": "Prime time tonight on every TV channel in a country, from the local hour you choose, in one grid.", "tags": [ "Countries" ], "parameters": [ { "name": "cc", "in": "path", "required": true, "description": "Country code, ISO 3166-1 alpha-2.", "schema": { "type": "string" }, "example": "GB" }, { "name": "from_hour", "in": "query", "required": false, "description": "Local hour to start from. Defaults to 19.", "schema": { "type": "integer" }, "example": "19" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/countries-country-tonight" } } }, "/countries/{cc}/coverage": { "get": { "operationId": "countries_country_coverage", "summary": "Country coverage", "description": "How full the TV data is for a country on a day: the share of programmes with a description, category, episode number and more.", "tags": [ "Countries" ], "parameters": [ { "name": "cc", "in": "path", "required": true, "description": "Country code, ISO 3166-1 alpha-2.", "schema": { "type": "string" }, "example": "GB" }, { "name": "date", "in": "query", "required": false, "description": "The day, YYYY-MM-DD. Defaults to today.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-07" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/countries-country-coverage" } } }, "/guide": { "get": { "operationId": "guide", "summary": "TV guide grid", "description": "A TV guide grid for up to 50 channels over a window you choose, every slot with its times in UTC, ready to draw.", "tags": [ "Guide" ], "parameters": [ { "name": "channels", "in": "query", "required": true, "description": "Channel ids, comma separated, up to 50.", "schema": { "type": "string" }, "example": "ch_jw83a3xg,ch_7qk3m2xa" }, { "name": "from", "in": "query", "required": true, "description": "Window start, UTC.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "to", "in": "query", "required": true, "description": "Window end, UTC; at most 31 days after from.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-02T00:00:00Z" }, { "name": "fields", "in": "query", "required": false, "description": "Only these fields, comma separated.", "schema": { "type": "string" }, "example": "start,title,episode" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/guide" } } }, "/now": { "get": { "operationId": "now", "summary": "Now on", "description": "What is on now on the TV channels you name, or across a whole country, with what comes next on each.", "tags": [ "Guide" ], "parameters": [ { "name": "channels", "in": "query", "required": false, "description": "Channel ids, comma separated, up to 50.", "schema": { "type": "string" }, "example": "ch_jw83a3xg,ch_7qk3m2xa" }, { "name": "country", "in": "query", "required": false, "description": "Or a country code instead of channels.", "schema": { "type": "string" }, "example": "GB" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/now" } } }, "/next": { "get": { "operationId": "next", "summary": "Next on", "description": "The next programme on each of the TV channels you name, or across a whole country.", "tags": [ "Guide" ], "parameters": [ { "name": "channels", "in": "query", "required": false, "description": "Channel ids, comma separated, up to 50.", "schema": { "type": "string" }, "example": "ch_jw83a3xg,ch_7qk3m2xa" }, { "name": "country", "in": "query", "required": false, "description": "Or a country code instead of channels.", "schema": { "type": "string" }, "example": "GB" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/next" } } }, "/listings/{id}": { "get": { "operationId": "listings_id", "summary": "Get a listing", "description": "One TV listing slot in full: times, title, sub-title, description, category, rating, flags, its episode and the feeds it came from.", "tags": [ "Guide" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The listing id.", "schema": { "type": "string" }, "example": "ls_shr78fcp" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/listings-id" } } }, "/listings/search": { "get": { "operationId": "listings_search", "summary": "Search listings", "description": "Find upcoming TV programmes by words in their title, sub-title or description, in the countries you choose.", "tags": [ "Guide" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Words to find.", "schema": { "type": "string" }, "example": "eastenders" }, { "name": "country", "in": "query", "required": false, "description": "Country codes, ISO 3166-1 alpha-2, comma separated.", "schema": { "type": "string" }, "example": "GB" }, { "name": "from", "in": "query", "required": false, "description": "From when, UTC. Defaults to now.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-07T00:00:00Z" }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 500. Defaults to 100.", "schema": { "type": "integer" }, "example": "100" }, { "name": "cursor", "in": "query", "required": false, "description": "The cursor from the previous answer's meta.next. See Paging and fields.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/listings-search" } } }, "/premieres": { "get": { "operationId": "premieres", "summary": "Premieres", "description": "New episodes and first showings on a day, across the TV channels of the countries you choose.", "tags": [ "Guide" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "Country codes, ISO 3166-1 alpha-2, comma separated.", "schema": { "type": "string" }, "example": "GB" }, { "name": "date", "in": "query", "required": false, "description": "The day, YYYY-MM-DD. Defaults to today.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-07" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/premieres" } } }, "/live": { "get": { "operationId": "live", "summary": "Live slots", "description": "TV slots marked live, on now and later today, in the countries you choose.", "tags": [ "Guide" ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "Country codes, ISO 3166-1 alpha-2, comma separated.", "schema": { "type": "string" }, "example": "GB" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/live" } } }, "/xmltv": { "get": { "operationId": "xmltv", "summary": "XMLTV export", "description": "A country or a set of channels as a standard XMLTV file, up to 14 days ahead, for media centres and IPTV players.", "tags": [ "Guide" ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "A country code.", "schema": { "type": "string" }, "example": "GB" }, { "name": "channels", "in": "query", "required": false, "description": "Channel ids, comma separated, up to 50.", "schema": { "type": "string" }, "example": "ch_jw83a3xg,ch_7qk3m2xa" }, { "name": "days", "in": "query", "required": false, "description": "Days ahead, 1 to 14. Defaults to 7.", "schema": { "type": "integer" }, "example": "7" } ], "responses": { "200": { "description": "OK", "content": { "application/xml": { "example": "\n\n \n EastEnders\n \n" } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/xmltv" } } }, "/shows/search": { "get": { "operationId": "shows_search", "summary": "Find a show", "description": "Find a TV show by any of its titles and get its id, network, status and premiere date.", "tags": [ "Shows and episodes" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "A title.", "schema": { "type": "string" }, "example": "eastenders" }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 500. Defaults to 100.", "schema": { "type": "integer" }, "example": "100" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/shows-search" } } }, "/shows/{id}": { "get": { "operationId": "shows_id", "summary": "Get a show", "description": "One TV show: its titles, network, genres, status, premiere and its ids at TVmaze, TheTVDB, IMDb and Wikidata.", "tags": [ "Shows and episodes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The show id. Ids come from Find a show.", "schema": { "type": "string" }, "example": "sh_e29nzc1x" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "sh_e29nzc1x", "name": "EastEnders", "network": { "name": "BBC One" }, "status": "Running", "premiered": "1985-02-19", "genres": [ "Drama" ], "source": "tvmaze" }, "meta": { "took_ms": 23 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/shows-id" } } }, "/shows/{id}/episodes": { "get": { "operationId": "shows_id_episodes", "summary": "A show's episodes", "description": "Every episode of a TV show, season by season, with numbers, names and original air dates.", "tags": [ "Shows and episodes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The show id. Ids come from Find a show.", "schema": { "type": "string" }, "example": "sh_e29nzc1x" }, { "name": "season", "in": "query", "required": false, "description": "One season only.", "schema": { "type": "integer" }, "example": "41" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/shows-id-episodes" } } }, "/shows/{id}/cast": { "get": { "operationId": "shows_id_cast", "summary": "A show's cast", "description": "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.", "tags": [ "Shows and episodes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The show id. Ids come from Find a show.", "schema": { "type": "string" }, "example": "sh_e29nzc1x" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "person": { "id": 1, "name": "Example Actor", "country": "GB" }, "character": "Lead role", "self": false, "voice": false } ], "meta": { "count": 1, "next": null, "took_ms": 41 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/shows-id-cast" } } }, "/shows/{id}/airings": { "get": { "operationId": "shows_id_airings", "summary": "Where a show airs", "description": "When and where a TV show airs next, in every country or the ones you choose, first runs and repeats.", "tags": [ "Shows and episodes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The show id. Ids come from Find a show.", "schema": { "type": "string" }, "example": "sh_e29nzc1x" }, { "name": "country", "in": "query", "required": false, "description": "Country codes, ISO 3166-1 alpha-2, comma separated.", "schema": { "type": "string" }, "example": "GB" }, { "name": "days", "in": "query", "required": false, "description": "Days ahead, 1 to 14.", "schema": { "type": "integer" }, "example": "7" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/shows-id-airings" } } }, "/shows/{id}/history": { "get": { "operationId": "shows_id_history", "summary": "A show's past airings", "description": "Every past airing of a TV show that the archive holds, over a window you choose.", "tags": [ "Shows and episodes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The show id. Ids come from Find a show.", "schema": { "type": "string" }, "example": "sh_e29nzc1x" }, { "name": "from", "in": "query", "required": true, "description": "Window start, UTC.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "to", "in": "query", "required": true, "description": "Window end, UTC; at most 31 days after from.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-02T00:00:00Z" }, { "name": "cursor", "in": "query", "required": false, "description": "The cursor from the previous answer's meta.next. See Paging and fields.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/shows-id-history" } } }, "/episodes/{id}": { "get": { "operationId": "episodes_id", "summary": "Get an episode", "description": "One TV episode: its show, season, number, name, runtime and original air date.", "tags": [ "Shows and episodes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The episode id.", "schema": { "type": "string" }, "example": "ep_610mmeyh" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/episodes-id" } } }, "/episodes/{id}/airings": { "get": { "operationId": "episodes_id_airings", "summary": "Where an episode aired", "description": "Every showing of one TV episode we hold, the first run and every repeat, on every channel.", "tags": [ "Shows and episodes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The episode id.", "schema": { "type": "string" }, "example": "ep_610mmeyh" }, { "name": "cursor", "in": "query", "required": false, "description": "The cursor from the previous answer's meta.next. See Paging and fields.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/episodes-id-airings" } } }, "/networks": { "get": { "operationId": "networks", "summary": "List networks", "description": "TV networks and streaming services, by country, with their ids.", "tags": [ "Shows and episodes" ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "A country code.", "schema": { "type": "string" }, "example": "GB" }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 500. Defaults to 100.", "schema": { "type": "integer" }, "example": "100" }, { "name": "cursor", "in": "query", "required": false, "description": "The cursor from the previous answer's meta.next. See Paging and fields.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": "nw_2szm9pm5", "name": "BBC One", "country": "GB", "kind": "network" } ], "meta": { "count": 400, "next": "c_8f21a0", "took_ms": 41 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/networks" } } }, "/networks/{id}/shows": { "get": { "operationId": "networks_id_shows", "summary": "A network's shows", "description": "The TV shows of one network or streaming service, running or ended.", "tags": [ "Shows and episodes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The network id.", "schema": { "type": "string" }, "example": "nw_2szm9pm5" }, { "name": "status", "in": "query", "required": false, "description": "running or ended.", "schema": { "type": "string" }, "example": "running" }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 500. Defaults to 100.", "schema": { "type": "integer" }, "example": "100" }, { "name": "cursor", "in": "query", "required": false, "description": "The cursor from the previous answer's meta.next. See Paging and fields.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": "sh_e29nzc1x", "name": "EastEnders", "status": "Running" } ], "meta": { "count": 120, "next": "c_8f21a0", "took_ms": 41 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/networks-id-shows" } } }, "/sports": { "get": { "operationId": "sports", "summary": "List sports", "description": "The sports with events on TV this week, and how many events each has.", "tags": [ "Sport and events" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "sport": "football", "events_week": 412 }, { "sport": "cricket", "events_week": 38 } ], "meta": { "count": 2, "next": null, "took_ms": 41 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/sports" } } }, "/leagues": { "get": { "operationId": "leagues", "summary": "List leagues", "description": "Sports competitions with events on TV, by sport and country, with their ids.", "tags": [ "Sport and events" ], "parameters": [ { "name": "sport", "in": "query", "required": false, "description": "A sport: football, cricket, basketball, rugby, tennis...", "schema": { "type": "string" }, "example": "football" }, { "name": "country", "in": "query", "required": false, "description": "A country code.", "schema": { "type": "string" }, "example": "GB" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": "chinese-professional-baseball-league", "name": "Premier League", "sport": "football", "country": "GB" } ], "meta": { "count": 1, "next": null, "took_ms": 41 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/leagues" } } }, "/leagues/{id}/events": { "get": { "operationId": "leagues_id_events", "summary": "A league's events", "description": "A competition's fixtures over a window, each with every channel showing it and whether it is live.", "tags": [ "Sport and events" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The league id.", "schema": { "type": "string" }, "example": "chinese-professional-baseball-league" }, { "name": "from", "in": "query", "required": true, "description": "Window start, UTC.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "to", "in": "query", "required": true, "description": "Window end, UTC; at most 31 days after from.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-02T00:00:00Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/leagues-id-events" } } }, "/events": { "get": { "operationId": "events", "summary": "Events", "description": "Sports events on TV by sport, league and day, in every country or only those on air where you are.", "tags": [ "Sport and events" ], "parameters": [ { "name": "sport", "in": "query", "required": false, "description": "A sport: football, cricket, basketball, rugby, tennis...", "schema": { "type": "string" }, "example": "football" }, { "name": "league", "in": "query", "required": false, "description": "A league id.", "schema": { "type": "string" }, "example": "chinese-professional-baseball-league" }, { "name": "date", "in": "query", "required": false, "description": "The day, YYYY-MM-DD. Defaults to today.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-07" }, { "name": "country", "in": "query", "required": false, "description": "Only events on air in this country.", "schema": { "type": "string" }, "example": "TH" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/events" } } }, "/events/{id}": { "get": { "operationId": "events_id", "summary": "Get an event", "description": "One sports event: its teams, league, round, venue and start time, with the channels showing it.", "tags": [ "Sport and events" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The event id. Ids come from Events.", "schema": { "type": "string" }, "example": "ev_d2bh99ey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/events-id" } } }, "/events/{id}/broadcasts": { "get": { "operationId": "events_id_broadcasts", "summary": "Where to watch an event", "description": "Every TV channel showing a sports event, country by country, and whether each showing is live, delayed or a repeat.", "tags": [ "Sport and events" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The event id. Ids come from Events.", "schema": { "type": "string" }, "example": "ev_d2bh99ey" }, { "name": "country", "in": "query", "required": false, "description": "Country codes, ISO 3166-1 alpha-2, comma separated.", "schema": { "type": "string" }, "example": "GB" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/events-id-broadcasts" } } }, "/events/live": { "get": { "operationId": "events_live", "summary": "Live events now", "description": "Sports events live on TV right now, in a country or everywhere, with the channels showing them.", "tags": [ "Sport and events" ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "A country code.", "schema": { "type": "string" }, "example": "GB" }, { "name": "sport", "in": "query", "required": false, "description": "A sport: football, cricket, basketball, rugby, tennis...", "schema": { "type": "string" }, "example": "football" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/events-live" } } }, "/events/upcoming": { "get": { "operationId": "events_upcoming", "summary": "Upcoming events", "description": "The next sports events on TV with their channels, soonest first, over the hours ahead you choose.", "tags": [ "Sport and events" ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "A country code.", "schema": { "type": "string" }, "example": "TH" }, { "name": "hours", "in": "query", "required": false, "description": "Hours ahead, 1 to 168.", "schema": { "type": "integer" }, "example": "24" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/events-upcoming" } } }, "/events/{id}/replays": { "get": { "operationId": "events_id_replays", "summary": "An event's replays", "description": "Later showings of a sports event: repeats, highlights and delayed broadcasts, on every channel.", "tags": [ "Sport and events" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The event id. Ids come from Events.", "schema": { "type": "string" }, "example": "ev_d2bh99ey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "country": "GB", "channel": "ch_m0x4hs7r", "start": "2026-10-18T22:00:00Z", "kind": "repeat" } ], "meta": { "count": 1, "next": null, "took_ms": 41 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/events-id-replays" } } }, "/teams/{id}/events": { "get": { "operationId": "teams_id_events", "summary": "Where a team is on", "description": "Where a team's matches are shown on TV, in every country or the ones you choose.", "tags": [ "Sport and events" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The team id.", "schema": { "type": "string" }, "example": "india" }, { "name": "country", "in": "query", "required": false, "description": "Country codes, ISO 3166-1 alpha-2, comma separated.", "schema": { "type": "string" }, "example": "GB" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/teams-id-events" } } }, "/rights": { "get": { "operationId": "rights", "summary": "Broadcast rights history", "description": "Who held the TV rights to a competition, by country and season, from the yearly versions of public broadcaster lists.", "tags": [ "Sport and events" ], "parameters": [ { "name": "competition", "in": "query", "required": true, "description": "The competition.", "schema": { "type": "string" }, "example": "Premier League" }, { "name": "country", "in": "query", "required": false, "description": "A country code.", "schema": { "type": "string" }, "example": "TH" }, { "name": "season", "in": "query", "required": false, "description": "A season.", "schema": { "type": "string" }, "example": "2019-20" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "competition": "Premier League", "country": "TH", "season": "2019-20", "holders": [ "TrueVisions" ], "source": "wikipedia" } ], "meta": { "count": 1, "next": null, "took_ms": 41 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/rights" } } }, "/venue/tonight": { "get": { "operationId": "venue_tonight", "summary": "Tonight's screens", "description": "Tonight's sport for a bar or venue: live events first, one row per event with every channel you receive that has it.", "tags": [ "Venue plans" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "The venue's country.", "schema": { "type": "string" }, "example": "GB" }, { "name": "sports", "in": "query", "required": false, "description": "Sports to show.", "schema": { "type": "string" }, "example": "football,rugby" }, { "name": "channels", "in": "query", "required": false, "description": "Channel ids, comma separated, up to 50.", "schema": { "type": "string" }, "example": "ch_jw83a3xg,ch_7qk3m2xa" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/venue-tonight" } } }, "/venue/week": { "get": { "operationId": "venue_week", "summary": "The week ahead", "description": "The week ahead for a bar or venue, day by day, live events first, on the channels you receive.", "tags": [ "Venue plans" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "The venue's country.", "schema": { "type": "string" }, "example": "GB" }, { "name": "sports", "in": "query", "required": false, "description": "Sports to show.", "schema": { "type": "string" }, "example": "football,rugby" }, { "name": "channels", "in": "query", "required": false, "description": "Channel ids, comma separated, up to 50.", "schema": { "type": "string" }, "example": "ch_jw83a3xg,ch_7qk3m2xa" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "day": "2026-10-18", "events": 6, "live": 5 } ], "meta": { "count": 1, "next": null, "took_ms": 41 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/venue-week" } } }, "/me": { "get": { "operationId": "me", "summary": "Your account", "description": "Your plan, your keys by prefix and label, and your daily limit.", "tags": [ "Account and meta" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/me" } } }, "/usage": { "get": { "operationId": "usage", "summary": "Your usage", "description": "Your calls per day and per endpoint over the days you choose.", "tags": [ "Account and meta" ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "Days back, 1 to 90.", "schema": { "type": "integer" }, "example": "30" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "date": "2026-10-07", "calls": 31 }, { "date": "2026-10-06", "calls": 50 } ], "meta": { "count": 2, "next": null, "took_ms": 41 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/usage" } } }, "/status": { "get": { "operationId": "status", "summary": "Status", "description": "How fresh every source is right now, and whether the API is answering normally. No key needed.", "tags": [ "Account and meta" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "ok": true, "updated": "2026-10-07T10:31:02Z", "live_lag_s": 1 }, "meta": { "took_ms": 23 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/status" }, "security": [] } }, "/fields": { "get": { "operationId": "fields", "summary": "Field fill", "description": "How full each listing field is today, country by country.", "tags": [ "Account and meta" ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "Country codes, ISO 3166-1 alpha-2, comma separated.", "schema": { "type": "string" }, "example": "GB" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/fields" } } }, "/sources": { "get": { "operationId": "sources", "summary": "Sources and licences", "description": "Every source behind the data, the fields it supplies, its licence and the credit it asks for.", "tags": [ "Account and meta" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/sources" } } }, "/mcp": { "post": { "operationId": "mcp_endpoint", "summary": "MCP endpoint", "description": "The Model Context Protocol server: the same data as tools for Claude, ChatGPT and other assistants.", "tags": [ "Agents" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "jsonrpc": "2.0", "id": 1, "result": { "tools": [ { "name": "whats_on_now" }, { "name": "channel_day" }, { "name": "where_to_watch" }, { "name": "next_airing" } ] } } } } } }, "externalDocs": { "url": "https://tvguideapi.com/documentation/mcp-endpoint" } } } } }