Python TvMaze

https://github.com/yakupadakli/python-tvmaze
Admin
Python TvMaze is a Python client library that provides an interface to the TvMaze API for accessing...
Tokens:12,797
Snippets:129
Trust Score:7.4
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install python-tvmaze from source

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Clone the repository from GitHub and install it manually.

```bash
git clone https://github.com/yakupadakli/python-tvmaze.git
cd python-tvmaze
python setup.py install
```

--------------------------------

### Install python-tvmaze using pip

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Install the latest version of the library from PyPI using pip.

```bash
pip install python-tvmaze
```

--------------------------------

### Get Tvmaze Today Schedule

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve a list of all episodes airing today.

```python
api.schedule.today()
```

--------------------------------

### Show get

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieves all primary information for a specific show using its ID.

```APIDOC
## Show get

### Description
Retrieve all primary information for a given show.

### Method
api.show.get(show_id: int)

### Parameters
#### Path Parameters
- **show_id** (int) - Required - The ID of the show.
```

--------------------------------

### Episode get

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieves all primary information for a given episode using its ID.

```APIDOC
## Episode get

### Description
Retrieve all primary information for a given episode.

### Method
api.episode.get(episode_id: int)

### Parameters
#### Path Parameters
- **episode_id** (int) - Required - The ID of the episode.
```

--------------------------------

### Web Channel get

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieves all primary information for a given web channel using its ID.

```APIDOC
## Web Channel get

### Description
Retrieve all primary information for a given web channel.

### Method
api.web_channel.get(web_channel_id: int)

### Parameters
#### Path Parameters
- **web_channel_id** (int) - Required - The ID of the web channel.
```

--------------------------------

### Get Tvmaze Person by ID

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve all primary information for a given person using their ID.

```python
api.people.get(1)
```

--------------------------------

