API Reference

Functions

class imdbio.services.TitleType(*values)

Bases: Enum

Defines the valid ‘ttype’ filters for title searches on IMDb. The values correspond to the URL parameter used in search queries.

Movies = 'ft'

Series = 'tv'

Episodes = 'ep'

Shorts = 'sh'

TvMovie = 'tvm'

Video = 'v'

imdbio.services.normalize_imdb_id(imdb_id, locale=None)

imdbio.services.get_cookies(text, user_agent, force=False)

imdbio.services.request_json_url(url)

Return type:

Any

imdbio.services.request_handler(url)

Return type:

Any

imdbio.services.request_graphql_url(headers, search_term, payload, url)

Return type:

Any

imdbio.services.get_movie(imdb_id, locale=None)

Fetch movie details from IMDb using the provided IMDb ID as string, preserve the ‘tt’ prefix or not, it will be stripped in the function.

Return type:

Optional[MovieDetail]

imdbio.services.search_title(search_term, year=None, exact_match=False, locale=None, title_type=None)

Return type:

Optional[SearchResult]

imdbio.services.get_name(person_id, locale=None)

Fetch person details from IMDb using the provided IMDb ID. Preserve the ‘nm’ prefix or not, it will be stripped in the function.

Return type:

Optional[PersonDetail]

imdbio.services.get_season_episodes(imdb_id, season=1, locale=None)

Fetch episodes for a movie or series using the provided IMDb ID.

Return type:

SeasonEpisodesList

imdbio.services.get_all_episodes(imdb_id, locale=None)

imdbio.services.get_episodes(imdb_id, season=1, locale=None)

wrap until deprecation : use get_season_episodes instead for seasons or get_all_episodes for all episodes

Return type:

SeasonEpisodesList

imdbio.services.get_akas(imdb_id, locale=None)

Return type:

Union[AkasData, list]

imdbio.services.get_all_interests(imdb_id, locale=None)

Fetch all ‘interests’ for a title using the provided IMDb ID.

In the context of IMDb data, ‘interests’ are thematic tags, topics, or metadata associated with a title, such as genres, themes, or other descriptors that go beyond the standard genre classification. These interests are extracted from the extended title information returned by IMDb’s GraphQL API.

Note: This function makes an additional request to IMDb’s GraphQL endpoint, which may be slower and more resource-intensive than standard API calls. Use this function only if you require interests beyond what is available in movie.genres, as it can impact performance.

imdbio.services.get_trivia(imdb_id, locale=None)

Return type:

List[Dict]

imdbio.services.get_reviews(imdb_id, locale=None)

Return type:

List[Dict]

imdbio.services.get_parental_guide(imdb_id, locale=None)

Return type:

Dict

imdbio.services.get_media_gallery(imdb_id, locale=None)

Return type:

TitleMediaGallery

imdbio.services.get_filmography(imdb_id, locale=None)

Fetch full filmography for a person using the provided IMDb ID.

Return type:

dict

Models

class imdbio.models.Person(**data)

Bases: BaseModel

person model for directors, cast and search results. This model is used to represent a person in the IMDb database. It can be used for directors, cast members and search results. It contains the basic information about a person such as name, id, imdb_id, imdbId, url and job.

id: str

imdb_id: str

imdbId: str

name: str

url: str

job: str | None

classmethod from_directors(data)

classmethod from_creators(data)

classmethod from_cast(data)

classmethod from_search(data)

classmethod from_category(data)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.TitleMediaItem(**data)

Bases: BaseModel

id: str

url: str

caption: str | None

width: int | None

height: int | None

type: str | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.TitleMediaGallery(**data)

Bases: BaseModel

total: int

items: List[TitleMediaItem]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.SeriesMixin

Bases: object

is_series()

Check if this movie title is a series, the main title of a series. If True, it means that this is a series, not a movie, not an episode, but the main reference for the series itself, and series details can be found in the self.info_series property.

Return type:

bool

is_episode()

Check if this movie title is an episode of a series. If True, means that this is the episode of a series and episode details can be found in the self.info_episode property

Return type:

bool

class imdbio.models.InfoSeries(**data)

Bases: BaseModel

display_years: List[str]

display_seasons: List[str]

creators: List[Person]

classmethod filter_years(value)

get_creators()

Return type:

List[Person]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.InfoEpisode(**data)

Bases: BaseModel

season_n: int | None

episode_n: int | None

series_imdbId: str | None

series_title: str | None

series_title_localized: str | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.CastMember(**data)

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.

characters: List[str]

picture_url: str | None

attributes: str | None

classmethod from_cast(data)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.CompanyInfo(**data)

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.

id: str

imdb_id: str

imdbId: str

name: str

url: str

attributes: List[str] | None

countries: List[str] | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.AwardInfo(**data)

