Services

services

TitleType

Bases: Enum

Enum for filtering titles by type in search queries.

This enum defines the valid title type filters for IMDb searches. Each member corresponds to a specific title category on IMDb.

Attributes:

Name	Type	Description
Movies	str	Movies (ft / MOVIE). Includes theatrical and made-for-TV movies.
Series	str	TV series (tv / TV). Includes serialized television programs.
Episodes	str	TV episodes (ep / TV_EPISODE). Individual episodes within a series.
Shorts	str	Short films (sh / MOVIE). Works under 40 minutes.
TvMovie	str	TV movies (tvm / TV). Films made for television.
Video	str	Video releases (v / ALL). Direct-to-video and streaming releases.

Examples:

>>> from imdbinfo import search_title, TitleType
>>> # Search for movies only
>>> results = search_title("The Matrix", title_type=TitleType.Movies)

Search for multiple types:

>>> results = search_title(
...     "Game of Thrones",
...     title_type=(TitleType.Series, TitleType.Episodes)
... )

normalize_imdb_id(imdb_id: str, locale: Optional[str] = None)

Normalize IMDb IDs to a standard 7-digit numeric format.

Accepts both prefixed (e.g., "tt0133093") and unprefixed (e.g., "0133093") IMDb IDs and returns a normalized numeric ID and language code.

Parameters:

Name	Type	Description	Default
imdb_id	str	IMDb ID with or without prefix. E.g. "tt0133093", "0133093", "nm0000206". The function strips all non-digit characters and formats the result as a 7-digit ID.	required
locale	str	Language locale code. Defaults to global locale setting (see :func:set_locale). Supported: "en", "it", "fr", "es", "de", "pt", "hi", "fr-ca", "es-es".	None

Returns:

Type	Description
tuple	A tuple of (imdb_id_numeric, language_code) where: - imdb_id_numeric is the 7-digit numeric ID (e.g., "0133093") - language_code is the URL language parameter (e.g., "", "it", "fr"). Empty string for English (default).

Examples:

>>> normalize_imdb_id("tt0133093")
('0133093', '')

>>> normalize_imdb_id("0133093")
('0133093', '')

>>> normalize_imdb_id("tt0133093", locale="it")
('0133093', 'it')

get_movie(imdb_id: str, locale: Optional[str] = None) -> Optional[MovieDetail] cached

Fetch detailed information for a movie, TV series, or episode.

Retrieves comprehensive title details including cast, crew, ratings, plot, runtime, release dates, and other metadata from IMDb.

Parameters:

Name	Type	Description	Default
imdb_id	str	IMDb title ID, with or without the tt prefix. E.g. "tt0133093" or "0133093".	required
locale	str	Language locale code. Defaults to global locale setting (see :func:set_locale). Supported: "en", "it", "fr", "es", "de", "pt", "hi", "fr-ca", "es-es".	None

Returns:

Type	Description
MovieDetail	A structured response containing title, plot, cast, ratings, runtime, release dates, and all available metadata. Check :attr:~imdbinfo.models.MovieDetail.is_series or :attr:~imdbinfo.models.MovieDetail.is_episode to determine the title kind.

Raises:

Type	Description
HTTPError	If IMDb returns a non-200 HTTP status.
WAFError	If AWS WAF blocks the request (HTTP 202). Retry later or use a different IP/proxy.
ParseError	If the HTML response lacks the __NEXT_DATA__ JSON script tag.

Notes

Results are cached with :func:functools.lru_cache (maxsize=128). To clear the cache, call get_movie.cache_clear().

Examples:

>>> from imdbinfo import get_movie
>>> movie = get_movie("tt0133093")
>>> print(movie.title)
The Matrix
>>> print(movie.rating)
8.7

Fetch a TV series and check its kind:

>>> series = get_movie("tt1520211")
>>> if series.is_series():
...     print(f"Seasons: {series.info_series.display_seasons}")

get_awards(imdb_id: str, locale: Optional[str] = None) -> List[Award] cached

Fetch awards and nominations for a title.

Retrieves all award nominations and wins for a movie, TV series, or episode, including BAFTA, Golden Globe, Oscars, and other major award ceremonies.

Parameters:

