User:Kunalkapoor/sandbox

Introduction

The Open Movie Database (OMDb API) provides an easy web interface to access information of online media content referenced on IMDb. It provides a simple web service that responds to HTTP GET requests and returns the search results in either JSON or XML. The API can be used to search for movies, series and episodes using keywords or clues like name, type and year of release. It can also provide a detailed result for a particular movie, series or episode outputting interesting aspects about the media like the plot, Rotten Tomatoes ratings and others.^[1]^[2]

The web service also provides a Poster API that returns an image of the poster of the media requested. The API also provides a monthly database dump of media which users can subscribe to. These features are only for users that have donated to the website and is currently in closed beta.^[3]

Usage

There are two ways to get the data using OMDb API first is by using IMDb ID or movie title and other is by using search string. To use the OMDb API send the HTTP GET request using this link http://www.omdbapi.com/ by adding parameter mentioned in below table.

By ID or Title

In this method you need to provide the ID or title to get the JSON /XML response. After the request is sent, a detailed response for that particular IMDb ID or response with the closest match to title will be returned. If there is no match for title or ID, a response with "Movie not found" error will be returned. ^[1]

Paramter	Required	Valid Options	Default value	Description
i	optional		<empty>	A valid IMDb ID (e.g. tt1285016)
t	optional		<empty>	Movie title to search for
type	no	movie, series, episode, game	<empty>	Type of result to return
y	no		<empty>	Year of release
plot	no	short, full	short	Return short or full plot
r	no	json, xml	json	The data type to return
tomatoes	no	true, false	false	Include Rotten Tomatoes ratings
Season	no		<empty>	Season number
Episode	no		<empty>	Episode number
callback	no		<empty>	JSONP callback name
v	no		1	API version (reserved for future use)

By Search

In this method you can search the database using a search string and a list of movies matching the search string will be returned as the response. If no match is found for the search string then a "Movie not found" error will be returned.^[1]

Paramter	Required	Valid Options	Default value	Description
s	yes		<empty>	Movie title to search for
type	no	movie, series, episode, game	<empty>	Type of result to return
y	no		<empty>	Year of release
r	no	json, xml	json	The data type to return
page	no	1-100	1	Page to return
callback	no		<empty>	JSONP callback name
v	no		1	API version (reserved for future use)

Examples

By ID or Title

The simplest search by title can be the following:

http://www.omdbapi.com/?t=the%20matrix&tomatoes=true

It returns a JSON result which contains details on the movie The Matrix along with its rating on Rotten Tomatoes. When parsed into a readable format the output looks like below:

{
  "Title": "The Matrix",
  "Year": "1999",
  "Rated": "R",
  "Released": "31 Mar 1999",
  "Runtime": "136 min",
  "Genre": "Action, Sci-Fi",
  "Director": "Lana Wachowski, Lilly Wachowski",
  "Writer": "Lilly Wachowski, Lana Wachowski",
  "Actors": "Keanu Reeves, Laurence Fishburne, Carrie-Anne Moss, Hugo Weaving",
  "Plot": "A computer hacker learns from mysterious rebels about the true nature of his reality and his role in the war against its controllers.",
  "Language": "English",
  "Country": "USA",
  "Awards": "Won 4 Oscars. Another 33 wins & 43 nominations.",
  "Poster": "http://ia.media-imdb.com/images/M/MV5BMTkxNDYxOTA4M15BMl5BanBnXkFtZTgwNTk0NzQxMTE@._V1_SX300.jpg",
  "Metascore": "73",
  "imdbRating": "8.7",
  "imdbVotes": "1,224,854",
  "imdbID": "tt0133093",
  "Type": "movie",
  "tomatoMeter": "87",
  "tomatoImage": "certified",
  "tomatoRating": "7.6",
  "tomatoReviews": "142",
  "tomatoFresh": "124",
  "tomatoRotten": "18",
  "tomatoConsensus": "Thanks to the Wachowskis' imaginative vision, The Matrix is a smartly crafted combination of spectacular action and groundbreaking special effects.",
  "tomatoUserMeter": "85",
  "tomatoUserRating": "3.6",
  "tomatoUserReviews": "33321462",
  "tomatoURL": "http://www.rottentomatoes.com/m/matrix/",
  "DVD": "21 Sep 1999",
  "BoxOffice": "N/A",
  "Production": "Warner Bros. Pictures",
  "Website": "http://www.whatisthematrix.com",
  "Response": "True"
}

