IMDb_API is a custom open-source IMDb search API service, it allows users to make api calls to query the IMDb database. This repo contains all the necessary files required to initialize your own IMDb_API server.
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
IMDb_API requires Python (> Python 3.6) .
$ git clone https://github.com/gdsoumya/imdb_api.git
or
Download and extract the Zip-FileSetting up a virtual environment would be better for both development and normal execution purposes.
$ cd imdb_api
$ python -m virtualenv env
$ source env/bin/activate
or (Windows machine)
$ .\env\Scripts\activateThe Project has a few dependencies which can be installed by running.
$ pip install -r dependencies.txt To start the Flask server run
$ python api-server.pyA Flask development server will be initialized at http://127.0.0.1:5000/ . The API server is now ready to use, you can send requests to the server and fetch results.
A possible warning that one might get is :
WARNING: Do not use the development server in a production environment.
This warning is displayed because currently a Flask Development Server is running but the default environment of Flask is set to Production, to remove this warning change the FLASK_ENV environment variable.
*Setting environment to development automatically sets the debugger on.
$ export FLASK_ENV=development
or (Windows machine)
$ set FLASK_ENV=developmentThe API server provides 2 endpoints to access the search api :
- POST : /imdb-api-post
- GET : /imdb-api-get
Both endpoints return the same result.
A complete guide to using the api endpoints can be found at http://127.0.0.1:500/ .
REQUIRED Parameters
Atleast one of the following parameters are needed to perform a succesful search.
| Parameter | Description |
|---|---|
| title | Title/Query to Search |
| keywords | Instead of searching for specific Title, you can search for keywords that are related to the title you want to search. eg. 'detective' or 'jail,escape' |
| plot | This is a tricky and experimental feature, avoid using it. Instead of searching for specific Title, you can give the plot of the title you want to search. |
OPTIONAL Parameters
| Parameter | Description |
|---|---|
| title_type | Types of title to search, possible values :
|
| release_date | Two comma separated dates(YYYY-MM-DD) indicating a time range to search for title released in that range of time. eg. '1999-02-20,2018-11-29' or ' ,2000-01-31' or '1999-10-11, ' etc. |
| user_rating | Two comma separated integers(0-10) indicating the range of IMDb rating from which you want to search for the titles. eg. '1,9' or '5.6,9.9' etc. |
| genres | Genre to search titles from, possible values:
|
| colors | Color Info to search titles from,possible values:
|
| adult | Option to whether include or exclude adult titles, possible values:
|
| count | Maximum number of results to fetch. eg. '50','100' etc. Default max count is 50. |
GET Request
cURL Example:
curl -X GET http://127.0.0.1:5000/imdb-api-get?title=game&title_type=featureAJAX Example:
$.ajax({
url:'http://127.0.0.1:5000/imdb-api-get',
type:'get',
data:'title=game&title_type=feature',
success:function(myJson){
console.log(myJson);
}
});POST Request
cURL Example:
curl -d '{"title":"Game","title_type":"feature"}' -H "Content-Type: application/json" -X POST http://127.0.0.1:5000/imdb-api-postAJAX Example:
$.ajax({
url:'http://127.0.0.1:5000/imdb-api-post',
type:'post',
contentType:'application/json',
data:JSON.stringify({'title':'game','title_type':'feature'}),
success:function(myJson){
console.log(myJson);
}
});The Response is a list of dictionaries where each dictionary contains details about one title. The list is ordered in the descending order of Popularity of the titles.
SUCCESS Response :
- Code: 200
Response :
[
{
"directors": "John Francis Daley, Jonathan Goldstein",
"genre": "Action, Comedy, Crime",
"gross": "$69.00M",
"idm_id": "tt2704998",
"name": "Game Night (I) (2018)",
"plot": "A group of friends who meet regularly for game nights find themselves entangled ....",
"poster": "https://m.media-amazon.com/images/M/MV5BMjI3ODkzNDk5MF5BMl5BanBnX.jpg",
"rating": "7.0",
"runtime": "100 min",
"stars": "Jason Bateman, Rachel McAdams, Kyle Chandler, Sharon Horgan",
"votes": "155,318",
},
...
...
...]
ERROR Response :
- Code: 400
Response :
{"error":"Title/Keyword/Plot is required"}- Code: 500
Response :
{"error":"SERVER ERROR"}The parameters returned for each title :
| Parameter | Description |
|---|---|
| idm_id | IMDb ID of the title. |
| name | Name of the title. |
| plot | Short summary/plot of the story. |
| poster | Poster image urls. |
| genre | Genre of the title. |
| runtime | Duration of the movie/title. |
| rating | IMDb Rating of the title. |
| directors | Name of the Directors of the title. |
| stars | Cast of the title. |
| votes | Number of votes recieved by the title on IMDb. |
| gross | Gross amount earned by the title. |
To see a ready-made example of using the API visit http://127.0.0.1:5000/test-api . The test queries both the POST and GET endpoints with just the title parameter and fetches the results and displays it on the webpage. The whole process is done on the client side using AJAX call, it can also be achieved using a asynchronus fetch operation in javascript too.
The server by default does not start in debugger mode but to initialize debugger mode change the last line of the 'api-server.py' file to :
app.run() -> app.run(debug=True)Most errors will be logged to the console and can be referenced later for debugging.
- Requests : For fetching data from IMDb.
- BeautifulSoup : For parsing the fetched data.
- Flask : For hosting the API server.
- Flask-Cors : For enabling Cross Origin Resource Sharing.
- Soumya Ghosh Dastidar
Any contribution/suggestions are welcomed.