### Get Tvmaze Show AKA's

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve a list of aliases (AKA's) for a show. An AKA with a null country indicates the original country's alias.

```python
api.show.akas(1)
```

--------------------------------

### Network get

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieves all primary information for a given network using its ID.

```APIDOC
## Network get

### Description
Retrieve all primary information for a given network.

### Method
api.network.get(network_id: int)

### Parameters
#### Path Parameters
- **network_id** (int) - Required - The ID of the network.
```

--------------------------------

### Person get

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieves all primary information for a given person using their ID.

```APIDOC
## Person get

### Description
Retrieve all primary information for a given person.

### Method
api.people.get(person_id: int)

### Parameters
#### Path Parameters
- **person_id** (int) - Required - The ID of the person.
```

--------------------------------

### Get Tvmaze Show List

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve a list of all shows with primary information. Supports pagination.

```python
api.show.list()  # default page is 0
api.show.list(page=1)
```

--------------------------------

### Get Tvmaze Show Episode List

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve a complete list of episodes for a given show.

```python
api.show.episodes(1)
```

--------------------------------

### Get Tvmaze Person Crew Credits

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve all show-level crew credits for a person.

```python
api.people.crew_credits(100)
```

--------------------------------

### Get Single Show by ID

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieve detailed information for a specific show using its ID. Handles ShowNotFound exceptions if the show does not exist.

```python
from tvmaze.api import Api
from tvmaze.expections import ShowNotFound

api = Api()

try:
    show = api.show.get(1)  # "Under the Dome"
    print(show.name)          # Under the Dome
    print(show.language)      # English
    print(show.status)        # Ended
    print(show.rating.average)  # e.g. 6.5
    print(show.network.name)    # CBS
    print(show.externals.imdb)  # tt1553656
except ShowNotFound:
    print("Show not found")
```

--------------------------------

### Character get

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieves all primary information for a given character using its ID.

```APIDOC
## Character get

### Description
Retrieve all primary information for a given character.

### Method
api.character.get(character_id: int)

### Parameters
#### Path Parameters
- **character_id** (int) - Required - The ID of the character.
```

--------------------------------

### Get Main Cast for a Show

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieves the main cast members for a given show ID. Requires the `tvmaze` library to be installed.

```python
from tvmaze.api import Api

api = Api()

cast = api.show.cast(169)  # Breaking Bad
for member in cast[:3]:
    print(f"{member.person.name} as {member.character.name}")
```

--------------------------------

### Get Tvmaze Person Cast Credits

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve all show-level cast credits for a person.

```python
api.people.cast_credits(1)
```

--------------------------------

### Get Tvmaze Show Crew

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve the main crew list for a show.

```python
api.show.crew(1)
```

--------------------------------

### Get Tvmaze Show Episodes by Date

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve all episodes for a show that aired on a specific date.

```python
api.show.episodes_by_date(1, "2013-07-01")
```

--------------------------------

### Get Images for a Show

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieves image information for a show, including type and resolutions. The `resolutions` object contains URLs for original and medium sizes.

```python
from tvmaze.api import Api

api = Api()

images = api.show.images(1)
for img in images[:2]:
    print(img.type, img.resolutions.original.url)
```

--------------------------------

### Get Tvmaze Network by ID

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve all primary information for a given network using its ID.

```python
api.network.get(1)
```

--------------------------------

### Get Tvmaze WebChannel by ID

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve all primary information for a given web channel using its ID.

```python
api.web_channel.get(1)
```

--------------------------------

### Get Tvmaze Show Seasons

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve a complete list of seasons for a given show.

```python
api.show.seasons(1)
```

--------------------------------

### Get Network by ID - Python

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Fetches network details by ID, including name, official site, and country. Handles `NetworkNotFound` exceptions.

```python
from tvmaze.api import Api
from tvmaze.expections import NetworkNotFound

api = Api()

try:
    network = api.network.get(1)  # CBS
    print(network.name)            # CBS
    print(network.country.name)    # United States
    print(network.country.code)    # US
    print(network.officialSite)    # https://www.cbs.com/
except NetworkNotFound:
    print("Network not found")
```

--------------------------------

### Get Web Channel by ID - Python

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieves web channel information by ID, including name and official site. Handles `WebChannelNotFound` exceptions.

```python
from tvmaze.api import Api
from tvmaze.expections import WebChannelNotFound

api = Api()

try:
    channel = api.web_channel.get(1)  # Netflix
    print(channel.name)          # Netflix
    print(channel.officialSite)  # https://www.netflix.com
except WebChannelNotFound:
    print("Web channel not found")
```

--------------------------------

### Get Tvmaze Show Cast

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve the main cast list for a show.

```python
api.show.cast(1)
```

--------------------------------

### Get Tvmaze Show by ID

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve all primary information for a specific show using its ID.

```python
api.show.get(1)
```

--------------------------------

### Get Show by Name

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieve a show by its name. This method delegates to `api.search.single_show()` and raises `ShowNotFound` if no exact match is found.

```python
from tvmaze.api import Api
from tvmaze.expections import ShowNotFound

api = Api()

try:
    show = api.show.get_by_name("Breaking Bad")
    print(show.id, show.name)  # e.g. 169 Breaking Bad
except ShowNotFound:
    print("Show not found")
```

--------------------------------

### Get Tvmaze Episode by ID

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve all primary information for a given episode using its ID.

```python
api.episode.get(1)
```

--------------------------------

### Get Tvmaze Character by ID

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve all primary information for a given character using its ID.

```python
api.character.get(1)
```

--------------------------------

### Get Broadcast Schedule by Country and Date

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Fetches the broadcast schedule for a specific country and date. Country codes must follow ISO 3166-1 standards.

```python
from tvmaze.api import Api

api = Api()

episodes = api.schedule.filter(country_code="US", date="2014-12-01")
for ep in episodes[:3]:
    print(f"{ep.airtime} S{ep.season:02d}E{ep.number:02d} {ep.name}")
```

--------------------------------

### Get Full Future Schedule - Python

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Fetches all upcoming episodes from TvMaze. This can result in a large response, so consider slicing or filtering.

```python
from tvmaze.api import Api

api = Api()

all_upcoming = api.schedule.full()
print(f"Total upcoming episodes: {len(all_upcoming)}")
# Print the next 3
for ep in all_upcoming[:3]:
    print(ep.name, ep.airdate)
```

--------------------------------

### Get Tvmaze Full Schedule

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve a list of all future episodes known to TVmaze, regardless of country.

```python
api.schedule.full()
```

--------------------------------

### Get Aliases (AKAs) for a Show

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Fetches alternative titles (aliases) for a show, including the country of origin if available. A null country indicates the original title.

```python
from tvmaze.api import Api

api = Api()

akas = api.show.akas(1)  # Under the Dome
for aka in akas:
    country = aka.country.name if aka.country else "Original"
    print(f"{aka.name} ({country})")
```

--------------------------------

### Get Person by ID - Python

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieves a person's primary information using their ID. Handles `PeopleNotFound` exceptions.

```python
from tvmaze.api import Api
from tvmaze.expections import PeopleNotFound

api = Api()

try:
    person = api.people.get(5)  # Bryan Cranston
    print(person.name)     # Bryan Cranston
    print(person.birthday) # 1956-03-07
    print(person.gender)   # Male
    print(person.image.medium)  # URL to medium image
except PeopleNotFound:
    print("Person not found")
```

--------------------------------

### Get Character by ID - Python

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieves character details by ID, including name and image. Handles `CharacterNotFound` exceptions.

```python
from tvmaze.api import Api
from tvmaze.expections import CharacterNotFound

api = Api()

try:
    char = api.character.get(1)
    print(char.name)         # e.g. Walter White
    print(char.image.medium) # URL to image
except CharacterNotFound:
    print("Character not found")
```

--------------------------------

### Get Tvmaze Show Episode by Number

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve a specific episode from a show by its season and episode number.

```python
api.show.episode_by_number(1, season=1, number=1)
```

--------------------------------

### Get Cast Credits for Person - Python

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Fetches cast credits for a given person ID, returning `CastCredit` models with embedded show and character information.

```python
from tvmaze.api import Api

api = Api()

credits = api.people.cast_credits(5)  # Bryan Cranston
for credit in credits[:3]:
    print(f"{credit.show.name} — as {credit.character.name}")
# Output:
# Breaking Bad — as Walter White
# Malcolm in the Middle — as Hal
# ...
```

--------------------------------

### Get Today's Broadcast Schedule

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieves a list of all episodes airing today based on the server's current date and timezone. Useful for checking current TV programming.

```python
from tvmaze.api import Api

api = Api()

episodes = api.schedule.today()
for ep in episodes[:5]:
    print(f"{ep.airtime} - {ep.name} (show id: {ep.show.get('id') if isinstance(ep.show, dict) else ep.show})")
```

--------------------------------

### Get Episode by ID - Python

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Fetches a single episode's details using its ID. Handles `EpisodeNotFound` exceptions.

```python
from tvmaze.api import Api
from tvmaze.expections import EpisodeNotFound

api = Api()

try:
    ep = api.episode.get(1)
    print(ep.name)    # Pie-lette
    print(ep.season)  # 1
    print(ep.number)  # 1
    print(ep.airdate) # 2007-10-03
    print(ep.runtime) # 60
except EpisodeNotFound:
    print("Episode not found")
```

--------------------------------

### Get Crew Credits for Person - Python

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieves crew credits for a person ID, providing `CrewCredit` models with role type and associated show information.

```python
from tvmaze.api import Api

api = Api()

credits = api.people.crew_credits(100)
for credit in credits[:3]:
    print(f"{credit.type} on {credit.show.name}")
# Output:
# Director on ...
# Executive Producer on ...

```

--------------------------------

### Get Single Episode by Season and Number

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieve a specific episode using the show ID, season number, and episode number. Handles `EpisodeNotFound` exceptions.

```python
from tvmaze.api import Api
from tvmaze.expections import EpisodeNotFound

api = Api()

try:
    ep = api.show.episode_by_number(169, season=5, number=14)
    print(ep.name)     # Ozymandias
    print(ep.airdate)  # 2013-09-15
    print(ep.runtime)  # 60
except EpisodeNotFound:
    print("Episode not found")
```

--------------------------------

### Get Main Crew for a Show

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieves the main crew members for a given show ID. The result includes the crew member's type and associated person.

```python
from tvmaze.api import Api

api = Api()

crew = api.show.crew(169)
for member in crew[:3]:
    print(f"{member.type}: {member.person.name}")
```

--------------------------------

### Initializing the API Client

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

The Api class is the central entry point for the library. Instantiate it to access various resource namespaces. No authentication is required for the public TvMaze API.

```APIDOC
## Initializing the API Client

The `Api` class is the single entry point. It stores the base URL and exposes all resource namespaces as properties. No authentication is required for the public TvMaze API.

```python
from tvmaze.api import Api

api = Api()
# api.base_url == "http://api.tvmaze.com"
```
```

--------------------------------

### Initialize Tvmaze API

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Initialize the Tvmaze API client. This is the first step before making any API calls.

```python
from tvmaze.api import Api
api = Api()
```

--------------------------------

### Tvmaze API Exception Handling - Python

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Demonstrates how to handle various exceptions from the Tvmaze API, including specific `NotFound` errors, `ConnectionError`, and the generic `TvMazeException`.

```python
from tvmaze.api import Api
from tvmaze.expections import (
    TvMazeException,
    ConnectionError,
    ShowNotFound,
    EpisodeNotFound,
    PeopleNotFound,
    CharacterNotFound,
    NetworkNotFound,
    WebChannelNotFound,
)

api = Api()

# Catch a specific not-found error
try:
    show = api.show.get(999999999)
except ShowNotFound as e:
    print(f"Not found: {e}")  # Show Not Found

# Catch any connection/HTTP error
try:
    episodes = api.show.episodes(1)
except ConnectionError as e:
    print(f"Network error: {e}")

# Catch any TvMaze error generically
try:
    person = api.people.get(999999999)
except TvMazeException as e:
    print(f"TvMaze error: {e}")
```

--------------------------------

### Exception Handling

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Demonstrates how to handle various exceptions that can occur when using the TVMaze API, including resource not found errors, connection issues, and general API errors.

```APIDOC
## Exception Handling

All exceptions inherit from `TvMazeException`. Resource-specific `NotFound` subclasses are raised automatically when an API call returns a 4xx response. `ConnectionError` is raised for network-level failures.

### Request Example
```python
from tvmaze.api import Api
from tvmaze.expections import (
    TvMazeException,
    ConnectionError,
    ShowNotFound,
    EpisodeNotFound,
    PeopleNotFound,
    CharacterNotFound,
    NetworkNotFound,
    WebChannelNotFound,
)

api = Api()

# Catch a specific not-found error
try:
    show = api.show.get(999999999)
except ShowNotFound as e:
    print(f"Not found: {e}")  # Show Not Found

# Catch any connection/HTTP error
try:
    episodes = api.show.episodes(1)
except ConnectionError as e:
    print(f"Network error: {e}")

# Catch any TvMaze error generically
try:
    person = api.people.get(999999999)
except TvMazeException as e:
    print(f"TvMaze error: {e}")
```
```

--------------------------------

### api.show.list(page=0)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Fetches a paginated list of all shows from the TvMaze API. Returns a ResultSet of Show model objects, with 250 shows per page (zero-indexed).

```APIDOC
## `api.show.list(page=0)` — Paginated list of all shows

Returns a `ResultSet` of `Show` model objects for the given page (250 shows per page, zero-indexed).

```python
from tvmaze.api import Api
from tvmaze.expections import TvMazeException

api = Api()

# Fetch first page (shows 0–249)
shows = api.show.list()
for show in shows[:3]:
    print(show.name, show.id, show.status)
# Output:
# Under the Dome 1 Ended
# Person of Interest 2 Ended
# Bitten 3 Ended

# Fetch second page
shows_page2 = api.show.list(page=1)
print(len(shows_page2))  # 250
```
```

--------------------------------

### Show list

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieves a list of all shows with their primary information. Supports pagination.

```APIDOC
## Show list

### Description
A list of all shows, with all primary information included.

### Method
api.show.list(page: int = 0)

### Parameters
#### Query Parameters
- **page** (int) - Optional - The page number to retrieve. Defaults to 0.
```

--------------------------------

### api.schedule.full()

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Fetches the full future schedule of episodes across all countries. This can result in a large dataset.

```APIDOC
## api.schedule.full()

### Description
Returns a `ResultSet` of all future episodes known to TvMaze across all countries. This can be a very large response.

### Method
```python
api.schedule.full()
```

### Response
#### Success Response
- `ResultSet`: A collection of episode objects.

### Request Example
```python
from tvmaze.api import Api

api = Api()

all_upcoming = api.schedule.full()
print(f"Total upcoming episodes: {len(all_upcoming)}")
for ep in all_upcoming[:3]:
    print(ep.name, ep.airdate)
```
```

--------------------------------

### Show AKA's

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Fetches a list of aliases (AKAs) for a show. An AKA with a null country indicates the show's original country.

```APIDOC
## Show AKA's

### Description
A list of AKA's (aliases) for a show. An AKA with its country set to null indicates an AKA in the show's original country.

### Method
api.show.akas(show_id: int)

### Parameters
#### Path Parameters
- **show_id** (int) - Required - The ID of the show.
```

--------------------------------

### api.search.single_show(query)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Performs a single best-match search for a TV show by name. Returns a Show model or raises ShowNotFound.

```APIDOC
## api.search.single_show(query)

### Description
Single best-match show search. Returns exactly one `Show` model or raises `ShowNotFound` if no match exists.

### Parameters
#### Query Parameters
- **query** (string) - Required - The name of the show to search for.

### Request Example
```python
from tvmaze.api import Api
from tvmaze.expections import ShowNotFound

api = Api()

try:
    show = api.search.single_show("Succession")
    print(show.id, show.name, show.premiered)
except ShowNotFound:
    print("No exact match found")
```

### Response
#### Success Response (200)
- **Show** model.

#### Error Response
- **ShowNotFound** exception is raised if no exact match is found.
```

--------------------------------

### Fetch All Seasons for a Show

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieve all season information for a show, including season number, episode count, and premiere date.

```python
from tvmaze.api import Api

api = Api()

seasons = api.show.seasons(169)  # Breaking Bad
for season in seasons:
    print(f"Season {season.number}: {season.episodeOrder} episodes, "
          f"premiere {season.premiereDate}")
# Output:
# Season 1: 7 episodes, premiere 2008-01-20
```

--------------------------------

### api.schedule.today()

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieves the full broadcast schedule for the current day. Returns a ResultSet of Episode models.

```APIDOC
## api.schedule.today()

### Description
Today's full broadcast schedule. Returns a `ResultSet` of `Episode` models for all episodes airing today (uses the server's current date/timezone).

### Request Example
```python
from tvmaze.api import Api

api = Api()

episodes = api.schedule.today()
for ep in episodes[:5]:
    print(f"{ep.airtime} - {ep.name} (show id: {ep.show.get('id') if isinstance(ep.show, dict) else ep.show})")
```

### Response
#### Success Response (200)
- **ResultSet** of **Episode** models airing today.
```

--------------------------------

### Search for a Single Best-Match Show

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Performs a search for a single show and returns the best match. Raises `ShowNotFound` if no exact match is found. Use this when you expect a unique result.

```python
from tvmaze.api import Api
from tvmaze.expections import ShowNotFound

api = Api()

try:
    show = api.search.single_show("Succession")
    print(show.id, show.name, show.premiered)
except ShowNotFound:
    print("No exact match found")
```

--------------------------------

### Today schedule

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Fetches a list of all episodes scheduled to air today.

```APIDOC
## Today schedule

### Description
The schedule is a complete list of episodes that air today.

### Method
api.schedule.today()
```

--------------------------------

### Fetch Episodes by Date

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieve episodes that aired on a specific date for a given show ID. The date must be in ISO format.

```python
from tvmaze.api import Api

api = Api()

episodes = api.show.episodes_by_date(1, "2013-07-01")
for ep in episodes:
    print(ep.name, ep.airdate)
# Output:
# Manhunt 2013-07-01
```

--------------------------------

### Fetch Paginated List of Shows

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieve a list of shows, paginated by 250 entries per page. Access show name, ID, and status from the returned Show model objects.

```python
from tvmaze.api import Api
from tvmaze.expections import TvMazeException

api = Api()

# Fetch first page (shows 0–249)
shows = api.show.list()
for show in shows[:3]:
    print(show.name, show.id, show.status)
# Output:
# Under the Dome 1 Ended
# Person of Interest 2 Ended
# Bitten 3 Ended

# Fetch second page
shows_page2 = api.show.list(page=1)
print(len(shows_page2))  # 250
```

--------------------------------

### api.show.get_by_name(show_name)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieves a show by its name. This method delegates to `api.search.single_show()` and returns a single Show model or raises ShowNotFound if no exact match is found.

```APIDOC
## `api.show.get_by_name(show_name)` — Retrieve a show by name

Delegates to `api.search.single_show()` and returns exactly one `Show` or raises `ShowNotFound`.

```python
from tvmaze.api import Api
from tvmaze.expections import ShowNotFound

api = Api()

try:
    show = api.show.get_by_name("Breaking Bad")
    print(show.id, show.name)  # e.g. 169 Breaking Bad
except ShowNotFound:
    print("Show not found")
```
```

--------------------------------

### Fetch All Episodes for a Show

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieve all aired and upcoming episodes for a given show ID. The output includes season, episode number, name, and airdate.

```python
from tvmaze.api import Api

api = Api()

episodes = api.show.episodes(169)  # Breaking Bad
for ep in episodes[:3]:
    print(f"S{ep.season:02d}E{ep.number:02d} - {ep.name} ({ep.airdate})")
# Output:
# S01E01 - Pilot (2008-01-20)
# S01E02 - Cat's in the Bag (2008-01-27)
# S01E03 - ...and the Bag's in the River (2008-02-10)
```

--------------------------------

### Search Tvmaze Shows by Name

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Search through all shows by their name.

```python
api.search.shows("girls")
```

--------------------------------

### Show episode list

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Fetches a complete list of episodes for a given show.

```APIDOC
## Show episode list

### Description
A complete list of episodes for the given show.

### Method
api.show.episodes(show_id: int)

### Parameters
#### Path Parameters
- **show_id** (int) - Required - The ID of the show.
```

--------------------------------

### api.show.images(show_id)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieves images for a given show ID. Returns a ResultSet of Image models with type, main status, and nested resolutions.

```APIDOC
## api.show.images(show_id)

### Description
Images for a show. Returns a `ResultSet` of `Image` models with `type`, `main`, and nested `resolutions` (`Resolution` model containing `original` and `medium`).

### Parameters
#### Path Parameters
- **show_id** (int) - Required - The ID of the show.

### Request Example
```python
from tvmaze.api import Api

api = Api()
images = api.show.images(1)
for img in images[:2]:
    print(img.type, img.resolutions.original.url)
```

### Response
#### Success Response (200)
- **ResultSet** of **Image** models. Each `Image` model contains:
  - **type** (string)
  - **main** (boolean)
  - **resolutions** (`Resolution` model)
```

--------------------------------

### Search Tvmaze People by Name

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Search through all people by their name.

```python
api.search.people("lauren")
```

--------------------------------

### Schedule by country and date

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieves the schedule of episodes airing in a specific country on a given date.

```APIDOC
## Schedule by country and date

### Description
The schedule is a complete list of episodes that air in a given country on a given date.

### Method
api.schedule.filter(country_code: str, date: str)

### Parameters
#### Query Parameters
- **country_code** (str) - Required - The two-letter country code (e.g., "US").
- **date** (str) - Required - The date in YYYY-MM-DD format.
```

--------------------------------

### api.search.shows(query)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Searches for TV shows by name. Returns a ResultSet of Show models ranked by relevance.

```APIDOC
## api.search.shows(query)

### Description
Search shows by name. Returns a `ResultSet` of `Show` models ranked by relevance.

### Parameters
#### Query Parameters
- **query** (string) - Required - The name of the show to search for.

### Request Example
```python
from tvmaze.api import Api

api = Api()
results = api.search.shows("game of thrones")
for show in results[:3]:
    print(show.id, show.name, show.status)
```

### Response
#### Success Response (200)
- **ResultSet** of **Show** models.
```

--------------------------------

### api.show.get(show_id)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieves a single show by its unique ID. Returns a Show model object with all primary fields accessible as attributes.

```APIDOC
## `api.show.get(show_id)` — Retrieve a single show by ID

Returns a single `Show` model with all primary fields (name, language, genres, status, rating, network, schedule, image, externals, etc.) as attributes.

```python
from tvmaze.api import Api
from tvmaze.expections import ShowNotFound

api = Api()

try:
    show = api.show.get(1)  # "Under the Dome"
    print(show.name)          # Under the Dome
    print(show.language)      # English
    print(show.status)        # Ended
    print(show.rating.average)  # e.g. 6.5
    print(show.network.name)    # CBS
    print(show.externals.imdb)  # tt1553656
except ShowNotFound:
    print("Show not found")
```
```

--------------------------------

### api.web_channel.get(web_channel_id)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieves information about a web channel using its unique ID.

```APIDOC
## api.web_channel.get(web_channel_id)

### Description
Returns a `WebChannel` model with `name`, `officialSite`, and optional nested `country`.

### Method
```python
api.web_channel.get(web_channel_id)
```

### Parameters
#### Path Parameters
- **web_channel_id** (int) - Required - The unique identifier for the web channel.

### Response
#### Success Response
- `WebChannel` model: Contains web channel details like name, official site, and country.

### Request Example
```python
from tvmaze.api import Api
from tvmaze.expections import WebChannelNotFound

api = Api()

try:
    channel = api.web_channel.get(1)  # Netflix
    print(channel.name)
    print(channel.officialSite)
except WebChannelNotFound:
    print("Web channel not found")
```
```

--------------------------------

### Show episode by date

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Fetches all episodes for a show that aired on a specific date.

```APIDOC
## Show episode by date

### Description
Retrieve all episodes from this show that have aired on a specific date.

### Method
api.show.episodes_by_date(show_id: int, date: str)

### Parameters
#### Path Parameters
- **show_id** (int) - Required - The ID of the show.
- **date** (str) - Required - The date in YYYY-MM-DD format.
```

--------------------------------

### Filter Tvmaze Schedule by Country and Date

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieve a list of episodes airing in a specific country on a given date.

```python
api.schedule.filter(country_code="US", date="2014-12-01")
```

--------------------------------

### Search Shows by Name

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Searches for TV shows by their name and returns a ranked list of results. Useful for finding shows when you know part of the title.

```python
from tvmaze.api import Api

api = Api()

results = api.search.shows("game of thrones")
for show in results[:3]:
    print(show.id, show.name, show.status)
```

--------------------------------

### Look Up a Show by External ID

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Finds a show using its ID from an external database like IMDB, TheTVDB, or TVRage. Handles potential `ShowNotFound` exceptions.

```python
from tvmaze.api import Api
from tvmaze.expections import ShowNotFound

api = Api()

# Lookup by IMDB ID
try:
    show = api.search.lookup_show("imdb", "tt0944947")  # Game of Thrones
    print(show.name, show.id)  # Game of Thrones 82
except ShowNotFound:
    print("Show not found")

# Lookup by TheTVDB ID
show = api.search.lookup_show("thetvdb", "81189")
print(show.name)  # Breaking Bad

# Invalid option raises Exception
try:
    api.search.lookup_show("netflix", "12345")
except Exception as e:
    print(e)  # Invalid lookup option
```

--------------------------------

### api.show.episodes_by_date(show_id, date)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Fetches episodes that aired on a specific date for a given show ID. The date should be provided as an ISO-format string. Returns a ResultSet of Episode model objects.

```APIDOC
## `api.show.episodes_by_date(show_id, date)` — Episodes aired on a specific date

Returns a `ResultSet` of `Episode` models that aired on the given ISO-format date string.

```python
from tvmaze.api import Api

api = Api()

episodes = api.show.episodes_by_date(1, "2013-07-01")
for ep in episodes:
    print(ep.name, ep.airdate)
# Output:
# Manhunt 2013-07-01
```
```

--------------------------------

### Full schedule

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Fetches a list of all future episodes known to TVmaze, regardless of country.

```APIDOC
## Full schedule

### Description
The full schedule is a list of all future episodes known to TVmaze, regardless of their country.

### Method
api.schedule.full()
```

--------------------------------

### api.episode.get(episode_id)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Fetches a specific episode's details using its unique ID.

```APIDOC
## api.episode.get(episode_id)

### Description
Returns a single `Episode` model with fields including `name`, `season`, `number`, `airdate`, `airtime`, `runtime`, `summary`, and `image`.

### Method
```python
api.episode.get(episode_id)
```

### Parameters
#### Path Parameters
- **episode_id** (int) - Required - The unique identifier for the episode.

### Response
#### Success Response
- `Episode` model: Contains episode details like name, season, number, airdate, runtime, summary, and image.

### Request Example
```python
from tvmaze.api import Api
from tvmaze.expections import EpisodeNotFound

api = Api()

try:
    ep = api.episode.get(1)
    print(ep.name)
    print(ep.season)
    print(ep.number)
    print(ep.airdate)
    print(ep.runtime)
except EpisodeNotFound:
    print("Episode not found")
```
```

--------------------------------

### api.network.get(network_id)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Fetches network details using the network's unique ID.

```APIDOC
## api.network.get(network_id)

### Description
Returns a `Network` model with `name`, `officialSite`, and nested `country` (`Country` model).

### Method
```python
api.network.get(network_id)
```

### Parameters
#### Path Parameters
- **network_id** (int) - Required - The unique identifier for the network.

### Response
#### Success Response
- `Network` model: Contains network details like name, official site, and country.

### Request Example
```python
from tvmaze.api import Api
from tvmaze.expections import NetworkNotFound

api = Api()

try:
    network = api.network.get(1)  # CBS
    print(network.name)
    print(network.country.name)
    print(network.country.code)
    print(network.officialSite)
except NetworkNotFound:
    print("Network not found")
```
```

--------------------------------

### Search People by Name

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Searches for people (actors, crew) by their name and returns a ranked list of results. Includes person ID, name, and birthday.

```python
from tvmaze.api import Api

api = Api()

results = api.search.people("bryan cranston")
for person in results[:2]:
    print(person.id, person.name, person.birthday)
```

--------------------------------

### api.schedule.filter(country_code, date)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieves the broadcast schedule for a specific country and date. Returns a ResultSet of Episode models.

```APIDOC
## api.schedule.filter(country_code, date)

### Description
Schedule by country and date. Returns a `ResultSet` of `Episode` models for a specific country and date. Country codes follow ISO 3166-1 (e.g., `"US"`, `"GB"`, `"JP"`).

### Parameters
#### Query Parameters
- **country_code** (string) - Required - The ISO 3166-1 country code (e.g., `"US"`).
- **date** (string) - Required - The date in `YYYY-MM-DD` format.

### Request Example
```python
from tvmaze.api import Api

api = Api()

episodes = api.schedule.filter(country_code="US", date="2014-12-01")
for ep in episodes[:3]:
    print(f"{ep.airtime} S{ep.season:02d}E{ep.number:02d} {ep.name}")
```

### Response
#### Success Response (200)
- **ResultSet** of **Episode** models for the specified country and date.
```

--------------------------------

### api.search.people(query)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Searches for people by name. Returns a ResultSet of People models ranked by relevance.

```APIDOC
## api.search.people(query)

### Description
Search people by name. Returns a `ResultSet` of `People` models ranked by relevance.

### Parameters
#### Query Parameters
- **query** (string) - Required - The name of the person to search for.

### Request Example
```python
from tvmaze.api import Api

api = Api()

results = api.search.people("bryan cranston")
for person in results[:2]:
    print(person.id, person.name, person.birthday)
```

### Response
#### Success Response (200)
- **ResultSet** of **People** models.
```

--------------------------------

### Show seasons

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieves a complete list of seasons for a given show.

```APIDOC
## Show seasons

### Description
A complete list of seasons for the given show.

### Method
api.show.seasons(show_id: int)

### Parameters
#### Path Parameters
- **show_id** (int) - Required - The ID of the show.
```

--------------------------------

### api.show.cast(show_id)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieves the main cast for a given show ID. Returns a ResultSet of Cast models, each containing person and character details.

```APIDOC
## api.show.cast(show_id)

### Description
Main cast for a show. Returns a `ResultSet` of `Cast` models, each with a nested `person` (`Person` model) and `character` (`Character` model).

### Parameters
#### Path Parameters
- **show_id** (int) - Required - The ID of the show.

### Request Example
```python
from tvmaze.api import Api

api = Api()
cust = api.show.cast(169)  # Breaking Bad
for member in cust[:3]:
    print(f"{member.person.name} as {member.character.name}")
```

### Response
#### Success Response (200)
- **ResultSet** of **Cast** models. Each `Cast` model contains:
  - **person** (`Person` model)
  - **character** (`Character` model)
```

--------------------------------

### Show crew

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Retrieves a list of the main crew members for a show.

```APIDOC
## Show crew

### Description
A list of main crew for a show.

### Method
api.show.crew(show_id: int)

### Parameters
#### Path Parameters
- **show_id** (int) - Required - The ID of the show.
```

--------------------------------

### api.search.lookup_show(lookup_option, lookup_id)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Looks up a show using its ID on an external database. Supports TVRage, TheTVDB, and IMDB IDs.

```APIDOC
## api.search.lookup_show(lookup_option, lookup_id)

### Description
Look up a show by external ID. Looks up a show using its ID on an external database. Valid `lookup_option` values: `"tvrage"`, `"thetvdb"`, `"imdb"`.

### Parameters
#### Query Parameters
- **lookup_option** (string) - Required - The external database to use (e.g., `"tvrage"`, `"thetvdb"`, `"imdb"`).
- **lookup_id** (string) - Required - The ID of the show in the specified external database.

### Request Example
```python
from tvmaze.api import Api
from tvmaze.expections import ShowNotFound

api = Api()

# Lookup by IMDB ID
try:
    show = api.search.lookup_show("imdb", "tt0944947")  # Game of Thrones
    print(show.name, show.id)  # Game of Thrones 82
except ShowNotFound:
    print("Show not found")

# Lookup by TheTVDB ID
show = api.search.lookup_show("thetvdb", "81189")
print(show.name)  # Breaking Bad

# Invalid option raises Exception
try:
    api.search.lookup_show("netflix", "12345")
except Exception as e:
    print(e)  # Invalid lookup option
```

### Response
#### Success Response (200)
- **Show** model.

#### Error Response
- **ShowNotFound** exception is raised if the show is not found.
- **Exception** is raised for invalid `lookup_option`.
```

--------------------------------

### Show cast

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Fetches a list of the main cast members for a show.

```APIDOC
## Show cast

### Description
A list of main cast for a show.

### Method
api.show.cast(show_id: int)

### Parameters
#### Path Parameters
- **show_id** (int) - Required - The ID of the show.
```

--------------------------------

### api.show.episodes(show_id)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Fetches all episodes for a given show ID, including both aired and upcoming episodes. Returns a ResultSet of Episode model objects.

```APIDOC
## `api.show.episodes(show_id)` — All episodes for a show

Returns a `ResultSet` of `Episode` models covering all aired and upcoming episodes.

```python
from tvmaze.api import Api

api = Api()

episodes = api.show.episodes(169)  # Breaking Bad
for ep in episodes[:3]:
    print(f"S{ep.season:02d}E{ep.number:02d} - {ep.name} ({ep.airdate})")
# Output:
# S01E01 - Pilot (2008-01-20)
# S01E02 - Cat's in the Bag (2008-01-27)
# S01E03 - ...and the Bag's in the River (2008-02-10)
```
```

--------------------------------

### Search show

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Searches for shows by their name.

```APIDOC
## Search show

### Description
Search through all the shows by the show's name.

### Method
api.search.shows(query: str)

### Parameters
#### Query Parameters
- **query** (str) - Required - The name of the show to search for.
```

--------------------------------

### api.people.get(people_id)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieves detailed information about a person using their unique ID.

```APIDOC
## api.people.get(people_id)

### Description
Returns a `People` model with all primary info including `name`, `birthday`, `deathday`, `gender`, `country`, and a nested `image`.

### Method
```python
api.people.get(people_id)
```

### Parameters
#### Path Parameters
- **people_id** (int) - Required - The unique identifier for the person.

### Response
#### Success Response
- `People` model: Contains person's details like name, birthday, gender, and image.

### Request Example
```python
from tvmaze.api import Api
from tvmaze.expections import PeopleNotFound

api = Api()

try:
    person = api.people.get(5)  # Bryan Cranston
    print(person.name)
    print(person.birthday)
    print(person.gender)
    print(person.image.medium)
except PeopleNotFound:
    print("Person not found")
```
```

--------------------------------

### api.show.akas(show_id)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Retrieves alternative titles (AKAs) for a given show ID. Returns a ResultSet of Aka models, each with a name and optional country.

```APIDOC
## api.show.akas(show_id)

### Description
Aliases (AKAs) for a show. Returns a `ResultSet` of `Aka` models with `name` and optional nested `country` (`Country` model). A `null` country means the original country's title.

### Parameters
#### Path Parameters
- **show_id** (int) - Required - The ID of the show.

### Request Example
```python
from tvmaze.api import Api

api = Api()
akas = api.show.akas(1)
for aka in akas:
    country = aka.country.name if aka.country else "Original"
    print(f"{aka.name} ({country})")
```

### Response
#### Success Response (200)
- **ResultSet** of **Aka** models. Each `Aka` model contains:
  - **name** (string)
  - **country** (`Country` model) - Optional
```

--------------------------------

### Person cast credits

Source: https://github.com/yakupadakli/python-tvmaze/blob/master/README.md

Fetches all cast credits for a person at the show level.

```APIDOC
## Person cast credits

### Description
Retrieve all (show-level) cast credits for a person.

### Method
api.people.cast_credits(person_id: int)

### Parameters
#### Path Parameters
- **person_id** (int) - Required - The ID of the person.
```

--------------------------------

### api.people.cast_credits(people_id)

Source: https://context7.com/yakupadakli/python-tvmaze/llms.txt

Fetches the cast credits for a given person, including the shows they were part of and their character.

```APIDOC
## api.people.cast_credits(people_id)

### Description
Returns a `ResultSet` of `CastCredit` models, each with embedded `show` (`Show` model) and `character` (`Character` model).

### Method
```python
api.people.cast_credits(people_id)
```

### Parameters
#### Path Parameters
- **people_id** (int) - Required - The unique identifier for the person.

### Response
#### Success Response
- `ResultSet`: A collection of `CastCredit` models.
  - `show` (`Show` model): Details of the show.
  - `character` (`Character` model): Details of the character.

### Request Example
```python
from tvmaze.api import Api

api = Api()

credits = api.people.cast_credits(5)  # Bryan Cranston
for credit in credits[:3]:
    print(f"{credit.show.name} — as {credit.character.name}")
```
```
Tokens:
Raw