Name	Type	Description	Default
imdb_id	str	IMDb title ID, with or without the tt prefix. E.g. "tt0133093" or "0133093".	required
locale	str	Language locale code. Defaults to global locale setting (see :func:set_locale). Supported: "en", "it", "fr", "es", "de", "pt", "hi", "fr-ca", "es-es".	None

Returns:

Type	Description
List[Award]	List of :class:~imdbinfo.models.Award objects, each containing award name, nominations, and winners. Empty list if no awards are available.

Raises:

Type	Description
HTTPError	If IMDb returns a non-200 HTTP status.
WAFError	If AWS WAF blocks the request (HTTP 202). Retry later or use a different IP/proxy.
ParseError	If the HTML response lacks the __NEXT_DATA__ JSON script tag.

Notes

Results are cached with :func:functools.lru_cache (maxsize=128).

Examples:

>>> from imdbinfo import get_awards
>>> awards = get_awards("tt0111161")  # The Shawshank Redemption
>>> for award in awards:
...     print(f"{award.name}: {len(award.nominations)} nominations")

search_title(search_term: str, year: int | None = None, exact_match: bool = False, locale: Optional[str] = None, title_type: Optional[TitleFilter] = None) -> Optional[SearchResult] cached

Search for movies, TV series, episodes, and people on IMDb.

Queries IMDb's GraphQL API to find titles and people matching the search term. Supports filtering by year, exact match, and title type.

Parameters:

Name	Type	Description	Default
search_term	str	The search query. E.g. "The Matrix", "Tom Cruise".	required
year	int	Filter results to titles released in a specific year.	None
exact_match	bool	If True, match titles exactly by name. If False, allow partial/fuzzy matches.	False
locale	str	Language locale code. Defaults to global locale setting (see :func:set_locale). Supported: "en", "it", "fr", "es", "de", "pt", "hi", "fr-ca", "es-es".	None
title_type	TitleType or tuple of TitleType	Filter by title kind. E.g. TitleType.Movies, TitleType.TVSeries, or (TitleType.Movies, TitleType.TVSeries) for multiple types. See :class:~imdbinfo.services.TitleType for available filters.	None

Returns:

Type	Description
SearchResult	A :class:~imdbinfo.models.SearchResult containing two lists: titles (matching titles) and names (matching people).

Raises:

Type	Description
GraphQLError	If the GraphQL API returns an error or non-200 status.

Notes

Results are cached with :func:functools.lru_cache (maxsize=128). The API returns up to 50 results per query.

Examples:

>>> from imdbinfo import search_title, TitleType
>>> results = search_title("The Matrix", year=1999)
>>> for title in results.titles:
...     print(f"{title.imdbId}: {title.title} ({title.year})")

Search for movies only with exact match:

>>> movies = search_title(
...     "The Matrix",
...     year=1999,
...     exact_match=True,
...     title_type=TitleType.Movies,
... )
>>> print(f"Found {len(movies.titles)} result(s)")

get_name(person_id: str, locale: Optional[str] = None) -> Optional[PersonDetail] cached

Fetch detailed information for a person (actor, director, writer, etc.).

Retrieves comprehensive person details including biography, filmography, awards, birth/death dates, and career information.

Parameters:

Name	Type	Description	Default
person_id	str	IMDb person ID, with or without the nm prefix. E.g. "nm0000206" or "0000206".	required
locale	str	Language locale code. Defaults to global locale setting (see :func:set_locale). Supported: "en", "it", "fr", "es", "de", "pt", "hi", "fr-ca", "es-es".	None

Returns:

Type	Description
PersonDetail	A structured response containing person name, birth/death dates, biography, primary profession, known for titles, and other biographical data.

Raises:

Type	Description
HTTPError	If IMDb returns a non-200 HTTP status.
WAFError	If AWS WAF blocks the request (HTTP 202). Retry later or use a different IP/proxy.
ParseError	If the HTML response lacks the __NEXT_DATA__ JSON script tag.

Notes

Results are cached with :func:functools.lru_cache (maxsize=128). For full filmography, use :func:get_filmography separately.

Examples:

>>> from imdbinfo import get_name
>>> person = get_name("nm0000206")  # Keanu Reeves
>>> print(person.name)
Keanu Reeves
>>> print(person.primary_profession)
actor

get_season_episodes(imdb_id: str, season=1, locale: Optional[str] = None) -> SeasonEpisodesList cached

Fetch all episodes for a specific season of a TV series.

Parameters:

