A minimalist Python wrapper for the Open Movie Database (OMDb) API (https://www.omdbapi.com/).
omdbpy is a minimalist Python wrapper for the Open Movie Database (OMDb) API (https://www.omdbapi.com/).
$ pip install omdbpy
To run linting via flake8 and pylint, formatting via black, unit tests via pytest, get a coverage report, and build via sdist on all support versions of Python, run the following command:
$ tox
search_terms>>> import omdb
>>> import json
>>> omdb_api = omdb.Api(apikey='123xyz')
>>> result = omdb_api.search(search_terms='terminator', release_year='1984')
>>> print(json.dumps(result.json(), indent=4))
{
"Search": [
{
"Title": "The Terminator",
"Year": "1984",
"imdbID": "tt0088247",
"Type": "movie",
"Poster": "https://m.media-amazon.com/images/M/MV5BYTViNzMxZjEtZGEwNy00MDNiLWIzNGQtZDY2MjQ1OWViZjFmXkEyXkFqcGdeQXVyNzkwMjQ5NzM@._V1_SX300.jpg"
},
{
"Title": "The Making of 'Terminator'",
"Year": "1984",
"imdbID": "tt0267719",
"Type": "movie",
"Poster": "https://m.media-amazon.com/images/M/MV5BMTQ3MzE5NTI0Nl5BMl5BanBnXkFtZTgwNDE1OTk1MDE@._V1_SX300.jpg"
}
],
"totalResults": "2",
"Response": "True"
}
title>>> import omdb
>>> import json
>>> omdb_api = omdb.Api(apikey='123xyz')
>>> result = omdb_api.search(title='terminator', release_year='1984')
>>> print(json.dumps(result.json(), indent=4))
{
"Title": "The Terminator",
"Year": "1984",
"Rated": "R",
"Released": "26 Oct 1984",
"Runtime": "107 min",
"Genre": "Action, Sci-Fi",
"Director": "James Cameron",
"Writer": "James Cameron, Gale Anne Hurd, William Wisher (additional dialogue)",
"Actors": "Arnold Schwarzenegger, Michael Biehn, Linda Hamilton, Paul Winfield",
"Plot": "A cyborg is sent from the future on a deadly mission. He has to kill Sarah Connor, a young woman whose life will have a great significance in years to come. Sarah has only one protector - Kyle Reese - also sent from the future. The Terminator uses his exceptional intelligence and strength to find Sarah, but is there any way to stop the seemingly indestructible cyborg ?",
"Language": "English, Spanish",
"Country": "UK, USA",
"Awards": "6 wins & 6 nominations.",
"Poster": "https://m.media-amazon.com/images/M/MV5BYTViNzMxZjEtZGEwNy00MDNiLWIzNGQtZDY2MjQ1OWViZjFmXkEyXkFqcGdeQXVyNzkwMjQ5NzM@._V1_SX300.jpg",
"Ratings": [
{
"Source": "Internet Movie Database",
"Value": "8.0/10"
},
{
"Source": "Rotten Tomatoes",
"Value": "100%"
},
{
"Source": "Metacritic",
"Value": "84/100"
}
],
"Metascore": "84",
"imdbRating": "8.0",
"imdbVotes": "734,748",
"imdbID": "tt0088247",
"Type": "movie",
"DVD": "03 Sep 1997",
"BoxOffice": "N/A",
"Production": "Orion Pictures Corporation",
"Website": "http://www.terminator1.com/",
"Response": "True"
}
imdb_id>>> import omdb
>>> import json
>>> omdb_api = omdb.Api(apikey='123xyz')
>>> result = omdb_api.search(imdb_id='tt0088247', release_year='1984')
>>> print(json.dumps(result.json(), indent=4))
{
"Title": "The Terminator",
"Year": "1984",
"Rated": "R",
"Released": "26 Oct 1984",
"Runtime": "107 min",
"Genre": "Action, Sci-Fi",
"Director": "James Cameron",
"Writer": "James Cameron, Gale Anne Hurd, William Wisher (additional dialogue)",
"Actors": "Arnold Schwarzenegger, Michael Biehn, Linda Hamilton, Paul Winfield",
"Plot": "A cyborg is sent from the future on a deadly mission. He has to kill Sarah Connor, a young woman whose life will have a great significance in years to come. Sarah has only one protector - Kyle Reese - also sent from the future. The Terminator uses his exceptional intelligence and strength to find Sarah, but is there any way to stop the seemingly indestructible cyborg ?",
"Language": "English, Spanish",
"Country": "UK, USA",
"Awards": "6 wins & 6 nominations.",
"Poster": "https://m.media-amazon.com/images/M/MV5BYTViNzMxZjEtZGEwNy00MDNiLWIzNGQtZDY2MjQ1OWViZjFmXkEyXkFqcGdeQXVyNzkwMjQ5NzM@._V1_SX300.jpg",
"Ratings": [
{
"Source": "Internet Movie Database",
"Value": "8.0/10"
},
{
"Source": "Rotten Tomatoes",
"Value": "100%"
},
{
"Source": "Metacritic",
"Value": "84/100"
}
],
"Metascore": "84",
"imdbRating": "8.0",
"imdbVotes": "734,748",
"imdbID": "tt0088247",
"Type": "movie",
"DVD": "03 Sep 1997",
"BoxOffice": "N/A",
"Production": "Orion Pictures Corporation",
"Website": "http://www.terminator1.com/",
"Response": "True"
}
Although search_terms, imdb_id, and title are all optional, at least one must be chosen or an error will be returned.
Through testing, it appears that there is a priority order. In other words, if one query parameter is provided, it will take priority over the others
that are provided. This theory can be tested easily by providing three different examples and verifying the results.
The priority is as follows: search_terms > title > imdb_id. Keep in mind that the release_year greatly affects the results as well.
For example, if you search via title with title="terminator" and the release_year="1984", you will get The Terminator (imdb_id=tt0088247):
>>> import omdb
>>> import json
>>> omdb_api = omdb.Api(apikey='123xyz')
>>> result = omdb_api.search(title='terminator', release_year='1984')
>>> print(json.dumps(result.json(), indent=4))
{
"Title": "The Terminator",
"Year": "1984",
"Rated": "R",
"Released": "26 Oct 1984",
"Runtime": "107 min",
"Genre": "Action, Sci-Fi",
"Director": "James Cameron",
"Writer": "James Cameron, Gale Anne Hurd, William Wisher (additional dialogue)",
"Actors": "Arnold Schwarzenegger, Michael Biehn, Linda Hamilton, Paul Winfield",
"Plot": "A cyborg is sent from the future on a deadly mission. He has to kill Sarah Connor, a young woman whose life will have a great significance in years to come. Sarah has only one protector - Kyle Reese - also sent from the future. The Terminator uses his exceptional intelligence and strength to find Sarah, but is there any way to stop the seemingly indestructible cyborg ?",
"Language": "English, Spanish",
"Country": "UK, USA",
"Awards": "6 wins & 6 nominations.",
"Poster": "https://m.media-amazon.com/images/M/MV5BYTViNzMxZjEtZGEwNy00MDNiLWIzNGQtZDY2MjQ1OWViZjFmXkEyXkFqcGdeQXVyNzkwMjQ5NzM@._V1_SX300.jpg",
"Ratings": [
{
"Source": "Internet Movie Database",
"Value": "8.0/10"
},
{
"Source": "Rotten Tomatoes",
"Value": "100%"
},
{
"Source": "Metacritic",
"Value": "84/100"
}
],
"Metascore": "84",
"imdbRating": "8.0",
"imdbVotes": "734,748",
"imdbID": "tt0088247",
"Type": "movie",
"DVD": "03 Sep 1997",
"BoxOffice": "N/A",
"Production": "Orion Pictures Corporation",
"Website": "http://www.terminator1.com/",
"Response": "True"
}
However, if you search via search_terms with search_terms="terminator" with release_year="1985", you will get Ninja Terminator (imdb_id=tt0199849):
>>> import omdb
>>> import json
>>> omdb_api = omdb.Api(apikey='123xyz')
>>> result = omdb_api.search(search_terms='terminator', release_year='1985')
>>> print(json.dumps(result.json(), indent=4))
{
"Search": [
{
"Title": "Ninja Terminator",
"Year": "1985",
"imdbID": "tt0199849",
"Type": "movie",
"Poster": "https://m.media-amazon.com/images/M/MV5BMGZiNTczNWItOTdmYy00OTFjLWIwOWUtMmE3Y2QyNzBmZDJkXkEyXkFqcGdeQXVyNzg3NjQyOQ@@._V1_SX300.jpg"
}
],
"totalResults": "1",
"Response": "True"
}
Often, you will receive more than one object as the result of a search. For example, if you search via search_terms with search_terms="terminator" with the release_year="2002", you will get
The Terminator: Dawn of Fate (imdb_id=tt0320595) and Terminator: A Short Film About JT LeRoy (imdb_id=tt7108520):
>>> import omdb
>>> import json
>>> omdb_api = omdb.Api(apikey='123xyz')
>>> result = omdb_api.search(search_terms='terminator', release_year='2002')
>>> print(json.dumps(result.json(), indent=4))
{
"Search": [
{
"Title": "The Terminator: Dawn of Fate",
"Year": "2002",
"imdbID": "tt0320595",
"Type": "game",
"Poster": "https://m.media-amazon.com/images/M/MV5BYjEyNWU3Y2ItMGI4MS00OGY2LTk2ZTUtNWQyNDY3MTRmM2I1XkEyXkFqcGdeQXVyMzM4MjM0Nzg@._V1_SX300.jpg"
},
{
"Title": "Terminator: A Short Film About JT LeRoy",
"Year": "2002",
"imdbID": "tt7108520",
"Type": "movie",
"Poster": "N/A"
}
],
"totalResults": "2",
"Response": "True"
}
If there are no results, you will get a response with a message like this one:
>>> import omdb
>>> import json
>>> omdb_api = omdb.Api(apikey='123xyz')
>>> result = omdb_api.search(search_terms='terminator', release_year='32')
>>> print(json.dumps(result.json(), indent=4))
{
"Response": "False",
"Error": "Movie not found!"
}
Finally, if the request doesn't make sense, you will get a response with a message like this one:
>>> import omdb
>>> import json
>>> omdb_api = omdb.Api(apikey='123xyz')
>>> result = omdb_api.search(release_year='32')
>>> print(json.dumps(result.json(), indent=4))
{
"Response": "False",
"Error": "Something went wrong."
}
FAQs
A minimalist Python wrapper for the Open Movie Database (OMDb) API (https://www.omdbapi.com/).
We found that omdbpy demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Browserslist-rs now uses static data to reduce binary size by over 1MB, improving memory use and performance for Rust-based frontend tools.
Research
Security News
Eight new malicious Firefox extensions impersonate games, steal OAuth tokens, hijack sessions, and exploit browser permissions to spy on users.
Security News
The official Go SDK for the Model Context Protocol is in development, with a stable, production-ready release expected by August 2025.