# TV Shows API > TV episode guides and daily broadcast schedules as an API, powered by TVMaze. Look up any TV show by name or id for its network, genres, status, rating and summary; pull a show's full episode list with air dates and S01E01-style codes; fetch a specific episode by season and number; and get the complete TV schedule for any country and date — everything airing that day with show, network, episode and air time. Across broadcast, cable and streaming. Ideal for TV-guide and watchlist apps, episode trackers and "what to watch" widgets, calendar reminders, media-centre dashboards and entertainment chatbots. ## Authentication All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys. ```bash curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/tvshows-api/..." ``` ## Pricing - **Free** (Free) — 8,500 calls/Mo, 2 req/s - **Starter** ($5/Mo) — 125,000 calls/Mo, 8 req/s - **Pro** ($15/Mo) — 560,000 calls/Mo, 20 req/s - **Mega** ($41/Mo) — 2,300,000 calls/Mo, 50 req/s ## Endpoints ### TV #### `GET /v1/episode` — A specific episode by season + number **Parameters:** - `id` (query, optional, string) — Show id, e.g. 169 Example: `169` - `show` (query, optional, string) — Or show name - `season` (query, required, string) — Season number Example: `1` - `number` (query, required, string) — Episode number Example: `1` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/tvshows-api/v1/episode?id=169&season=1&number=1" ``` **Response:** ```json { "data": { "show": { "id": 169, "name": "Breaking Bad" }, "episode": { "id": 12192, "code": "S01E01", "name": "Pilot", "type": "regular", "image": "https://static.tvmaze.com/uploads/images/original_untouched/405/1012681.jpg", "number": 1, "rating": 8.2, "season": 1, "airdate": "2008-01-20", "airtime": "22:00", "runtime": 60, "summary": "A high-school chemistry teacher (Bryan Cranston) is diagnosed with a deadly cancer, so he puts his expertise to use and teams with an ex-student (Aaron Paul) to manufacture top-grade crystal meth in hopes of providing for his family after he's gone." } }, "meta": { "timestamp": "2026-06-01T00:04:21.699Z", "request_id": "d7ed73ac-65c7-41c1-9961-befcae4f5239" }, "status": "ok", "message": "Episode retrieved", "success": true } ``` #### `GET /v1/episodes` — Full episode list for a show **Parameters:** - `show` (query, optional, string) — Show name Example: `Breaking Bad` - `id` (query, optional, string) — Show id **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/tvshows-api/v1/episodes?show=Breaking+Bad" ``` **Response:** ```json { "data": { "show": { "id": 169, "name": "Breaking Bad" }, "count": 62, "episodes": [ { "id": 12192, "code": "S01E01", "name": "Pilot", "type": "regular", "image": "https://static.tvmaze.com/uploads/images/original_untouched/405/1012681.jpg", "number": 1, "rating": 8.2, "season": 1, "airdate": "2008-01-20", "airtime": "22:00", "runtime": 60, "summary": "A high-school chemistry teacher (Bryan Cranston) is diagnosed with a deadly cancer, so he puts his expertise to use and teams with an ex-student (Aaron Paul) to manufacture top-grade crystal meth in hopes of providing for his family after he's gone." }, { "id": 12193, "code": "S01E02", "name": "Cat's in the Bag...", "type": "regular", "image": "https://static.tvmaze.com/uploads/images/original_untouched/405/1012682.jpg", "number": 2, "rating": 7.9, "season": 1, "airdate": "2008-01-27", "airtime": "22:00", "runtime": 60, "summary": "After the accident in the desert, Walter and Jesse need to dispose of the unfortunate mess in their rolling lab of an RV, and …(truncated, see openapi.json for full schema) ``` #### `GET /v1/schedule` — What is airing on a date **Parameters:** - `country` (query, optional, string) — 2-letter country (default US) Example: `US` - `date` (query, optional, string) — YYYY-MM-DD Example: `2024-01-01` - `limit` (query, optional, string) — Max airings (1-250) Example: `50` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/tvshows-api/v1/schedule?country=US&date=2024-01-01&limit=50" ``` **Response:** ```json { "data": { "date": "2024-01-01", "count": 50, "total": 82, "airings": [ { "code": "S2023E02", "show": "New Year's Eve Live with Anderson Cooper and Andy Cohen", "time": "2024-01-01T05:30:00+00:00", "episode": "New Year's Eve Live with Sara Sidner and Cari Champion", "network": "CNN", "runtime": 150 }, { "code": "S2024E01", "show": "CNN This Morning", "time": "2024-01-01T10:00:00+00:00", "episode": "Episode 1", "network": "CNN", "runtime": 120 }, { "code": "S2024E01", "show": "Bloomberg Brief", "time": "2024-01-01T10:00:00+00:00", "episode": "Episode 1", "network": "Bloomberg TV", "runtime": 60 }, { "code": "S2024E01", "show": "FOX Weather First", "time": "2024-01-01T10:00:00+00:00", "episode": "Episode 1", "network": "Fox Business Network", "runtime": 60 }, { "code": "S2024E01", "show": "FOX & Friends", "time": "2024-01-01T11:00:00+00:00", "episode": "Episode 1", "network": "Fox …(truncated, see openapi.json for full schema) ``` #### `GET /v1/show` — Show details by name or id **Parameters:** - `show` (query, optional, string) — Show name, e.g. Breaking Bad Example: `Breaking Bad` - `id` (query, optional, string) — TVMaze show id **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/tvshows-api/v1/show?show=Breaking+Bad" ``` **Response:** ```json { "data": { "show": { "id": 169, "name": "Breaking Bad", "type": "Scripted", "ended": "2019-10-11", "image": "https://static.tvmaze.com/uploads/images/original_untouched/501/1253519.jpg", "genres": [ "Drama", "Crime", "Thriller" ], "rating": 9.2, "status": "Ended", "country": "US", "network": "AMC", "runtime": 60, "summary": "Breaking Bad follows protagonist Walter White, a chemistry teacher who lives in New Mexico with his wife and teenage son who has cerebral palsy. White is diagnosed with Stage III cancer and given a prognosis of two years left to live. With a new sense of fearlessness based on his medical prognosis, and a desire to secure his family's financial security, White chooses to enter a dangerous world of drugs and crime and ascends to power in this world. The series explores how a fatal diagnosis such as White's releases a typical man from the daily concerns and constraints of normal society and follows his transformation from mild family man to a kingpin of the drug trade.", "language": "English", "premiered": "2008-01-20", "official_site": "http://www.amc.com/shows/breaking-bad" } }, "meta": { "timestamp": "2026-06-01T00:04:22.078Z", "request_id": "a3462168-d099-4691-b444-f300317df …(truncated, see openapi.json for full schema) ``` ### Meta #### `GET /v1/meta` — Usage notes **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/tvshows-api/v1/meta" ``` **Response:** ```json { "data": { "note": "TV episode guides & schedules. /v1/show = a show's details by name (show=Breaking Bad) or id — network, genres, status, rating, summary; /v1/episodes = the full episode list of a show with air dates and codes (S01E01); /v1/episode = a specific episode by season & number; /v1/schedule = what's airing in a country on a date (country=US, date=YYYY-MM-DD). Data from TVMaze (CC BY-SA).", "source": "TVMaze (api.tvmaze.com)", "endpoints": [ "/v1/show", "/v1/episodes", "/v1/episode", "/v1/schedule", "/v1/meta" ] }, "meta": { "timestamp": "2026-06-01T00:04:22.149Z", "request_id": "fa8bddf7-81ed-442a-a0d1-7db492bc65f5" }, "status": "ok", "message": "Meta retrieved", "success": true } ``` --- Marketplace page: https://www.oanor.com/api/tvshows-api OpenAPI spec: https://www.oanor.com/api/tvshows-api/openapi.json