Models¶

`models` ¶

Pydantic models for imdbinfo API responses.

This module contains all data models used to represent IMDb entities such as movies, TV series, people, episodes, awards, and metadata. All models are built with Pydantic for type safety, validation, and IDE autocompletion.

Model Hierarchy

Title Models: - :class:MovieDetail — Main response for titles (movies, series, episodes) - :class:TvSeriesDetail — Series-specific metadata - :class:TvEpisodeDetail — Episode-specific metadata - :class:MovieBriefInfo — Lightweight title metadata for search results

Person Models: - :class:Person — Basic person info (directors, cast, crew) - :class:PersonDetail — Comprehensive person biography and filmography

Search & Results: - :class:SearchResult — Combined search results (titles + people)

Metadata Models: - :class:Award — Award and nominations data - :class:Quote — Character quotes and dialogue - :class:AkaInfo / :class:AkasData — Alternative titles by region - :class:MediaGallery — Images and media items - :class:ParentalGuideList — Content warnings and ratings

Episode Collections: - :class:SeasonEpisodesList — Episodes grouped by season - :class:BulkedEpisode — Individual episode in bulk results

`Person` ¶

Bases: BaseModel

Basic information about a person (actor, director, writer, etc.).

This model represents individuals in the IMDb database with their core identifying information. It's used for cast, crew, and search results.

Attributes:

Name	Type	Description
`id`	`str`	IMDb ID without prefix (e.g., `"0000206"` for Keanu Reeves).
`imdb_id`	`str`	IMDb ID without prefix. Same as `id`.
`imdbId`	`str`	IMDb ID with `nm` prefix (e.g., `"nm0000206"`).
`name`	`str`	Person's full name.
`url`	`str`	IMDb profile URL.
`job`	`(str, optional)`	Job title or role (e.g., `"Director"`, `"Actor"`, `"Writer"`).

`InfoSeries` ¶

Bases: BaseModel

Metadata about a TV series (years, seasons, creators).

Attributes:

Name	Type	Description
`display_years`	`List[str]`	Year range for the series (e.g., `["2013", "2017"]` for 2013-2017). Empty list if not available.
`display_seasons`	`List[str]`	List of season numbers as strings (e.g., `["1", "2", "3"]`). Empty list if not available.
`creators`	`List[Person]`	List of series creators. Empty list if not available.

`get_creators() -> List[Person]` ¶

Get the list of series creators.

Returns:

Type	Description
`List[Person]`	Series creators, or empty list if none are available.

`InfoEpisode` ¶

Bases: BaseModel

Metadata about a specific TV episode.

Attributes:

Name	Type	Description
`season_n`	`(int, optional)`	Season number (1-indexed).
`episode_n`	`(int, optional)`	Episode number within the season (1-indexed).
`series_imdbId`	`(str, optional)`	IMDb ID of the parent series (with `tt` prefix).
`series_title`	`(str, optional)`	Title of the parent series in original language.
`series_title_localized`	`(str, optional)`	Title of the parent series in the requested locale.

`CastMember` ¶

Bases: Person

Cast member model for cast members in a movie. This model extends the Person model to include additional information specific to cast members. It includes the characters they played in the movie and their picture URL.

`CompanyInfo` ¶

Bases: BaseModel

CompanyInfo model for production companies and other companies involved in a movie. This model contains basic information about a company such as name, id, imdb_id, imdbId, url, attributes and countries.

`AwardInfo` ¶

Bases: BaseModel

Summary of award wins and nominations for a title.

Attributes:

Name	Type	Description
`wins`	`(int, optional)`	Total number of award wins.
`nominations`	`(int, optional)`	Total number of award nominations.
`prestigious_award`	`(dict, optional)`	Details of the most prestigious award, if any.

`Award` ¶

Bases: BaseModel

A movie or TV series award, nomination, or win.

Represents a single award entry as listed on IMDb's awards page for a title. Returned by :func:~imdbinfo.services.get_awards.

Attributes:

Name	Type	Description
`event`	`str`	Award ceremony name (e.g., `"Academy Awards, USA"`, `"Golden Globe Awards"`).
`status`	`(str, optional)`	Award status/year (e.g., `"2000 Winner"`, `"Nominee"`).
`award`	`(str, optional)`	Award name (e.g., `"Oscar"`, `"BAFTA Award"`).
`category`	`(str, optional)`	Award category (e.g., `"Best Picture"`, `"Best Director"`).
`nominees`	`(str, optional)`	Nominees or honorees associated with this award.