A more detailed example would be^[4]:

http://www.omdbapi.com/?t=stargate&type=series&season=1&r=xml

This returns the details of Season 1 of the TV series, Stargate SG-1 (the closest name to stargate given in the parameter) in an XML format.

<?xml version="1.0" encoding="UTF-8"?>
<root Title="Stargate SG-1" Season="1" totalSeasons="10" Response="True">
   <result Title="Children of the Gods" Released="1997-07-27" Episode="1" imdbRating="8.3" imdbID="tt0234794" />
   <result Title="The Enemy Within" Released="1997-08-01" Episode="2" imdbRating="7.7" imdbID="tt0709185" />
   <result Title="Emancipation" Released="1997-08-08" Episode="3" imdbRating="6.1" imdbID="tt0709075" />
   <result Title="The Broca Divide" Released="1997-08-15" Episode="4" imdbRating="7.2" imdbID="tt0709181" />
   <result Title="The First Commandment" Released="1997-08-22" Episode="5" imdbRating="6.8" imdbID="tt0709188" />
   <result Title="Cold Lazarus" Released="1997-08-29" Episode="6" imdbRating="7.6" imdbID="tt0709059" />
   <result Title="The Nox" Released="1997-09-12" Episode="7" imdbRating="8.2" imdbID="tt0709194" />
   <result Title="Brief Candle" Released="1997-09-19" Episode="8" imdbRating="7.5" imdbID="tt0709052" />
   <result Title="Thor's Hammer" Released="1997-09-26" Episode="9" imdbRating="8.2" imdbID="tt0709209" />
   <result Title="The Torment of Tantalus" Released="1997-10-03" Episode="10" imdbRating="8.4" imdbID="tt0709205" />
   <result Title="Bloodlines" Released="1997-10-10" Episode="11" imdbRating="7.3" imdbID="tt0709051" />
   <result Title="Fire and Water" Released="1997-10-17" Episode="12" imdbRating="7.2" imdbID="tt0709091" />
   <result Title="Hathor" Released="1997-10-24" Episode="13" imdbRating="7.6" imdbID="tt0709101" />
   <result Title="Singularity" Released="1997-10-31" Episode="14" imdbRating="7.8" imdbID="tt0709172" />
   <result Title="Cor-ai" Released="1998-01-23" Episode="15" imdbRating="7.3" imdbID="tt0709061" />
   <result Title="Enigma" Released="1998-01-30" Episode="16" imdbRating="8.2" imdbID="tt0709079" />
   <result Title="Solitudes" Released="1998-02-06" Episode="17" imdbRating="8.3" imdbID="tt0709175" />
   <result Title="Tin Man" Released="1998-02-13" Episode="18" imdbRating="7.8" imdbID="tt0709212" />
   <result Title="There But for the Grace of God" Released="1998-02-20" Episode="19" imdbRating="8.7" imdbID="tt0709207" />
   <result Title="Politics" Released="1998-02-27" Episode="20" imdbRating="6.3" imdbID="tt0709142" />
   <result Title="Within the Serpent's Grasp" Released="1998-03-06" Episode="21" imdbRating="8.6" imdbID="tt0709219" />
</root>

By Search

A simple search argument would be:

http://www.omdbapi.com/?s=matrix

This results in a list of different types of media with that name.

