Skip to main content

Python wrapper for OMDb API: http://www.omdbapi.com/

Project description

version travis coveralls license

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

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

Changelog

v0.10.1 (2018-12-10)

  • Fix mishandling of fullplot, tomatoes, and timeout parameters in OMDBClient.get() that did not work correctly in conjuction with OMDBClient.set_default().

  • Fix mishandling of type parameter which was not being serialized to API request.

v0.10.0 (2018-04-08)

  • Add methods to OMDBClient that mirror module functions:

    • search()

    • search_movie()

    • search_episode()

    • search_series()

    • imdbid()

    • title()

v0.9.1 (2018-03-24)

  • Remove omdb.models module and return plain dictionaries from search results instead of custom model classes. (breaking change)

    • Previously, one could access result items using attributes (e.g. result.title) or indexes (e.g. result['title']). Now, results are dict objects so must use result['title'].

  • Rename omdb.Client to omdb.OMDBClient. (breaking change)

  • Make omdb.request|omdb.OMDBClient.request use an API key if it’s set.

v0.8.1 (2017-08-10)

  • Add support for OMDb API key via omdb.set_default(apikey=API_KEY) or client = omdb.Client(apikey=API_KEY). Thanks oshribr!

  • Add Epiodes OMDb API fields as episodes model field.

v0.7.0 (2016-08-03)

  • Add support for page parameter to search. Thanks taserian!

v0.6.0 (2016-05-22)

  • Add support for timeout parameter to all HTTP requests.

v0.5.0 (2015-07-29)

  • Add support for Season/Episode OMDb parameter via season/episode arguments to every main API function. Thanks cihansahin!

v0.4.0 (2015-04-29)

  • Add Season, Episode, and SeriesID OMDb API fields as season, episode, and series_id model fields.

v0.3.1 (2015-01-27)

  • Add metadata to main module:

    • __title__

    • __summary__

    • __url__

    • __version__

    • __author__

    • __email__

    • __license__

v0.3.0 (2015-01-13)

  • Add search_movie.

  • Add search_episode.

  • Add search_series.

  • Add support for type OMDb parameter via media_type argument to every main API function.

v0.2.0 (2014-10-16)

  • Update models.Item with additional OMDb API fields: Awards, Country, Language, and Metascore.

  • Add omdb.request method for easier access to raw request response.

  • Initialization of omdb.Client now accepts keyword arguments for API request parameter defaults. Previously, a dict object needed to be passed in.

  • Full PEP8 compliance.

  • Integrate tox testing into setup.py.

v0.1.1 (2014-02-09)

v0.1.0 (2013-11-24)

  • Convert API response to data models (see omdb/models.py).

  • Add /tests folder and move appropriate doctests there.

  • Return empty data for search and get requests which return no record(s).

  • Add omdb.set_default() for setting default request parameters (e.g. set_default(tomatoes=True) to always include tomatoes data)

v0.0.1 (2013-11-12)

  • Initial release.

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

omdb-0.10.1.tar.gz (23.2 kB view hashes)

Uploaded Source

Built Distribution

omdb-0.10.1-py2.py3-none-any.whl (9.8 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