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.
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.
API Reference¶
Includes links to source code.
API Reference¶
-
omdb.get(**params)¶ Generic request.
-
omdb.imdbid(string, **params)¶ Get by IMDB ID.
-
omdb.request(**params)¶ Lower-level request.
-
omdb.search(string, **params)¶ Search by string.
-
omdb.search_movie(string, **params)¶ Search movies by string.
-
omdb.search_episode(string, **params)¶ Search episodes by string.
-
omdb.search_series(string, **params)¶ Search series by string.
-
omdb.set_default(key, default)¶ Proxy method to internal client instance that sets default params values.
-
omdb.title(string, **params)¶ Get by title.
-
class
omdb.OMDBClient(**defaults)¶ HTTP request client for OMDb API.
-
format_params(params)¶ Format our custom named params to OMDb API param names.
-
format_search_item(item)¶ Format search item by converting dict key case from camel case to underscore case.
-
format_search_list(items)¶ Format each search item using
format_search_item().
-
format_search_results(data, params)¶ Format OMDb API search results into standard format.
-
get(search=None, title=None, imdbid=None, year=None, page=1, fullplot=None, tomatoes=None, media_type=None, season=None, episode=None, timeout=None)¶ Make OMDb API GET request and return results.
-
imdbid(string, **params)¶ Get by IMDB ID.
-
request(**params)¶ Lower-level HTTP GET request to OMDb API.
Raises exception for non-200 HTTP status codes.
-
search(string, **params)¶ Search by string.
-
search_episode(string, **params)¶ Search episodes by string.
-
search_movie(string, **params)¶ Search movies by string.
-
search_series(string, **params)¶ Search series by string.
-
set_default(key, default)¶ Set default request params.
-
title(string, **params)¶ Get by title.
-
Project Info¶
License¶
The MIT License (MIT)
Copyright (c) 2014 Derrick Gilland
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Changelog¶
v0.10.1 (2018-12-10)¶
- Fix mishandling of
fullplot,tomatoes, andtimeoutparameters inOMDBClient.get()that did not work correctly in conjuction withOMDBClient.set_default(). - Fix mishandling of
typeparameter which was not being serialized to API request.
v0.10.0 (2018-04-08)¶
- Add methods to
OMDBClientthat mirror module functions:search()search_movie()search_episode()search_series()imdbid()title()
v0.9.1 (2018-03-24)¶
- Remove
omdb.modelsmodule 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 aredictobjects so must useresult['title'].
- Previously, one could access result items using attributes (e.g.
- Rename
omdb.Clienttoomdb.OMDBClient. (breaking change) - Make
omdb.request|omdb.OMDBClient.requestuse 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)orclient = omdb.Client(apikey=API_KEY). Thanks oshribr! - Add
EpiodesOMDb API fields asepisodesmodel field.
v0.6.0 (2016-05-22)¶
- Add support for
timeoutparameter to all HTTP requests.
v0.5.0 (2015-07-29)¶
- Add support for
Season/EpisodeOMDb parameter viaseason/episodearguments to every main API function. Thanks cihansahin!
v0.4.0 (2015-04-29)¶
- Add
Season,Episode, andSeriesIDOMDb API fields asseason,episode, andseries_idmodel 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
typeOMDb parameter viamedia_typeargument to every main API function.
v0.2.0 (2014-10-16)¶
- Update
models.Itemwith additionalOMDb APIfields:Awards,Country,Language, andMetascore. - Add
omdb.requestmethod for easier access to raw request response. - Initialization of
omdb.Clientnow accepts keyword arguments for API request parameter defaults. Previously, adictobject needed to be passed in. - Full PEP8 compliance.
- Integrate
toxtesting intosetup.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
searchandgetrequests 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.
Authors¶
Lead¶
- Derrick Gilland, dgilland@gmail.com, dgilland@github
Contributors¶
- Alex Grönholm, agronholm@github
- Cihan Sahin, cihansahin@github
- taserian, taserian@github
- oshribr, oshribr@github