{"id":36845419,"url":"https://github.com/tveronesi/imdbinfo","last_synced_at":"2026-05-24T12:02:24.849Z","repository":{"id":302795497,"uuid":"1013647548","full_name":"tveronesi/imdbinfo","owner":"tveronesi","description":"A Python package to fetch and manage IMDb movie information easily.","archived":false,"fork":false,"pushed_at":"2026-01-10T10:56:59.000Z","size":1126,"stargazers_count":45,"open_issues_count":7,"forks_count":13,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-11T03:30:07.650Z","etag":null,"topics":["imdb","imdb-scrap","movie-library"],"latest_commit_sha":null,"homepage":"https://tveronesi.github.io/imdbinfo/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tveronesi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-04T08:35:19.000Z","updated_at":"2026-01-10T10:56:34.000Z","dependencies_parsed_at":"2025-08-05T13:06:25.892Z","dependency_job_id":"62098ccc-65f7-4f8d-ac4d-44d46251205e","html_url":"https://github.com/tveronesi/imdbinfo","commit_stats":null,"previous_names":["tveronesi/imdbinfo"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/tveronesi/imdbinfo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tveronesi%2Fimdbinfo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tveronesi%2Fimdbinfo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tveronesi%2Fimdbinfo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tveronesi%2Fimdbinfo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tveronesi","download_url":"https://codeload.github.com/tveronesi/imdbinfo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tveronesi%2Fimdbinfo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28340400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T12:22:26.515Z","status":"ssl_error","status_checked_at":"2026-01-12T12:22:10.856Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["imdb","imdb-scrap","movie-library"],"created_at":"2026-01-12T14:32:21.992Z","updated_at":"2026-05-24T12:02:24.834Z","avatar_url":"https://github.com/tveronesi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![PyPI Downloads](https://static.pepy.tech/badge/imdbinfo)](https://pepy.tech/projects/imdbinfo)\n[![PyPI Version](https://img.shields.io/pypi/v/imdbinfo?style=flat-square)](https://pypi.org/project/imdbinfo/)\n[![Build Status](https://github.com/tveronesi/imdbinfo/actions/workflows/pypi-publish.yml/badge.svg)](https://github.com/tveronesi/imdbinfo/actions/workflows/pypi-publish.yml)\n[![Python Versions](https://img.shields.io/pypi/pyversions/imdbinfo?style=flat-square)](https://pypi.org/project/imdbinfo/)\n\n[//]: # (![PyPI - Daily Downloads]\u0026#40;https://img.shields.io/pypi/dm/your-package-name?label=PyPI%20downloads\u0026logo=pypi\u0026#41;)\n\n# imdbinfo\n\n**Your personal gateway to IMDb data**. Search for movies, series and people and get structured information in seconds.\n\n## Features\n\n- 🔍 **Search movies, series, miniseries and people** by name or title\n- 🎬 **Detailed movie info** including cast, crew, ratings and more\n- 👥 **Detailed person info** with biography, filmography and images\n- 📺 **TV series and miniseries** support with seasons and episodes\n- 🌐 **Localized results** in multiple languages (set globally or per request)\n- 📅 **Release dates** and **box office** information\n- 🌍 **International titles** and **alternate titles (AKAs)** via `get_akas`\n- 📸 **Poster images** and **backdrops**\n- 📊 **Ratings** from IMDb and other sources\n- 📝 **User reviews and ratings** via `get_reviews`\n- 🎭 **Movie trivia and interesting facts** via `get_trivia`\n- 🗂️ **Full filmography** for actors, directors and writers via `get_filmography`\n- 🛡️ **Parental guide** including content advisories via `get_parental_guide`\n- 📝 **Typed Pydantic models** for predictable responses\n- ⚡ **Built-in caching** for faster repeated requests\n- 🛡️**AWS WAF** solver in CPython for better performance\n- ✅ **No API keys required**\n\n## Installation\n\n```bash\npip install imdbinfo\n```\n\n## Quick Start\n\n```python\nfrom imdbinfo import search_title, get_movie, get_name, get_season_episodes, get_reviews, get_trivia\n\n# Search for a title\nresults = search_title(\"The Matrix\")\nfor movie in results.titles:\n    print(f\"{movie.title} ({movie.year}) - Rating: {movie.rating} - {movie.imdb_id}\")\n\n# Get movie details\nmovie = get_movie(\"0133093\")  # or 'tt0133093'\nprint(movie.title, movie.year, movie.rating)\n\n# Get movie kind:\nprint(movie.kind)  # movie, tvSeries, tvMiniSeries, tvMovie, tvEpisode, tvSpecial, tvShort, short, videoGame, video, musicVideo, podcastEpisode, podcastSeries\nprint(movie.is_series())  # False\n\n# Get person details\nperson = get_name(\"nm0000206\")  # or '0000206' \nprint(person.name, person.birth_date)\n```\n#### Working with Series and Episodes\n\nThe `movie` object provides helpful methods to identify its type:\n\n- `movie.is_series()` — Returns `True` if the movie is a series.\n- `movie.is_episode()` — Returns `True` if the movie is an episode.\n\nDepending on the type, you can access additional information:\n\n- For series: use `movie.info_series` to get series details (creators, seasons, episodes, ...)\n- For episodes: use `movie.info_episode` to get episode details \n\n#### Example: Working with Series and Episodes\n\n```python\nfrom imdbinfo import get_movie, get_season_episodes\n\n# Fetch a TV series as a Movie object\nwalking_dead_serie = get_movie(\"tt1520211\")  # Walking Dead\n\n# Check if the object is a series\nprint(walking_dead_serie.is_series())  # True\n\n# Access series-specific information\nprint(f\"Series Info: {walking_dead_serie.info_series}\")\n\n# Retrieve episodes for the series season 1\nwalking_dead_episodes = get_season_episodes(walking_dead_serie.imdb_id, season=1)\n\n# Print details for the first 3 episodes from the season 1\nfor episode_info in walking_dead_episodes[:3]:\n    print(episode_info)\n\n# Fetch a single episode as a Movie object and check its type\nepisode_detail = get_movie(episode_info.imdb_id)\nprint(\"Is Episode:\", episode_detail.is_episode())  # True\n\n# Access episode-specific information: series imdbid, season and episode number ...\nprint(f\"Episode Info: {episode_detail.info_episode}\")\n```\n\n#### All episodes in a series\nYou can now retrieve all episodes in a series with a single call:\n```python\nfrom imdbinfo import get_all_episodes\n# Fetch all episodes for a series\nall_episodes = get_all_episodes(\"tt1520211\")  # Walking Dead\nfor episode in all_episodes:\n    print(f\"Title: {episode.title} - ({episode.imdbId})\")\n    print(f\"Plot: {episode.plot[:100]}...\")\n    print(f\"Release Date: {episode.release_date}\")\n    print(f\"Rating: {episode.rating}\")\n    print(f\"Duration: {episode.duration/60}min\")\n    print(\"\" + \"=\"*50)\n```\n\n#### Company Credits\n\n* distribution companies, \n* production companies, \n* sales companies, \n* special effects companies, \n* miscellaneous companies\n\nYou can now extract information about the companies involved in a movie or series:\n\n```python\nfrom imdbinfo import get_movie\n\nmovie = get_movie(\"tt0133093\")  # The Matrix\n\n# Distribution companies\nfor company in movie.company_credits[\"distribution\"]:\n    print(f\"Distribution: {company.name} ({company.country})\")\n\n# Sales companies\nfor company in movie.company_credits[\"sales\"]:\n    print(f\"Sales: {company.name}\")\n\n# Production companies\nfor company in movie.company_credits[\"production\"]:\n    print(f\"Production: {company.name}\")\n\n# Special effects companies\nfor company in movie.company_credits[\"specialEffects\"]:\n    print(f\"Special Effects: {company.name}\")\n\n# Miscellaneous companies\nfor company in movie.company_credits[\"miscellaneous\"]:\n    print(f\"Miscellaneous: {company.name}\")\n```\n\n#### Alternate titles (AKAs)\nFetch international and alternate titles for any movie or series:\n```python\nfrom imdbinfo import get_akas\nakas = get_akas(\"tt0133093\")  # The Matrix\nfor aka in akas[\"akas\"][:5]:\n    print(f\"{aka.title} ({aka.country_name})\")\n```\n\n#### Reviews and User Ratings\nGet user reviews and ratings for any movie or series:\n```python\nfrom imdbinfo import get_reviews\nreviews = get_reviews(\"tt0133093\")  # The Matrix\nfor review in reviews[:3]:\n    print(f\"Rating: {review['authorRating']}/10\")\n    print(f\"Summary: {review['summary']}\")\n    print(f\"Helpful votes: {review['upVotes']} up, {review['downVotes']} down\")\n    print(f\"Spoiler: {review['spoiler']}\")\n    print(\"---\")\n```\n\n#### Movie Trivia and Facts\nDiscover interesting trivia and behind-the-scenes facts:\n```python\nfrom imdbinfo import get_trivia\ntrivia = get_trivia(\"tt0133093\")  # The Matrix\nfor fact in trivia[:3]:\n    print(f\"Interest Score: {fact['interestScore']}\")\n    print(f\"Fact: {fact['body'][:200]}...\")\n    print(\"---\")\n```\n\n#### Parental Guide\nGet parental guide information including content advisories, severity level, spoiler flags, and content descriptions:\n\n```python\nfrom imdbinfo import get_parental_guide\n\npg = get_parental_guide(\"tt0133093\")  # The Matrix\nfor cat in pg.categories:\n    print(cat)  # e.g. NUDITY - MILD (6 descriptions)\n    for txt in cat.category_texts_list(spolier=True):\n        print(f\" - {txt.text} (SPOILER: {txt.is_spoiler})\")\n```\n\n#### Awards\n\nThe package groups award-related counts in the `MovieDetail.awards` object (an `AwardInfo` instance). The model currently exposes:\n\n- `wins` — number of award wins\n- `nominations` — number of nominations (excluding wins)\n- `prestigious_award` — optional dict containing details of a prestigious award (may include `wins` and `nominations` keys)\n\nExample showing how to safely read `MovieDetail.awards` using the current model shape:\n\n```python\nfrom imdbinfo import get_movie\n\nmovie = get_movie(\"tt0133093\")  # The Matrix\naw = movie.awards\nif not aw:\n    print(\"No award information available for this title\")\nelse:\n    # basic counts\n    print(\"wins:\", aw.wins)\n    print(\"nominations:\", aw.nominations)\n\n    # prestigious award (may be None or a dict)\n    if aw.prestigious_award:\n        pa = aw.prestigious_award\n        print(\"prestigious wins:\", pa.get(\"wins\"))\n        print(\"prestigious nominations:\", pa.get(\"nominations\"))\n    else:\n        print(\"No prestigious award summary available\")\n```\n\nNotes:\n- The JSON parser maps page data into `movie.awards` (a dict turned into an `AwardInfo` instance). Depending on the source data, `prestigious_award` can be None or a dict with `wins` and `nominations`.\n- Use `if movie.awards:` to check presence before reading attributes.\n\n\n### Localized results in multiple languages (set globally or per request)\n\nAdded support for locales in `search_movie`, `get_movie`, `get_episodes`, `get_all_episodes`, `get_name`\n```python\nfrom imdbinfo import get_movie, search_title\n# Fetch movie details in Italian\nmovie_it = get_movie(\"tt0133093\", locale=\"it\")  # The Matrix\n\n# Search for titles in Spanish (although IMDb search is mostly in all languages)\nresults_es = search_title(\"La Casa de Papel\", locale=\"es\")\n```\n\nLocalized data can be set globally, dont need to pass `locale` every time in the functions:\n```python\nfrom imdbinfo import get_movie\nfrom imdbinfo.locale import set_locale\nset_locale(\"it\")  # Set default locale to Italian\nmovie_it = get_movie(\"tt0133093\")  # The Matrix in Italian\n```\n\n#### MovieInfoBrief.title_localized\nThe `MovieInfoBrief` object (e.g., items in `results.titles` from `search_title`) now includes the `title_localized` property. This property contains the title in the requested locale, if available, and falls back to the default `title` when a localized version is not present.\n\nExample:\n```python\nfrom imdbinfo import search_title\n\n# Search for a title with a specific locale\nresults = search_title(\"The Matrix\", locale=\"it\")\nfor item in results.titles:\n    # Print the localized title if available, otherwise the default title\n    print(item.title, \"-\u003e\", getattr(item, \"title_localized\", item.title))\n```\n\n### Filtering results based on type (e.g. Movies, Series, Episodes etc.) 🔽 \nYou can filter results from `search_title`, done server-side.\n```python\nfrom imdbinfo import search_title, TitleType\n\n# Search for single type: movies\nresults = search_title(\"The Matrix\", title_type=TitleType.Movies)\nfor movie in results.titles:\n    print(f\"{movie.title} ({movie.year}) - {movie.imdb_id}\")\n\n# Search for multiple types: movies, shorts and videos.\nresults = search_title(\"The Matrix\", title_type=(TitleType.Movies, TitleType.Shorts, TitleType.Video))\nfor movie in results.titles:\n    print(f\"{movie.title} ({movie.year}) - {movie.imdb_id}\")\n\n```\n\n### Get filmography with images 🎬🖼️\nYou can now get filmography for actors, directors and writers and all credits with images:\n```python\nfrom imdbinfo import get_filmography\n\nfilmography = get_filmography(\"nm0000206\")  # Brad Pitt\nif filmography:\n    for role, films in filmography.items():\n        print(f\"\\nRole: {role}\")\n        for film in films:\n            print(f\" - {film.title} ({film.year}) [{film.imdbId}]\")\n\n```\n\n#### Get all interests for a title\n\n_Fetch all interests for a title using the provided IMDb ID. Most time it returns the same as genres. \n    It requires a new request and parsing. Use it only if you really need it._\n\n```python\nfrom imdbinfo import get_all_interests\n\nmovies = [\"tt1490017\", \"tt0133093\"]\n\nfor imdb_id in movies:\n    interests = get_all_interests(imdb_id)\n    print(f\"Interests for {imdb_id}: {interests}\")\n```\n\n\n📝 For more examples see the [examples](examples/) folder.\n\n\u003e 💡 **Looking for a ready-to-use API based on this package? Check out [qdMovieAPI](https://github.com/tveronesi/qdMovieAPI) — a fast and simple way to access IMDb data via REST!**\n\n## Why choose imdbinfo?\n\n- Easy to use Python API\n- Returns clean structured data\n- Powered by niquests and lxml\n- Uses Pydantic for type safety\n- No external dependencies or API keys required\n- Ideal for quick scripts and data analysis\n\n## Disclaimer\nThis project and its authors are not affiliated in any way with IMDb Inc. or its affiliates. \nFor more information, please refer to the [DISCLAIMER](DISCLAIMER.txt) file.\n\n## Contributing\n\nContributions are welcome! Open an issue or pull request on GitHub.\n\nIf you find this project useful, please consider giving it a ⭐ on GitHub!\n\nPlease read our [Contributing Guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.\n\n## Star History\n\n\u003ca href=\"https://www.star-history.com/?repos=tveronesi%2Fimdbinfo\u0026type=date\u0026legend=top-left\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=tveronesi/imdbinfo\u0026type=date\u0026theme=dark\u0026logscale\u0026legend=top-left\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=tveronesi/imdbinfo\u0026type=date\u0026logscale\u0026legend=top-left\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=tveronesi/imdbinfo\u0026type=date\u0026logscale\u0026legend=top-left\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n## License\n\nimdbinfo is released under the MIT License.\nSee the [LICENSE](LICENSE) file for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftveronesi%2Fimdbinfo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftveronesi%2Fimdbinfo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftveronesi%2Fimdbinfo/lists"}