{  
   "Search":[  
      {  
         "Title":"The Matrix",
         "Year":"1999",
         "imdbID":"tt0133093",
         "Type":"movie",
         "Poster":"http://ia.media-imdb.com/images/M/MV5BMTkxNDYxOTA4M15BMl5BanBnXkFtZTgwNTk0NzQxMTE@._V1_SX300.jpg"
      },
      {  
         "Title":"The Matrix Reloaded",
         "Year":"2003",
         "imdbID":"tt0234215",
         "Type":"movie",
         "Poster":"http://ia.media-imdb.com/images/M/MV5BMjA0NDM5MDY2OF5BMl5BanBnXkFtZTcwNzg5OTEzMw@@._V1_SX300.jpg"
      },
      {  
         "Title":"The Matrix Revolutions",
         "Year":"2003",
         "imdbID":"tt0242653",
         "Type":"movie",
         "Poster":"http://ia.media-imdb.com/images/M/MV5BMTkyNjc4NTQzOV5BMl5BanBnXkFtZTcwNDYzMTQyMQ@@._V1_SX300.jpg"
      },
      {  
         "Title":"The Matrix Revisited",
         "Year":"2001",
         "imdbID":"tt0295432",
         "Type":"movie",
         "Poster":"http://ia.media-imdb.com/images/M/MV5BMTIzMTA4NDI4NF5BMl5BanBnXkFtZTYwNjg5Nzg4._V1_SX300.jpg"
      },
      {  
         "Title":"Enter the Matrix",
         "Year":"2003",
         "imdbID":"tt0277828",
         "Type":"game",
         "Poster":"http://ia.media-imdb.com/images/M/MV5BMjA4NTYwNjk0M15BMl5BanBnXkFtZTgwODk3MDMwMTE@._V1_SX300.jpg"
      },
      {  
         "Title":"The Matrix: Path of Neo",
         "Year":"2005",
         "imdbID":"tt0451118",
         "Type":"game",
         "Poster":"http://ia.media-imdb.com/images/M/MV5BYWM2ZWU5MDUtYTU2ZS00ZDFmLWIyNGEtNWZkMjRmZjI2YzMzXkEyXkFqcGdeQXVyMTA1OTEwNjE@._V1_SX300.jpg"
      },
      {  
         "Title":"CR: Enter the Matrix",
         "Year":"2009",
         "imdbID":"tt1675286",
         "Type":"game",
         "Poster":"http://ia.media-imdb.com/images/M/MV5BMTExMzY3NTQ1NjleQTJeQWpwZ15BbWU3MDAyMjk2NzM@._V1_SX300.jpg"
      },
      {  
         "Title":"Armitage III: Dual Matrix",
         "Year":"2002",
         "imdbID":"tt0303678",
         "Type":"movie",
         "Poster":"http://ia.media-imdb.com/images/M/MV5BOTUwOTY3Mjg1MF5BMl5BanBnXkFtZTcwODI2MTAyMQ@@._V1_SX300.jpg"
      },
      {  
         "Title":"Sex and the Matrix",
         "Year":"2000",
         "imdbID":"tt0274085",
         "Type":"movie",
         "Poster":"N/A"
      },
      {  
         "Title":"Buhera mátrix",
         "Year":"2007",
         "imdbID":"tt0970173",
         "Type":"movie",
         "Poster":"N/A"
      }
   ],
   "totalResults":"87",
   "Response":"True"
}

Poster API

Searching through the poster API requires a key which is obtained by donating to the developer. A simple search is done by the following GET request which looks similar to the requests shown in the above examples.^[5]

http://img.omdbapi.com/?apikey=%5Bkey%5D&t=frozen

This returns the poster for the movie Frozen. File:Frozen (2013 film) poster.jpg

Applications

Ruby Wrapper

Several ruby gems are available to access the OMDb API like omdb, omdbapi. A simple code^[6] of how to use omdbapi gem is shown below:

require 'omdbapi'

game_of_thrones = OMDB.title('Game of Thrones')
# => {:title=>"Game of Thrones", :year=>"2011", :rated=>"TV-MA", :released=>"17 Apr 2011", :runtime=>"1 h", :genre=>"Adventure, Drama, Fantasy", :director=>"N/A", :writer=>"David Benioff, D.B. Weiss", :actors=>"Peter Dinklage, Lena Headey, Maisie Williams, Emilia Clarke", :plot=>"Seven noble families fight for control of the mythical land of Westeros.", :poster=>"http://ia.media-imdb.com/images/M/MV5BNTY2MzAxNzM0Ml5BMl5BanBnXkFtZTcwNDA0MDkxOQ@@._V1_SX300.jpg", :imdb_rating=>"9.4", :imdb_votes=>"382,638", :imdb_id=>"tt0944947", :type=>"series", :response=>"True"} 
game_of_thrones.title # => "Game of Thrones"
game_of_thrones.year  # => "2011"
game_of_thrones.rated # => "TV-MA"