Examples:

>>> from imdbinfo import get_awards
>>> awards = get_awards("tt0111161")  # The Shawshank Redemption
>>> for award in awards[:3]:
...     print(f"{award.event}: {award.award} ({award.category})")
...     print(f"  Status: {award.status}")

`MovieDetail` ¶

Bases: SeriesMixin, BaseModel

Comprehensive details for a movie, TV series, or episode.

This is the main response model returned by :func:~imdbinfo.services.get_movie. It contains all available IMDb metadata for a title including basic info, cast, crew, ratings, release information, production details, and technical specifications.

Use :meth:is_series and :meth:is_episode to determine the title type before accessing type-specific fields like info_series or info_episode.

Attributes:

Name	Type	Description
`id`	`str`	IMDb title ID without `tt` prefix (e.g., `"0133093"`).
`imdb_id`	`str`	IMDb title ID without `tt` prefix. Same as `id`.
`imdbId`	`str`	IMDb title ID with `tt` prefix (e.g., `"tt0133093"`).
`title`	`str`	Primary title in original language.
`title_localized`	`(str, optional)`	Title in the requested locale language.
`title_akas`	`List[str]`	Alternative titles by region and language.
`kind`	`(str, optional)`	Title type (`"movie"`, `"tvSeries"`, `"tvEpisode"`, etc.).
`url`	`str`	IMDb title URL.
`cover_url`	`(str, optional)`	URL of the primary poster/cover image.
`plot`	`(str, optional)`	Plot summary or synopsis.
`release_date`	`(str, optional)`	Release date in ISO format (`YYYY-MM-DD`).
`languages`	`List[str]`	List of language codes (e.g., `["en", "fr"]`).
`certificates`	`Dict[str, Tuple[str, str]]`	Parental ratings by country (e.g., `{"US": ("PG-13", "description")}`)
`directors`	`List[Person]`	List of film directors.
`stars`	`List[Person]`	List of main cast members.
`year`	`(int, optional)`	Release year.
`year_end`	`(int, optional)`	End year (for TV series).
`duration`	`(int, optional)`	Runtime in minutes.
`rating`	`(float, optional)`	IMDb rating (0-10).
`votes`	`(int, optional)`	Number of user votes.
`info_series`	`(InfoSeries, optional)`	Series-specific metadata. Present only if `is_series()` returns `True`.
`info_episode`	`(InfoEpisode, optional)`	Episode-specific metadata. Present only if `is_episode()` returns `True`.

`TvSeriesDetail` ¶

Bases: MovieDetail

Details for a TV series (inherits from MovieDetail).

Contains series-specific metadata such as creators, seasons, and year range.

Attributes:

Name	Type	Description
`info_series`	`(InfoSeries, optional)`	Series metadata including display years, seasons, and creators.

`TvEpisodeDetail` ¶

Bases: MovieDetail

Details for a TV episode (inherits from MovieDetail).

Contains episode-specific metadata such as season number, episode number, and parent series information.

Attributes:

Name	Type	Description
`info_episode`	`(InfoEpisode, optional)`	Episode metadata including season, episode number, and series reference.

`MovieBriefInfo` ¶

Bases: SeriesMixin, BaseModel

Lightweight title metadata for search results and filmography.

Used in search results and as part of a person's filmography. Contains basic title info: name, year, rating, and IMDb ID.

Attributes:

Name	Type	Description
`id`	`str`	IMDb title ID without `tt` prefix (e.g., `"0133093"`).
`imdb_id`	`str`	IMDb title ID without `tt` prefix. Same as `id`.
`imdbId`	`str`	IMDb title ID with `tt` prefix (e.g., `"tt0133093"`).
`title`	`str`	Title in original language.
`title_localized`	`str`	Title in the requested locale.
`cover_url`	`(str, optional)`	URL of the poster image.
`url`	`(str, optional)`	IMDb title URL.
`year`	`(int, optional)`	Release year.
`kind`	`(str, optional)`	Title type (`"movie"`, `"tvSeries"`, `"tvEpisode"`, etc.).
`rating`	`(float, optional)`	IMDb rating (0-10).

`SearchResult` ¶

Bases: BaseModel

Results from a title/person search query.

Returned by :func:~imdbinfo.services.search_title. Contains both title matches and people matches in separate lists.

Attributes:

Name	Type	Description
`titles`	`List[MovieBriefInfo]`	Matching movie, TV series, and episode titles.
`names`	`List[Person]`	Matching people (actors, directors, writers, etc.).

