omdb.py¶

Python wrapper around The Open Movie Database API (a.k.a. OMDb API): http://omdbapi.com/

NOTE: This library and its author are not endorsed by or affiliated with OMDbAPI.com.

Installation¶

Using pip:

pip install omdb

Dependencies¶

requests >= 2.0.1

API¶

Each omdb.py method supports the same parameters as the OMDb API.

Paramters¶

OMDb API Param	omdb.py Param	Value	Description
`s`	`search`	string (optional)	title of media to search for
`i`	`imdbid`	string (optional)	a valid IMDb ID
`t`	`title`	string (optional)	title of media to return
`y`	`year`	year (optional)	year of media
`page`	`page`	page (optional)	page to return
`Season`	`season`	season (optional)	season number
`Episode`	`episode`	episode (optional)	episode number
`type`	`media_type`	string (optional)	media type to return (one of `movie`, `episode`, or `series`)
`plot=full`	`fullplot=True`	`full`	include extended plot
`plot=short`	`fullplot=False`	`short`	include short plot (default)
`tomatoes=true`	`tomatoes=True`	`true` (optional)	add Rotten Tomatoes data to response

NOTE: By default all OMDb API responses are formatted as JSON. However, OMDb API also supports responses formatted as XML. Since omdb.py will handle JSON to dict conversion automatically, it’s generally not necessary (nor is it supported by the main ombd.py methods) to return XML formatted responses. But this can be accomplished by directly using omdb.request:

import omdb

# must use OMDb API parameters
res = omdb.request(t='True Grit', y=1969, r='xml')
xml_content = res.content

Methods¶

All methods are accessible via:

import omdb

# omdb.<method>

Method	Description	Returns
`get(**params)`	Generic request to OMDb API (requires keyword argument passing of all parameters).	`dict`
`search(search, **params)`	Search by string.	`list`
`search_movie(search, **params)`	Search movies by string.	`list`
`search_episode(search, **params)`	Search episodes by string.	`list`
`search_series(search, **params)`	Search series by string.	`list`
`imdbid(imdbid, **params)`	Get by IMDB ID	`dict`
`title(title, **params)`	Get by title	`dict`
`set_default(key, default)`	Set default request parameter	`None`

Client¶

Instead of using the omdb module to access the OMDb API, one can create an OMDBClient instance:

from omdb import OMDBClient

client = OMDBClient(apikey=API_KEY)

Class Methods	Description	Returns
`get(**omdb_params)`	Generic request to OMDb API which can be used for any type of query.	`list` or `dict`
`request(**omdbapi_params)`	Lower-level request to OMDb API which accepts URL query parameters supported by OMDb API.	`request.Response`
`set_default(key, default)`	Set default request parameter.	`None`

API Data¶

API data returned from the OMDb API is returned as a dictionary with their fields converted from CamelCase to underscore_case.

Search Model Fields¶

OMDb API Field	omdb.py Field
`Title`	`title`
`Year`	`year`
`Type`	`type`
`imdbID`	`imdb_id`

Get Model Fields (tomatoes=False)¶

OMDb API Field	omdb.py Field
`Title`	`title`
`Year`	`year`
`Type`	`type`
`Actors`	`actors`
`Awards`	`awards`
`Country`	`country`
`Director`	`director`
`Genre`	`genre`
`Episode`	`episode`
`Episodes`	`episodes`
`Season`	`season`
`SeriesID`	`series_id`
`Language`	`language`
`Metascore`	`metascore`
`Plot`	`plot`
`Poster`	`poster`
`Rated`	`rated`
`Ratings`	`ratings`
`Released`	`released`
`Response`	`response`
`Runtime`	`runtime`
`Writer`	`writer`
`imdbID`	`imdb_id`
`imdbRating`	`imdb_rating`
`imdbVotes`	`imdb_votes`

Get Model Fields (tomatoes=True)¶