Bases: BaseModel

Model to group award-related counts for a title.

Fields:

wins (Optional[int]): Number of wins. nominations (Optional[int]): Number of nominations. prestigious_award (Optional[dict]): Details of a prestigious award, if any.

wins: int | None

nominations: int | None

prestigious_award: dict | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.MovieDetail(**data)

Bases: SeriesMixin, BaseModel

MovieDetail model for detailed information about a movie. This model contains all the information about a movie such as title, id, imdb_id, imdbId, url, cover_url, plot, release_date, languages, certificates, directors, stars, year, duration, country_codes, rating, metacritic_rating, votes, trailers, genres, interests, worldwide_gross, production_budget, storyline_keywords, filming_locations, sound_mixes, processes, printed_formats, negative_formats, laboratories, colorations, cameras, aspect_ratios, summaries, synopses, production and categories. It also includes a field_validator to ensure that certain fields are lists and not None.

id: str

imdb_id: str

imdbId: str

title: str

title_localized: str | None

title_akas: List[str]

kind: str | None

url: str

cover_url: str | None

plot: str | None

release_date: str | None

languages: List[str]

languages_text: List[str]

certificates: Dict[str, Tuple[str, str]]

certificate: str | None

mpaa: str | None

directors: List[Person]

stars: List[Person]

year: int | None

year_end: int | None

duration: int | None

country_codes: List[str]

countries: List[str]

rating: float | None

metacritic_rating: int | None

votes: int | None

awards: AwardInfo | None

trailers: List[str]

genres: List[str]

interests: List[str]

worldwide_gross: str | None

production_budget: str | None

storyline_keywords: List[str]

filming_locations: List[str]

sound_mixes: List[str]

processes: List[str]

printed_formats: List[str]

negative_formats: List[str]

laboratories: List[str]

colorations: List[str]

cameras: List[str]

aspect_ratios: List[Tuple[str | None, str | None]]

summaries: List[str]

synopses: List[str]

production: List[str]

categories: Dict[str, List[Person | CastMember]]

company_credits: Dict[str, List[CompanyInfo]]

release_country: str | None

release_country_code: str | None

box_office: Dict[str, str | None] | None

classmethod none_is_list(value)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.TvSeriesDetail(**data)

Bases: MovieDetail

info_series: InfoSeries | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.TvEpisodeDetail(**data)

Bases: MovieDetail

info_episode: InfoEpisode | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.MovieBriefInfo(**data)

Bases: SeriesMixin, BaseModel

MovieBriefInfo model for search results and cast members. This model is used to represent a movie in search results and cast members. It contains basic information about a movie such as title, id, imdb_id, imdbId, url, cover_url, year, rating and kind. It can be used to represent a movie in search results or as part of a cast member’s credits. It includes class methods to create an instance from search results and cast data.

id: str

imdb_id: str

imdbId: str

title: str

title_localized: str

cover_url: str | None

url: str | None

year: int | None

kind: str | None

rating: float | None

classmethod from_movie_search(data)

classmethod from_filmography(data)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.SearchResult(**data)

Bases: BaseModel

SearchResult model for search results. This model contains the results of a search query, including a list of titles and names. It is used to represent the results of a search query for movies and people. It includes a list of MovieBriefInfo objects for titles and a list of Person objects for names.

titles: List[MovieBriefInfo]

names: List[Person]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.PersonDetail(**data)

Bases: BaseModel

PersonDetail model for detailed information about a person. This model contains all the information about a person such as id, imdb_id, imdbId, name, url, knownfor, image_url, bio, height, primary_profession, birth_date, birth_place, death_date, death_place, jobs, credits and unreleased_credits.

id: str

imdb_id: str

imdbId: str

name: str

url: str

knownfor: List[str]

image_url: str | None

bio: str | None

height: str | None

primary_profession: List[str]

birth_date: str | None

birth_place: str | None

death_date: str | None

death_place: str | None

death_reason: str | None

jobs: List[str]

credits: Dict[str, List[MovieBriefInfo]]

unreleased_credits: Dict[str, List[MovieBriefInfo]]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.SeasonEpisode(**data)

Bases: BaseModel

id: str

imdbId: str

imdb_id: str

title: str

season: int

episode: int

plot: str

image_url: str | None

rating: float | None

votes: int | None

year: int | None

release_date: str | None

kind: str | None

classmethod from_episode_data(data)

Create a SeasonEpisode instance from episode data dictionary.

Return type:

SeasonEpisode

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.BulkedEpisode(**data)

Bases: BaseModel

id: str

imdbId: str

imdb_id: str

season_number: int | None

episode_number: int | None

title: str

plot: str

image_url: str | None

rating: float | None

votes: int | None

year: int | None

release_date: str | None

