Quick start

The first thing to do is to import imdb and call the imdb.IMDb function to get an access object through which IMDb data can be retrieved:

Important

Before creating the access object, download IMDb non-commercial datasets from https://datasets.imdbws.com/ (or run download-from-s3) and import them into SQLite:

s32cinemagoer.py /path/to/imdb-tsv-files/ sqlite:///cinemagoer.db

All examples on this page assume that this database is already populated. SQLite is used here for simplicity; Cinemagoer also supports other SQLAlchemy-supported databases.

>>> import imdb
>>> ia = imdb.Cinemagoer('s3', uri='sqlite:///cinemagoer.db')

This uses the S3 dataset access system. See S3 datasets for dataset import and database setup.

Searching

You can use the search_movie method of the access object to search for movies with a given (or similar) title. For example, to search for movies with titles like “matrix”:

>>> movies = ia.search_movie('matrix')
>>> movies[0]
<Movie id:0133093[s3] title:_The Matrix (1999)_>

Similarly, you can search for people using the search_person method:

>>> people = ia.search_person('angelina')
>>> people[0]
<Person id:0001401[s3] name:_Jolie, Angelina_>

As the examples indicate, the results are lists of Movie and Person objects. These behave like dictionaries, i.e. they can be queried by giving the key of the data you want to obtain:

>>> movies[0]['title']
'The Matrix'
>>> people[0]['name']
'Angelina Jolie'

Movie and person objects have id attributes that store the IMDb id of the object:

>>> movies[0].movieID
'0133093'
>>> people[0].personID
'0001401'

Retrieving

If you know the IMDb id of a movie, you can use the get_movie method to retrieve its data. For example, the movie “The Untouchables” by Brian De Palma has the id “0094226”:

>>> movie = ia.get_movie('0094226')
>>> movie
<Movie id:0094226[s3] title:_The Untouchables (1987)_>

Similarly, the get_person method can be used for retrieving Person data:

>>> person = ia.get_person('0000206')
>>> person['name']
'Keanu Reeves'
>>> person['birth date']
'1964-9-2'

Exceptions

Any error related to Cinemagoer can be caught by checking for the imdb.IMDbError exception:

from imdb import Cinemagoer, IMDbError

try:
   ia = Cinemagoer('s3', uri='sqlite:///cinemagoer.db')
   people = ia.search_person('Mel Gibson')
except IMDbError as e:
    print(e)

See also

For more details about available methods and objects, see Querying data, Data interface, Roles, and Series.