Name	Type	Description	Default
imdb_id	str	IMDb title ID, with or without the tt prefix. E.g. "tt1520211" or "1520211".	required
season	int	Season number to retrieve. E.g. 1 for season 1, 2 for season 2, etc.	1
locale	str	Language locale code. Defaults to global locale setting (see :func:set_locale). Supported: "en", "it", "fr", "es", "de", "pt", "hi", "fr-ca", "es-es".	None

Returns:

Type	Description
SeasonEpisodesList	A :class:~imdbinfo.models.SeasonEpisodesList containing list of :class:~imdbinfo.models.SeasonEpisode objects with episode details.

Raises:

Type	Description
HTTPError	If IMDb returns a non-200 HTTP status.
WAFError	If AWS WAF blocks the request (HTTP 202). Retry later or use a different IP/proxy.
ParseError	If the HTML response lacks the __NEXT_DATA__ JSON script tag.

Notes

Results are cached with :func:functools.lru_cache (maxsize=128). To get all episodes at once, use :func:get_all_episodes.

Examples:

>>> from imdbinfo import get_season_episodes
>>> episodes = get_season_episodes("tt1520211", season=1)
>>> for ep in episodes.episodes:
...     print(f"S01E{ep.episode:02d}: {ep.title}")

get_all_episodes(imdb_id: str, locale: Optional[str] = None) cached

Fetch all episodes for a TV series (across all seasons).

Retrieves the complete episode list for a series in chronological order.

Parameters:

Name	Type	Description	Default
imdb_id	str	IMDb title ID, with or without the tt prefix. E.g. "tt1520211" or "1520211".	required
locale	str	Language locale code. Defaults to global locale setting (see :func:set_locale). Supported: "en", "it", "fr", "es", "de", "pt", "hi", "fr-ca", "es-es".	None

Returns:

Type	Description
list	List of :class:~imdbinfo.models.BulkedEpisode objects, each containing episode title, number, rating, and other metadata.

Raises:

Type	Description
HTTPError	If IMDb returns a non-200 HTTP status.
WAFError	If AWS WAF blocks the request (HTTP 202). Retry later or use a different IP/proxy.
ParseError	If the HTML response lacks the __NEXT_DATA__ JSON script tag.

Notes

Results are cached with :func:functools.lru_cache (maxsize=128). For a single season, use :func:get_season_episodes instead. This function may be slower for long-running series.

Examples:

>>> from imdbinfo import get_all_episodes
>>> all_eps = get_all_episodes("tt0944947")  # Game of Thrones
>>> print(f"Total episodes: {len(all_eps)}")

get_episodes(imdb_id: str, season=1, locale: Optional[str] = None) -> SeasonEpisodesList cached

Deprecated: Use :func:get_season_episodes or :func:get_all_episodes instead.

This function is kept for backward compatibility and forwards calls to :func:get_season_episodes.

Parameters:

Name	Type	Description	Default
imdb_id	str	IMDb title ID, with or without the tt prefix.	required
season	int	Season number to retrieve.	1
locale	str	Language locale code. Defaults to global locale setting.	None

Returns:

Type	Description
SeasonEpisodesList	List of episodes for the specified season.

Warnings

This function is deprecated. Use :func:get_season_episodes for a single season or :func:get_all_episodes for all episodes instead.

get_akas(imdb_id: str, locale: Optional[str] = None) -> Union[AkasData, list]

Fetch alternative titles (AKAs) for a title in different regions and languages.

Retrieves all known alternative titles and regional releases for a title, along with country and language codes.

Parameters:

Name	Type	Description	Default
imdb_id	str	IMDb title ID, with or without the tt prefix. E.g. "tt0133093" or "0133093".	required
locale	str	Language locale code. Defaults to global locale setting (see :func:set_locale). Supported: "en", "it", "fr", "es", "de", "pt", "hi", "fr-ca", "es-es".	None

Returns:

Type	Description
AkasData or list	A :class:~imdbinfo.models.AkasData object or empty list if no AKAs are found.

Raises:

Type	Description
HTTPError	If IMDb returns a non-200 HTTP status.
WAFError	If AWS WAF blocks the request (HTTP 202). Retry later or use a different IP/proxy.
ParseError	If the HTML response lacks the __NEXT_DATA__ JSON script tag.

Examples:

