Skip to main content

Python IMDB client using the IMDB json web service made available for their iOS app.

Project description

NOTICE: If you’re reading this on please be aware this is a mirror of the primary remote located at Please direct issues and pull requests there.


PyPI Python Versions Build Status

Python IMDB client using the IMDB JSON web service made available for their iOS application.

API Terminology

  • Title this can be a movie, tv show, video, documentary etc.

  • Name this can be a credit, cast member, any person generally.


To install imdbpie, simply:

pip install imdbpie

How to use

Choose an option:

  1. ImdbPie Facade usage examples (the easy way, returns objects).

  2. ImdbPie Client usage examples (more low level client API, returns raw dicts).


1. Python 2 or 3
2. See requirements.txt

Running the tests

pip install -r test_requirements.txt
py.test src/tests

Release History

5.6.5 (2023-04-18)

  • Packaging fixes.

5.6.4 (2023-04-18)

  • Fix for JSON parsing from the API.

  • Fix for title_exists method raising 403 error.

5.6.3 (2018-10-13)

  • Bugfix for handing of national characters within search methods.

5.6.2 (2018-07-09)

  • Bugfix for issue in ImdbFacade.get_title where TypeError would raise if the Title did not have any genres.

5.6.1 (2018-06-17)

  • Bugfix for issue in ImdbFacade.get_title where with titles which no do yet have credits information would cause KeyError to raise.

5.6.0 (2018-06-09)

  • Adds runtime attribute to ImdbFacade.

5.5.0 (2018-05-27)

  • Adds get_title_auxiliary method to client.

  • Adds ImdbFacade facade for API.

5.4.5 (2018-04-29)

  • Packaging documentation updates.

5.4.4 (2018-04-17)

  • Python 2.x bugfix.

  • Bugfix for title_exists method returning None.

  • Bugfix for get_title raising an incorrect exception when redirection title.

5.4.3 (2018-04-05)

  • Updates license.

5.4.2 (2018-04-05)

  • Fixes missing setuptools dependency for pypi display of markdown formatted files.

5.4.1 (2018-04-05)

  • Packaging documentation fixes.

5.4.0 (2018-03-18)

  • Bugfix for incorrect AttributeError message showing when undefined attrs called on client class.

  • Adds get_title_top_crew method.

5.3.0 (2018-02-27)

  • Adds get_title_plot_taglines method.

  • Adds get_title_news method.

  • Adds get_title_trivia method.

  • Adds get_title_soundtracks method.

  • Adds get_title_goofs method.

  • Adds get_title_technical method.

  • Adds get_title_companies method.

  • Adds get_title_episodes_detailed method.

5.2.0 (2018-01-11)

  • Updates get_title to call “/auxiliary” as “/fulldetails” endpoint now returns an error.

  • Adds get_title_quotes method.

  • Adds get_title_ratings method.

  • Adds get_title_connections method.

  • Adds get_title_awards method.

  • Adds get_title_plot_synopsis method.

  • Adds get_title_versions method.

  • Adds get_title_releases method.

  • Adds get_title_similarities method.

  • Adds get_title_videos method.

  • Adds get_name_videos method.

  • Adds get_name_filmography method.

  • Adds response status code to ImdbAPIError exception message.

5.1.0 (2018-01-10)

  • Adds get_title_genres method.

5.0.0 (2018-01-10)

  • Fixes client to work with new API.

  • Renames most of methods on Imdb class.

  • Changes all methods on Imdb to return raw JSON resource dictionary rather than Python objects.

  • Removes params from Imdb __init__ method (user_agent, proxy_uri, verify_ssl, api_key, cache, anonymize).

  • Adds clear_cached_credentials method to Imdb class.

4.4.2 (2018-01-03)

  • Fixes bug when searching with non alphanumeric characters, second attempt.

4.4.1 (2017-12-27)

  • Fixes bug when searching with non alphanumeric characters.

4.4.0 (2017-12-24)

  • Fixes search_for_person and search_for_title methods, which were broken because XML api used by the client was removed, migrated to using search suggestions api used by the website itself.

  • Adds optional session param to client init method, used to specify requests.Session.

  • All client methods will raise ValueError if invalid imdb_id param given.

4.3.0 (2017-08-10)


  • Added Imdb.popular_movies to retrieve current popular movies.

4.2.0 (2016-09-29)


  • Person.photo_url has been added. It returns a string (url) or None.

4.1.0 (2016-07-26)

  • Changed Title and other objects to use less memory.

  • Added notice of deprecation of caching in version 5.0.0.

  • Added Imdb.get_episodes to retrieve Title Episode information.

4.0.2 (2015-08-08)

Added - Added cache_expiry parameter to Imdb class, to specify cache expiry in seconds.


  • Internal caching changed you use 3rd party package cachecontrol.


  • Imdb class no longer takes a cache_dir parameter.

3.0.0 (2015-06-12)


  • All methods on Imdb will raise imdbpie.exceptions.HTTPError if a bad request to the API or resource is not found (“Errors should never pass silently”).

  • Imdb.get_title_reviews now has param max_results to limit number of reviews returned.

2.1.0 (2015-05-03)

Added - Added verify_ssl kwarg option to Imdb object. Allows for controlling of ssl cert verification on all requests made.

2.0.1 (2015-03-30)


  • Title.plot_outline has been added. It returns a string.

2.0.0 (2015-03-12)


  • Imdb.search_for_person has been added. It returns a list of dicts.

  • Imdb.get_title_plots has been added. It returns a list of strings.

  • Title.trailer_image_urls returns a list of trailer urls (string).

  • Imdb.get_person_by_id has been added. It returns a Person object.


  • Title.plots returns a list of full plots.

  • Title.trailers returns a list of dicts (keys: “url”, “format”).

  • Title.runtime returns runtime in seconds now instead of hours.

  • Person.role is now Person.roles and returns a list rather than a string.

  • Imdb.person_images has been renamed to Imdb.get_person_images.

  • Imdb.title_reviews has been renamed to Imdb.get_title_reviews and parameter limit has also been removed.

  • Imdb.title_images has been renamed to Imdb.get_title_images.

  • Imdb.find_by_title has been renamed to Imdb.search_for_title.

  • Imdb.find_movie_by_id has been renamed to Imdb.get_title_by_id and parameter json has been removed.

  • Imdb.movie_exists has been renamed to Imdb.title_exists.


  • Imdb.validate_id has been removed.

  • Title.plot_outline has been removed.

  • Title.trailer_img_url has been removed.

1.5.6 (2014-12-07)

  • No notes, release made before changelog inception.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

imdbpie-5.6.5.tar.gz (14.9 kB view hashes)

Uploaded Source

Built Distribution

imdbpie-5.6.5-py2.py3-none-any.whl (13.3 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page