OMDb API Field	omdb.py Field
`Title`	`title`
`Year`	`year`
`Type`	`type`
`Actors`	`actors`
`Awards`	`awards`
`Country`	`country`
`Director`	`director`
`Genre`	`genre`
`Episode`	`episode`
`Season`	`season`
`SeriesID`	`series_id`
`Language`	`language`
`Metascore`	`metascore`
`Plot`	`plot`
`Poster`	`poster`
`Rated`	`rated`
`Ratings`	`ratings`
`Released`	`released`
`Runtime`	`runtime`
`Writer`	`writer`
`imdbID`	`imdb_id`
`imdbRating`	`imdb_rating`
`imdbVotes`	`imdb_votes`
`BoxOffice`	`box_office`
`DVD`	`dvd`
`Production`	`production`
`Website`	`website`
`tomatoConsensus`	`tomato_consensus`
`tomatoFresh`	`tomato_fresh`
`tomatoImage`	`tomato_image`
`tomatoMeter`	`tomato_meter`
`tomatoRating`	`tomato_rating`
`tomatoReviews`	`tomato_reviews`
`tomatoRotten`	`tomato_rotten`
`tomatoUserMeter`	`tomato_user_meter`
`tomatoUserRating`	`tomato_user_rating`
`tomatoUserReviews`	`tomato_user_reviews`

Usage¶

General Import¶

import omdb

Note

All functions below support a timeout keyword argument that will be forwarded to the underlying requests.get function call. You can also set a global default using omdb.set_default('timeout', <timeout>) that will be used when timeout is not explicitly provided.

API Key¶

Usage of the OMDb API currently requires an API key. Set the OMDb API key with omdb.set_default or when creating a new omdb.OMDBClient instance:

# if using the module level client
omdb.set_default('apikey', API_KEY)

# if creating a new client instance
client = omdb.OMDBClient(apikey=API_KEY)

omdb.get()¶

# include full plot and Rotten Tomatoes data
omdb.get(title='True Grit', year=1969, fullplot=True, tomatoes=True)

# set timeout of 5 seconds for this request
omdb.get(title='True Grit', year=1969, fullplot=True, tomatoes=True, timeout=5)

omdb.search()¶

# search by string
omdb.search('True Grit')
omdb.search('True Grit', timeout=5)
omdb.search('true', page=2)

omdb.search_movie()¶

# search movies by string
omdb.search_movie('True Grit')
omdb.search_movie('True Grit', timeout=5)
omdb.search_movie('true', page=2)

omdb.search_episode()¶

# search episodes by string
omdb.search_episode('True Grit')
omdb.search_episode('True Grit', timeout=5)
omdb.search_episode('true', page=2)

omdb.search_series()¶

# search series by string
omdb.search_series('True Grit')
omdb.search_series('True Grit', timeout=5)
omdb.search_series('true', page=2)

omdb.imdbid()¶

# get by IMDB id
omdb.imdbid('tt0065126')
omdb.imdbid('tt0065126', timeout=5)

omdb.title()¶

# get by title
omdb.title('True Grit')
omdb.title('True Grit', timeout=5)

omdb.set_default()¶

# include tomatoes data by default
omdb.set_default('tomatoes', True)
omdb.title('True Grit') == omdb.title('True Grit', tomatoes=True)

# set a global timeout of 5 seconds for all HTTP requests
omdb.set_default('timeout', 5)

omdb.request()¶

# lower level API request
omdb.request(t='True Grit', y=1969, plot='full', tomatoes='true', timeout=5)

Returns:

A requests.Response object.

Errors and Exceptions¶

Under the hood, omdb.py uses the requests library. For a listing of explicit exceptions raised by requests, see Requests: Errors and Exceptions.

By default requests will not raise an Exception when an HTTP response’s status code is not 200. However, omdb.py WILL raise an requests.exceptions.HTTPError error for any response with a non-200 status code.

Guide¶

Installation

API Reference¶

Includes links to source code.

API Reference