# TVmaze TV Shows API

> TV shows, episodes, cast and daily schedules worldwide from TVmaze: networks, ratings, air times

- Vendor: `tvmazetvshowsapi` · version 1.0 · category Entertainment · tags tv shows api, tv schedule api, episodes api, tvmaze api, tv guide api, series data api
- Datasource: custom HTTP routes
- Marketplace page: https://apiclay.com/api/tvmazetvshowsapi
- This document: https://apiclay.com/docs/tvmazetvshowsapi.md
- OpenAPI 3.1: https://apiclay.com/api/tvmazetvshowsapi/openapi.json
- MCP: connect https://api.apiclay.com/v1/mcp (see https://apiclay.com/llms.txt), then `apiclay_describe_api` with vendor `tvmazetvshowsapi`
- Updated: 2026-11-18

## About

## TVmaze TV Shows API

TV data from TVmaze: search shows, read a show (network, schedule, status, genres, rating, IMDb/TheTVDB ids, summary, image), its episodes and cast, and the day's TV schedule for any country.

Data comes from **tvmaze.com** (https://www.tvmaze.com). Every route calls the source's own public API and returns it unchanged.

Typical flow: `/search?q=girls`, then `/show?id=139` and `/episodes?id=139`; `/schedule?country=US&amp;date=2026-11-11`.

### Routes

#### GET `/search` - Search shows
| Param | In | Type | Required | Description |
|---|---|---|---|---|
| q | query | string | yes | Show name. |

Returns: array of `{score, show}`.

#### GET `/show` - Show
| Param | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | number | yes | TVmaze show id. |
| embed | query | string | no | `episodes`, `cast` or `nextepisode`. |

Returns: `name`, `type`, `genres`, `status`, `premiered`, `schedule`, `rating`, `network`, `externals`, `summary`.

#### GET `/episodes` - Episodes
| Param | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | number | yes | Show id. |

Returns: array of episodes (`season`, `number`, `airdate`, `name`, `summary`).

#### GET `/cast` - Cast
| Param | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | number | yes | Show id. |

Returns: array of `{person, character}`.

#### GET `/schedule` - Schedule
| Param | In | Type | Required | Description |
|---|---|---|---|---|
| country | query | string | no | Two-letter country, e.g. `US`. |
| date | query | string | no | `YYYY-MM-DD` (default today). |

Returns: array of episodes airing that day with their show.

### Caveats

- TVmaze data is CC BY-SA; credit TVmaze.
- Upstream responses can change over time. Verify fields before relying on them.
- Not affiliated with or endorsed by tvmaze.com.

## Pricing

- Pay as you go: 0.0012 credits/request
- Trial: 1 free requests per buyer
- Billing order: trial requests -> subscribed plan requests -> pay as you go. 1 credit's USD value is shown on the marketplace page.

## HTTP routes

Only the public, buyer-facing parts of each route are listed; vendor-side credentials stay on the gateway.

### GET /search — Search shows
- Gateway: `GET https://api.apiclay.com/v1/api/tvmazetvshowsapi/search`
- Public query params: `q` (string, required)
- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

### GET /show — Show
- Gateway: `GET https://api.apiclay.com/v1/api/tvmazetvshowsapi/show`
- Public query params: `embed` (string), `id` (string, required)
- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

### GET /episodes — Episodes
- Gateway: `GET https://api.apiclay.com/v1/api/tvmazetvshowsapi/episodes`
- Public query params: `id` (string, required)
- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

### GET /cast — Cast
- Gateway: `GET https://api.apiclay.com/v1/api/tvmazetvshowsapi/cast`
- Public query params: `id` (string, required)
- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

### GET /schedule — Schedule
- Gateway: `GET https://api.apiclay.com/v1/api/tvmazetvshowsapi/schedule`
- Public query params: `country` (string), `date` (string)
- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

## Call example

```bash
curl -X GET "https://api.apiclay.com/v1/api/tvmazetvshowsapi/search?q=<q>" \
  -H "token: <YOUR_APICLAY_TOKEN>"
```

Index of every published API: https://apiclay.com/llms.txt