kind: str | None

genres: List[str] | None

duration: int | None

classmethod from_bulked_episode_data(data)

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

Return type:

BulkedEpisode

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.SeasonEpisodesList(**data)

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.

series_imdbId: str

season_number: int

top_rating_episode: float | None

total_series_episodes: int | None

total_series_seasons: int | None

top_ten_episodes: List[dict] | None

episodes: List[SeasonEpisode]

property count: int

Count the number of episodes in the list. :returns: int – The number of episodes in the list.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.AkaInfo(**data)

Bases: BaseModel

title: str

country_code: str

country_name: str

language_code: str | None

language_name: str | None

classmethod from_data(title, country_code, country_name, language_code=None, language_name=None)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.AkasData(**data)

Bases: BaseModel

imdbId: str

akas: List[AkaInfo]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.ParentalGuideContentDescription(**data)

Bases: BaseModel

is_spoiler: bool

text: str

classmethod from_node(node)

Return type:

ParentalGuideContentDescription

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.ParentalGuideCategory(**data)

Bases: BaseModel

id: str

text: str

content_descriptions: List[ParentalGuideContentDescription]

severity: str

classmethod from_edge(edge)

Return type:

ParentalGuideCategory

has_category_texts()

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

Return type:

bool

category_texts_list(spoiler=False)

Return a list of texts from the guide items.

Return type:

List[str]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class imdbio.models.ParentalGuideList(**data)

Bases: BaseModel

categories: List[ParentalGuideCategory]

classmethod from_raw(parental_guide)

Return type:

Optional[ParentalGuideList]

property summary: dict[str, str]

Return the list of parental guide categories.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Exceptions

imdbio exception hierarchy

ImdbioError ├── HTTPError — any non-200 HTTP response (status_code, url, response_text) │ └── WAFError — HTTP 202 from AWS WAF enforcement ├── GraphQLError — non-200 or {“errors”: …} from the GraphQL endpoint └── ParseError — __NEXT_DATA__ script not found in HTML response

exception imdbio.exceptions.ImdbioError

Bases: Exception

Base class for all imdbio exceptions.

exception imdbio.exceptions.HTTPError(message, status_code, url, response_text='')

Bases: ImdbioError

Raised when the IMDb HTML endpoint returns a non-200 status code.

status_code

The HTTP status code returned by the server.

Type:

int

url

The full URL that was requested.

Type:

str

response_text

The first 500 characters of the response body (may be empty).

Type:

str

exception imdbio.exceptions.WAFError(message, status_code, url, response_text='')

Bases: HTTPError

Raised when AWS WAF returns HTTP 202, blocking the request.

This is a subclass of HTTPError so callers that catch HTTPError will also catch WAFError. Callers that want to handle WAF enforcement specifically (e.g. to rotate proxies or back off) can catch WAFError directly.

status_code

Always 202 for WAF-blocked responses.

Type:

int

url

The full URL that was blocked.

Type:

str

response_text

The first 500 characters of the WAF challenge response body.

Type:

str

exception imdbio.exceptions.GraphQLError(message, url, query_term, status_code=None, errors=None, response_text='')

Bases: ImdbioError

Raised when the IMDb GraphQL API returns a non-200 status or an {"errors": […]} payload.

url

The GraphQL endpoint URL.

Type:

str

query_term

The search term / entity ID used in the query.

Type:

str

status_code

HTTP status code when the failure is transport-level; None when the response was 200 but contained GraphQL errors.

Type:

Optional[int]

errors

Parsed GraphQL error objects from the response body (empty list for transport-level failures).

Type:

List[Dict[str, Any]]

response_text

First 500 characters of the raw response body.

Type:

str

exception imdbio.exceptions.ParseError(message, url='')

Bases: ImdbioError

Raised when the expected __NEXT_DATA__ JSON script tag is absent from the IMDb HTML response.

url

The URL whose response could not be parsed.

Type:

str

Proxy

imdbio.proxy.set_proxy(proxy_url)

Set (or clear) the global proxy used for all imdbio requests.

Parameters:

proxy_url – A proxy URL such as "http://user:pass@host:port". Supported schemes are http, https, socks4, socks5 and socks5h. Pass None to disable proxying.

Raises:

ValueError – If proxy_url is not None and is not a valid proxy URL.

Return type:

None

imdbio.proxy.get_proxy()

Return the currently configured proxy URL, or None if unset.

Return type:

Optional[str]

imdbio.proxy.get_proxies()

Return a proxies mapping suitable for niquests / curl_cffi.

Returns None when no proxy is configured, so callers can pass the result straight through as proxies=... without changing behaviour.

Return type:

Optional[Dict[str, str]]

Locale

imdbio.locale.set_locale(locale)

imdbio.locale.get_locale()