>>> from imdbinfo import get_akas
>>> akas = get_akas("tt0133093")  # The Matrix
>>> for aka in akas:
...     print(f"{aka.title} ({aka.country_code})")

get_all_interests(imdb_id: str, locale: Optional[str] = None)

Fetch all interest tags and thematic topics for a title.

In the context of IMDb data, 'interests' are thematic tags, topics, or metadata associated with a title, such as genres, themes, or other descriptors beyond the standard genre classification. These are extracted from IMDb's GraphQL API.

Parameters:

Name	Type	Description	Default
imdb_id	str	IMDb title ID, with or without the tt prefix. E.g. "tt0133093" or "0133093".	required
locale	str	Language locale code. Defaults to global locale setting (see :func:set_locale). Supported: "en", "it", "fr", "es", "de", "pt", "hi", "fr-ca", "es-es".	None

Returns:

Type	Description
list	List of interest tag strings. Empty list if no interests are found.

Raises:

Type	Description
HTTPError	If IMDb returns a non-200 HTTP status.
WAFError	If AWS WAF blocks the request (HTTP 202). Retry later or use a different IP/proxy.
GraphQLError	If the GraphQL endpoint returns an error.

Notes

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 :attr:~imdbinfo.models.MovieDetail.genres.

Examples:

>>> from imdbinfo import get_all_interests
>>> interests = get_all_interests("tt0133093")  # The Matrix
>>> print(interests[:5])
['cyberpunk', 'hacker', 'action', ...]

get_trivia(imdb_id: str, locale: Optional[str] = None) -> List[Dict]

Fetch trivia facts for a title.

Retrieves interesting behind-the-scenes facts, production trivia, and user-contributed trivia about a movie or TV series.

Parameters:

Name	Type	Description	Default
imdb_id	str	IMDb title ID, with or without the tt prefix. E.g. "tt0133093" or "0133093".	required
locale	str	Language locale code. Defaults to global locale setting (see :func:set_locale). Supported: "en", "it", "fr", "es", "de", "pt", "hi", "fr-ca", "es-es".	None

Returns:

Type	Description
List[Dict]	List of trivia dictionaries containing trivia text and interest scores. Empty list if no trivia is found.

Raises:

Type	Description
HTTPError	If IMDb returns a non-200 HTTP status.
WAFError	If AWS WAF blocks the request (HTTP 202). Retry later or use a different IP/proxy.
GraphQLError	If the GraphQL endpoint returns an error.

Examples:

>>> from imdbinfo import get_trivia
>>> trivia = get_trivia("tt0111161")  # The Shawshank Redemption
>>> print(f"Found {len(trivia)} trivia facts")

get_reviews(imdb_id: str, locale: Optional[str] = None) -> List[Dict]

Fetch user reviews for a title.

Retrieves top user reviews and comments about a movie or TV series, including reviewer names, ratings, and spoiler flags.

Parameters:

Name	Type	Description	Default
imdb_id	str	IMDb title ID, with or without the tt prefix. E.g. "tt0133093" or "0133093".	required
locale	str	Language locale code. Defaults to global locale setting (see :func:set_locale). Supported: "en", "it", "fr", "es", "de", "pt", "hi", "fr-ca", "es-es".	None

Returns:

Type	Description
List[Dict]	List of review dictionaries containing reviewer name, rating, text, and spoiler flag. Empty list if no reviews are found.

Raises:

Type	Description
HTTPError	If IMDb returns a non-200 HTTP status.
WAFError	If AWS WAF blocks the request (HTTP 202). Retry later or use a different IP/proxy.
GraphQLError	If the GraphQL endpoint returns an error.

Examples:

>>> from imdbinfo import get_reviews
>>> reviews = get_reviews("tt0111161")
>>> for review in reviews:
...     print(f"By {review['author']}: {review['summary']}")

get_parental_guide(imdb_id: str, locale: Optional[str] = None) -> Dict

Fetch parental guide information for a title.

Retrieves content warnings for violence, profanity, sex, drugs, and other categories to help parents assess title suitability.

Parameters:

Name	Type	Description	Default
imdb_id	str	IMDb title ID, with or without the tt prefix. E.g. "tt0133093" or "0133093".	required
locale	str	Language locale code. Defaults to global locale setting (see :func:set_locale). Supported: "en", "it", "fr", "es", "de", "pt", "hi", "fr-ca", "es-es".	None

Returns:

Type	Description
Dict	A :class:~imdbinfo.models.ParentalGuideList object or dict with categories and content warnings. Empty dict if no parental guide is found.

Raises:

Type	Description
HTTPError	If IMDb returns a non-200 HTTP status.
WAFError	If AWS WAF blocks the request (HTTP 202). Retry later or use a different IP/proxy.
GraphQLError	If the GraphQL endpoint returns an error.

Examples:

>>> from imdbinfo import get_parental_guide
>>> guide = get_parental_guide("tt0137523")  # Fight Club
>>> for category in guide.get('categories', []):
...     print(f"{category['name']}: {category['severity']}")

get_quotes(imdb_id: str, locale: Optional[str] = None) -> List[Quote]

Fetch character quotes and dialogue from a title.

Returns a list of memorable movie or TV quotes, including speaker attribution, dialogue lines, and community interest scores.

Parameters:

Name	Type	Description	Default
imdb_id	str	IMDb title ID, with or without the tt prefix. E.g. "tt0133093" or "0133093".	required
locale	str	Language locale code. Defaults to global locale setting (see :func:set_locale). Supported: "en", "it", "fr", "es", "de", "pt", "hi", "fr-ca", "es-es".	None

Returns:

Type	Description
List[Quote]	List of :class:~imdbinfo.models.Quote objects, each containing dialogue lines, speaker attribution, and interest scores. Empty list if no quotes are found.

Raises:

Type	Description
HTTPError	If IMDb returns a non-200 HTTP status.
WAFError	If AWS WAF blocks the request (HTTP 202). Retry later or use a different IP/proxy.
GraphQLError	If the GraphQL endpoint returns an error.

Examples:

>>> from imdbinfo import get_quotes
>>> quotes = get_quotes("tt0133093")  # The Matrix
>>> for quote in quotes:
...     print(f"{quote.characters[0].character}: {quote.lines[0].text}")

get_filmography(imdb_id, locale: Optional[str] = None) -> dict

Fetch complete filmography for a person.

Retrieves all known credits for an actor, director, writer, composer, or other professional, organized by job category.

Parameters:

Name	Type	Description	Default
imdb_id	str	IMDb person ID, with or without the nm prefix. E.g. "nm0000206" or "0000206".	required
locale	str	Language locale code. Defaults to global locale setting (see :func:set_locale). Supported: "en", "it", "fr", "es", "de", "pt", "hi", "fr-ca", "es-es".	None

Returns:

Type	Description
dict	Dictionary with filmography organized by category (actor, director, writer, etc.), containing all known credits. Empty dict if no filmography is found.

Raises:

Type	Description
HTTPError	If IMDb returns a non-200 HTTP status.
WAFError	If AWS WAF blocks the request (HTTP 202). Retry later or use a different IP/proxy.
GraphQLError	If the GraphQL endpoint returns an error.

Examples:

>>> from imdbinfo import get_filmography
>>> filmography = get_filmography("nm0000206")  # Keanu Reeves
>>> print(f"Acting credits: {len(filmography.get('actor', []))}")

get_media_gallery(imdb_id: str, locale: Optional[str] = None) -> Optional[MediaGallery] cached

Fetch media gallery (images and videos) for a title.

Retrieves all available images, promotional photos, and behind-the-scenes media for a movie or TV series.

Parameters:

Name	Type	Description	Default
imdb_id	str	IMDb title ID, with or without the tt prefix. E.g. "tt0133093" or "0133093".	required
locale	str	Language locale code. Defaults to global locale setting (see :func:set_locale). Supported: "en", "it", "fr", "es", "de", "pt", "hi", "fr-ca", "es-es".	None

Returns:

Type	Description
MediaGallery or list	A :class:~imdbinfo.models.MediaGallery object containing images with URLs, captions, and metadata. Empty list if no media is found.

Raises:

Type	Description
HTTPError	If IMDb returns a non-200 HTTP status.
WAFError	If AWS WAF blocks the request (HTTP 202). Retry later or use a different IP/proxy.
GraphQLError	If the GraphQL endpoint returns an error.

Notes

Results are cached with :func:functools.lru_cache (maxsize=128).

Examples:

>>> from imdbinfo import get_media_gallery
>>> media = get_media_gallery("tt0111161")  # The Shawshank Redemption
>>> print(f"Found {len(media or [])} media items")