Examples:

>>> from imdbinfo import search_title
>>> results = search_title("The Matrix", year=1999)
>>> print(f"Found {len(results.titles)} titles and {len(results.names)} people")
>>> for title in results.titles:
...     print(f"  {title.title} ({title.year})")

`PersonDetail` ¶

Bases: BaseModel

Comprehensive biography and filmography for a person.

Returned by :func:~imdbinfo.services.get_name. Contains personal biography, career information, and complete filmography across all job categories.

Attributes:

Name	Type	Description
`id`	`str`	IMDb person ID without `nm` prefix (e.g., `"0000206"`).
`imdb_id`	`str`	IMDb person ID without `nm` prefix. Same as `id`.
`imdbId`	`str`	IMDb person ID with `nm` prefix (e.g., `"nm0000206"`).
`name`	`str`	Person's full name.
`url`	`str`	IMDb profile URL.
`knownfor`	`List[str]`	List of titles the person is best known for (as titles).
`image_url`	`(str, optional)`	URL of the person's profile photo.
`bio`	`(str, optional)`	Biography or summary.
`height`	`(str, optional)`	Physical height.
`primary_profession`	`List[str]`	Primary job categories (e.g., `["actor", "producer"]`).
`birth_date`	`(str, optional)`	Birth date (ISO format: `YYYY-MM-DD`).
`birth_place`	`(str, optional)`	Birth location.
`death_date`	`(str, optional)`	Death date (ISO format: `YYYY-MM-DD`).
`death_place`	`(str, optional)`	Death location.
`death_reason`	`(str, optional)`	Cause of death.
`jobs`	`List[str]`	Complete list of job titles/professions.
`credits`	`Dict[str, List[MovieBriefInfo]]`	Filmography by job category (e.g., `{"actor": [...], "director": [...]}`)
`unreleased_credits`	`Dict[str, List[MovieBriefInfo]]`	Unreleased/upcoming projects by job category.

Examples:

>>> from imdbinfo import get_name
>>> person = get_name("nm0000206")  # Keanu Reeves
>>> print(person.name)
Keanu Reeves
>>> print(f"Known for: {', '.join(person.knownfor[:3])}")
>>> for category, titles in person.credits.items():
...     print(f"{category.title()}: {len(titles)} titles")

`SeasonEpisode` ¶

Bases: BaseModel

`from_episode_data(data: dict) -> SeasonEpisode` `classmethod` ¶

Create a SeasonEpisode instance from episode data dictionary.

`BulkedEpisode` ¶

Bases: BaseModel

`from_bulked_episode_data(data: dict) -> BulkedEpisode` `classmethod` ¶

Create an EpisodeData instance from bulked episode data dictionary. This is used when fetching episodes in bulk from a series.

`SeasonEpisodesList` ¶

Bases: BaseModel

EpisodesList model for a list of episodes. This model contains a list of EpisodeInfo objects representing the episodes of a series. It can be used to represent the episodes of a series in a specific season.

`count: int` `property` ¶

Count the number of episodes in the list. Returns: int: The number of episodes in the list.

`AkaInfo` ¶

Bases: BaseModel

`AkasData` ¶

Bases: BaseModel

`ParentalGuideContentDescription` ¶

Bases: BaseModel

`ParentalGuideCategory` ¶

Bases: BaseModel

`has_category_texts() -> bool` ¶

Return True if there are any guide items in this category.

`category_texts_list(spoiler=False) -> List[str]` ¶

Return a list of texts from the guide items.

`ParentalGuideList` ¶

Bases: BaseModel

`summary: dict[str, str]` `property` ¶

Return the list of parental guide categories.

`MediaItem` ¶

Bases: BaseModel

`MediaGallery` ¶

Bases: BaseModel

`InterestScore` ¶

Bases: BaseModel

Community interest and voting counts for a quote or trivia item.

Fields: users_interested (int): Number of users who marked this item as interesting. users_voted (int): Total number of users who voted on this item.

`QuoteCharacter` ¶

Bases: BaseModel

A character speaker attributed to a line in a quote.

Represents the actor/character speaking a line in a movie quote. May be linked to an IMDb person page or be unattributed.

Attributes:

Name	Type	Description
`character`	`(str, optional)`	Character name as shown on IMDb (e.g., `"Neo"`).
`id`	`(str, optional)`	IMDb person ID without `nm` prefix (e.g., `"0000206"`). `None` if speaker has no linked IMDb person page.
`imdb_id`	`(str, optional)`	Alias of `id`.
`imdbId`	`(str, optional)`	IMDb person ID with `nm` prefix (e.g., `"nm0000206"`).

`QuoteLine` ¶

Bases: BaseModel

A single line of dialogue within a quote exchange.

Represents one speaker's contribution to a multi-line quote.

Attributes:

Name	Type	Description
`characters`	`List[QuoteCharacter]`	Speaker(s) attributed to this line.
`text`	`(str, optional)`	The spoken dialogue text.
`stage_direction`	`(str, optional)`	Stage direction or action note (e.g., `"[enters stage]"`).

`speaker_names: List[str]` `property` ¶

Get list of character names speaking this line.

Returns:

Type	Description
`List[str]`	Character names from all speakers in this line.

`Quote` ¶

Bases: BaseModel

A memorable quote or dialogue exchange from a movie or TV series.

Returned by :func:~imdbinfo.services.get_quotes. Each quote contains one or more dialogue lines exchanged between characters, plus community voting data.

Attributes:

Name	Type	Description
`id`	`str`	IMDb quote ID (e.g., `"qt0324252"`).
`lines`	`List[QuoteLine]`	Ordered list of dialogue lines in the exchange.
`interest_score`	`InterestScore`	Community engagement metrics (votes, interest count).

Examples:

>>> from imdbinfo import get_quotes
>>> quotes = get_quotes("tt0133093")  # The Matrix
>>> for quote in quotes[:3]:
...     print(f"Quote {quote.id}:")
...     print(f"  Speakers: {', '.join(quote.speakers)}")
...     for line in quote.lines:
...         print(f"    {line}")

`speakers: List[str]` `property` ¶

Get deduplicated list of all character names in this quote.

Returns:

Type	Description
`List[str]`	Unique character names who speak in this quote.

Models¶

models ¶

Person ¶

InfoSeries ¶

get_creators() -> List[Person] ¶

InfoEpisode ¶

CastMember ¶

CompanyInfo ¶

AwardInfo ¶

Award ¶

MovieDetail ¶

TvSeriesDetail ¶

TvEpisodeDetail ¶

MovieBriefInfo ¶

SearchResult ¶

PersonDetail ¶

SeasonEpisode ¶

from_episode_data(data: dict) -> SeasonEpisode classmethod ¶

BulkedEpisode ¶

from_bulked_episode_data(data: dict) -> BulkedEpisode classmethod ¶

SeasonEpisodesList ¶

count: int property ¶

AkaInfo ¶

AkasData ¶

ParentalGuideContentDescription ¶

ParentalGuideCategory ¶

has_category_texts() -> bool ¶

category_texts_list(spoiler=False) -> List[str] ¶

ParentalGuideList ¶

summary: dict[str, str] property ¶

MediaItem ¶

MediaGallery ¶

InterestScore ¶

QuoteCharacter ¶

QuoteLine ¶

speaker_names: List[str] property ¶

Quote ¶

speakers: List[str] property ¶

`models` ¶

`Person` ¶

`InfoSeries` ¶

`get_creators() -> List[Person]` ¶

`InfoEpisode` ¶

`CastMember` ¶

`CompanyInfo` ¶

`AwardInfo` ¶

`Award` ¶

`MovieDetail` ¶

`TvSeriesDetail` ¶

`TvEpisodeDetail` ¶

`MovieBriefInfo` ¶

`SearchResult` ¶

`PersonDetail` ¶

`SeasonEpisode` ¶

`from_episode_data(data: dict) -> SeasonEpisode` `classmethod` ¶

`BulkedEpisode` ¶

`from_bulked_episode_data(data: dict) -> BulkedEpisode` `classmethod` ¶

`SeasonEpisodesList` ¶

`count: int` `property` ¶

`AkaInfo` ¶

`AkasData` ¶

`ParentalGuideContentDescription` ¶

`ParentalGuideCategory` ¶

`has_category_texts() -> bool` ¶

`category_texts_list(spoiler=False) -> List[str]` ¶

`ParentalGuideList` ¶

`summary: dict[str, str]` `property` ¶

`MediaItem` ¶

`MediaGallery` ¶

`InterestScore` ¶

`QuoteCharacter` ¶

`QuoteLine` ¶

`speaker_names: List[str]` `property` ¶

`Quote` ¶

`speakers: List[str]` `property` ¶