IMDbAPI Client¶

import asyncio
from imdbapi import IMDBAPIClient

async def main():
    async with IMDBAPIClient() as client:
        # Full-text search
        results = await client.search.titles("Inception", limit=5)
        for t in results.titles:
            print(t.primary_title, t.start_year)

        # Fetch full title record
        title = await client.titles.get("tt1375666")
        print(title.rating.aggregate_rating if title.rating else "N/A")

        # Fetch a person
        person = await client.names.get("nm0634240")
        print(person.display_name, person.primary_professions)

if __name__ == "__main__":
    asyncio.run(main())

import asyncio
from imdbapi import IMDBAPIClient

client = IMDBAPIClient()
title = asyncio.run(client.titles.get("tt0111161"))
print(title.primary_title)
asyncio.run(client.close())

from imdbapi import IMDBAPIClient
from imdbapi.models import TitleType, SortBy

class MovieService:
    def __init__(self):
        self._imdb = IMDBAPIClient(timeout=15.0, max_retries=3)

    async def startup(self):
        await self._imdb.open()

    async def shutdown(self):
        await self._imdb.close()

    async def get_top_drama_movies(self):
        return await self._imdb.titles.list(
            types=[TitleType.MOVIE],
            genres=["Drama"],
            sort_by=SortBy.USER_RATING,
            min_vote_count=10_000,
        )

from imdbapi.utils.logger import get_logger
logger = get_logger(__name__)

# Enable debug mode on the client for verbose HTTP logs:
client = IMDBAPIClient(debug=True)

async with IMDBAPIClient() as client:
    # Collect all action movies across multiple pages
    all_titles = []
    async for page in client.titles.list_pages(genres=["Action"], min_aggregate_rating=7.0):
        all_titles.extend(page.titles)

    # All StarMeter rankings
    async for page in client.charts.starmeter_pages():
        for person in page.names:
            print(person.display_name, person.meter_ranking)

    # All episodes of Breaking Bad
    async for page in client.titles.get_episodes_pages("tt0903747"):
        for ep in page.episodes:
            print(f"S{ep.season}E{ep.episode_number} — {ep.title}")

from imdbapi import IMDBAPIClient
from imdbapi.exceptions import (
    IMDBAPINotFoundError,
    IMDBAPIRateLimitError,
    IMDBAPIServerError,
    IMDBAPIConnectionError,
    IMDBAPITimeoutError,
    IMDBAPIValidationError,
)

async with IMDBAPIClient() as client:
    try:
        title = await client.titles.get("tt9999999")
    except IMDBAPINotFoundError:
        print("Title not found")
    except IMDBAPIRateLimitError:
        print("Rate limit — back off and retry")
    except IMDBAPIServerError as exc:
        print(f"Server error {exc.status_code}: {exc.message}")
    except IMDBAPIConnectionError:
        print("Network unreachable")
    except IMDBAPITimeoutError:
        print("Request timed out")
    except IMDBAPIValidationError as exc:
        print(f"Unexpected response shape: {exc}")

client = IMDBAPIClient(
    base_url="https://api.imdbapi.dev",   # override for local mock servers
    timeout=30.0,                          # total request timeout in seconds
    max_retries=3,                         # set to 1 to disable retries
    api_key="your-key-if-needed",          # optional X-API-Key header  # pragma: allowlist secret
    debug=True,                            # DEBUG-level request/response logs
)