Python Wrapper

omdb.py is the python wrapper for OMDb API. Simple code^[7] to use this wrapper is shown below:

import omdb

movie = omdb.title('True Grit')
movie.title == 'True Grit'
movie['title'] == 'True Grit'

search = omdb.search('True Grit')
search[0].title == 'True Grit'

R Wrapper

There is a R package to access OMDb API. Simple code^[8] to use this package is shown below:

devtools::install_github("hrbrmstr/omdbapi")
library(dplyr)
library(pbapply)
 
search_by_title("Captain America")

Other tools

There are several other tools on the web that perform the same or similar operation of exposing media details to a user. A preliminary list of these can be found below.^[9]

Rotten Tomatoes API ^[10]
IMDB We Make Sites ^[11]
Movie Poster Db^[12]
My API Films ^[13]
Cinemalytics ^[14]

References

^ ^a ^b ^c "OMDb". Retrieved 2016-09-14.
^ "The Linked Data Mining Challenge 2015" (PDF). KNOW@ LOD. 2015.
^ "OMDb API - The Open Movie Database". www.omdbapi.com. Retrieved 2016-09-14.
^ "How to get data from OMDb API web service". stackoverflow.com. Retrieved 2016-09-14.
^ "Given an IMDB movie id, how do I programmatically get its poster image?". stackoverflow.com. Retrieved 2016-09-14.
^ "Ruby gem omdbapi". GitHub. Retrieved 2016-09-14.
^ "Python Wrapper omdb.py". GitHub. Retrieved 2016-09-14.
^ "R Package to access the Open Movie Database (OMDB) API". 2015-07-10. Retrieved 2016-09-14.
^ "What is the best movie database api? - Quora". www.quora.com. Retrieved 2016-09-14.
^ "Rotten Tomatoes API - API Overview". developer.rottentomatoes.com. Retrieved 2016-09-14.
^ "IMDb JSON API by Martin Ivanov". 2016-09-14.
^ "ErikSchierboom/MoviePosterDb". GitHub. Retrieved 2016-09-14.
^ "MyAPIFilms, IMDB API, IMDB Web Service". www.myapifilms.com. Retrieved 2016-09-14.
^ "Cinemalytics Developer API - The Bollywood Movie Database". developers.cinemalytics.com. Retrieved 2016-09-14.

[:0-1] "OMDb". Retrieved 2016-09-14.

[2] "The Linked Data Mining Challenge 2015" (PDF). KNOW@ LOD. 2015.

[3] "OMDb API - The Open Movie Database". www.omdbapi.com. Retrieved 2016-09-14.

[4] "How to get data from OMDb API web service". stackoverflow.com. Retrieved 2016-09-14.

[5] "Given an IMDB movie id, how do I programmatically get its poster image?". stackoverflow.com. Retrieved 2016-09-14.

[6] "Ruby gem omdbapi". GitHub. Retrieved 2016-09-14.

[7] "Python Wrapper omdb.py". GitHub. Retrieved 2016-09-14.

[8] "R Package to access the Open Movie Database (OMDB) API". 2015-07-10. Retrieved 2016-09-14.

[9] "What is the best movie database api? - Quora". www.quora.com. Retrieved 2016-09-14.

[10] "Rotten Tomatoes API - API Overview". developer.rottentomatoes.com. Retrieved 2016-09-14.

[11] "IMDb JSON API by Martin Ivanov". 2016-09-14.

[12] "ErikSchierboom/MoviePosterDb". GitHub. Retrieved 2016-09-14.

[13] "MyAPIFilms, IMDB API, IMDB Web Service". www.myapifilms.com. Retrieved 2016-09-14.

[14] "Cinemalytics Developer API - The Bollywood Movie Database". developers.cinemalytics.com. Retrieved 2016-09-14.

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]

[11]

[12]

[13]

[14]