Skip to main content
Help us improve Python packaging – donate today!

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

Project Description

ImdbPie
=======

|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.

Installation
------------

To install imdbpie, simply:

.. code:: bash

pip install imdbpie

How To Use
----------

Initialise the client
~~~~~~~~~~~~~~~~~~~~~

.. code:: python

from imdbpie import Imdb
imdb = Imdb()

Available methods
~~~~~~~~~~~~~~~~~

NOTE: For each client method, if the resource cannot be found they will
raise ``LookupError``, for any other API status codes > 399 the client will raise ``ImdbAPIError``.

+----------------------------------------------------------------+-----------------------------------+
| Example | Description |
+================================================================+===================================+
| ``get_title('tt0111161')`` | Returns a dict containing title |
| | information |
+----------------------------------------------------------------+-----------------------------------+
| ``search_for_title("The Dark Knight")`` | Returns a dict of results |
| | |
+----------------------------------------------------------------+-----------------------------------+
| ``search_for_name("Christian Bale")`` | Returns a dict of results |
| | |
+----------------------------------------------------------------+-----------------------------------+
| ``title_exists('tt0111161')`` | Returns True if exists otherwise |
| | False |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_genres('tt0303461')`` | Returns a dict containing title |
| | genres information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_credits('tt0303461')`` | Returns a dict containing title |
| | credits information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_quotes('tt0303461')`` | Returns a dict containing title |
| | quotes information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_ratings('tt0303461')`` | Returns a dict containing title |
| | ratings information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_connections('tt0303461')`` | Returns a dict containing title |
| | connections information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_similarities('tt0303461')`` | Returns a dict containing title |
| | similarities information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_videos('tt0303461')`` | Returns a dict containing title |
| | videos information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_news('tt0303461')`` | Returns a dict containing news |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_trivia('tt0303461')`` | Returns a dict containing trivia |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_soundtracks('tt0303461')`` | Returns a dict containing |
| | soundtracks information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_goofs('tt0303461')`` | Returns a dict containing “goofs” |
| | and teaser information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_technical('tt0303461')`` | Returns a dict containing |
| | technical information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_companies('tt0303461')`` | Returns a dict containing |
| | information about companies |
| | related to title |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_episodes('tt0303461')`` | Returns a dict containing season |
| | and episodes information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_episodes_detailed(imdb_id='tt0303461', season=1)`` | Returns a dict containing |
| | detailed season episodes |
| | information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_top_crew('tt0303461')`` | Returns a dict containing |
| | detailed information about |
| | title’s top crew (ie: directors, |
| | writters, etc.) |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_plot('tt0111161')`` | Returns a dict containing title |
| | plot information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_plot_synopsis('tt0111161')`` | Returns a dict containing title |
| | plot synopsis information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_awards('tt0111161')`` | Returns a dict containing title |
| | plot information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_releases('tt0111161')`` | Returns a dict containing |
| | releases information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_versions('tt0111161')`` | Returns a dict containing |
| | versions information (meaning |
| | different versions of this title |
| | for different regions, or |
| | different versions for DVD vs |
| | Cinema) |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_user_reviews('tt0111161')`` | Returns a dict containing user |
| | review information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_metacritic_reviews('tt0111161')`` | Returns a dict containing |
| | metacritic review information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_images('tt0111161')`` | Returns a dict containing title |
| | images information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_name('nm0000151')`` | Returns a dict containing |
| | person/name information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_name_filmography('nm0000151')`` | Returns a dict containing |
| | person/name filmography |
| | information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_name_images('nm0000032')`` | Returns a dict containing |
| | person/name images information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_name_videos('nm0000032')`` | Returns a dict containing |
| | person/name videos information |
+----------------------------------------------------------------+-----------------------------------+
| ``validate_imdb_id('tt0111161')`` | Raises ``ValueError`` if not |
| | valid |
+----------------------------------------------------------------+-----------------------------------+
| ``get_popular_titles()`` | Returns a dict containing popular |
| | titles information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_popular_shows()`` | Returns a dict containing popular |
| | tv shows |
+----------------------------------------------------------------+-----------------------------------+
| ``get_popular_movies()`` | Returns a dict containing popular |
| | movies |
+----------------------------------------------------------------+-----------------------------------+

Requirements
------------

::

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

Running the tests
-----------------

.. code:: bash

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

.. |PyPI| image:: https://img.shields.io/pypi/v/imdbpie.svg
:target: https://pypi.python.org/pypi/imdb-pie
.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/imdbpie.svg
:target: https://pypi.python.org/pypi/imdb-pie
.. |Build Status| image:: https://travis-ci.org/richardasaurus/imdb-pie.png?branch=master
:target: https://travis-ci.org/richardasaurus/imdb-pie


.. :changelog:

Release History
---------------

5.4.4 (2018-04-17)
++++++++++++++++++

- Python 2.x setup.py 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**

- Added ``Imdb.popular_movies`` to retrieve current popular movies.


4.2.0 (2016-09-29)
++++++++++++++++++

**Added**

- ``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.

**Changes**

- Internal caching changed you use 3rd party package ``cachecontrol``.

**Removed**

- ``Imdb`` class no longer takes a ``cache_dir`` parameter.


3.0.0 (2015-06-12)
++++++++++++++++++

**Changed**

- 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)
++++++++++++++++++
**Added**

- ``Title.plot_outline`` has been added. It returns a string.


2.0.0 (2015-03-12)
++++++++++++++++++
**Added**

- ``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.

**Changed**

- ``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``.

**Removed**

- ``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.


Release history Release notifications

This version
History Node

5.4.4

History Node

5.4.3

History Node

5.4.2

History Node

5.4.1

History Node

5.4.0

History Node

5.3.0

History Node

5.2.0

History Node

5.1.0

History Node

5.0.0

History Node

4.4.2

History Node

4.4.1

History Node

4.4.0

History Node

4.3.0

History Node

4.2.0

History Node

4.1.0

History Node

4.0.2

History Node

3.0.0

History Node

2.1.0

History Node

2.0.1

History Node

2.0.0

History Node

1.5.6

History Node

1.5.5

History Node

1.5.4

History Node

1.5.3

History Node

1.4.4

History Node

1.4.3

History Node

1.4.2

History Node

1.4.1

History Node

1.4.0

History Node

1.3.3

History Node

1.3.2

History Node

1.3.1

History Node

1.3

History Node

1.2.15

History Node

1.2.14

History Node

1.2.13

History Node

1.2.12

History Node

1.2.11

History Node

1.2.10

History Node

1.2.9

History Node

1.2.8

History Node

1.2.7

History Node

1.2.6

History Node

1.2.5

History Node

1.2.4

History Node

1.2.3

History Node

1.2.2

History Node

1.2.1

History Node

1.2

History Node

1.1

Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
imdbpie-5.4.4-py2.py3-none-any.whl (14.7 kB) Copy SHA256 hash SHA256 Wheel py2.py3 Apr 17, 2018
imdbpie-5.4.4.tar.gz (13.9 kB) Copy SHA256 hash SHA256 Source None Apr 17, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page