Ryan Springer - OMDb API

Author

Ryan Springer

What is the OMDb API?

The Open Movie Database (OMDb) is a free online database of information about movie, TV shows, and episodes. Its API lets you ask for information from R. For any title, you can get the release year, runtime, genre, director, actors, plot summary, poster link, box officer earnings, and ratings from IMDb.

Why would someone use it?

It is free and simple. A free key allows 1,000 requests per day. It also uses the same style of API we learned in class. It is also great for movie analysis as you could do things like compare ratings across a movie franchise, check whether longer movies earn more at the box office, or add movie details to a dataset you already have.

Setting up the API

Get a free key

  1. Go to https://www.omdbapi.com/apikey.aspx and choose FREE
  2. Enter your name and email, then click Submit
  3. Check you email and click the activation link
  4. Test it in your browser by pasting this URL into your browser: https://www.omdbapi.com/?apikey=<YOUR_API_KEY_HERE>&t=Toy%20Story
  5. In R, load the packages and save your key
library(tidyverse)
library(jsonlite)
library(magrittr)
library(httr)

omdb_key <- <YOUR_API_KEY_HERE>

Demonstration

One Movie

Every request starts with https://www.ombdapi.com/? plus your key. Other parameters are added with &, such as t= (title), i= (IMDb ID), s= (search), type=, and page=.

omdb_api_url <- paste("https://www.omdbapi.com/?apikey", omdb_key, "&t=Toy%20Story&y=1995", sep = "")

toy_story <- 
  omdb_api_url %>%
  GET() %>% 
  content(as = "text", encoding = "UTF-8") %>% 
  fromJSON()

toy_story %>% use_series(Title)

A function for movie details

omdb_title_df <- 
  function(api_key, imdb_id) {
    omdb_url <- paste("https://www.omdbapi.com/?apikey=", api_key,
                      "&i=", imdb_id, sep = "")
    title_df <- 
      omdb_url %>% 
      GET() %>% 
      content(as = "text", encoding = "UTF-8") %>% 
      fromJSON() %>% 
      extract(c("imdbID", "Title", "Year", "Runtime", "imdbRating")) %>% 
      as.data.frame()
    return(title_df)
  }

Looping through search results

Search results come 10 per page, so a look collects every page. My full R scrip then looped through every movie with omdb_title_df(), cleaned the numbers with str_remove and as.numeric() and saved a CSV.

search_results <- data.frame()

for (i in 1:total_pages) {
  search_results <- 
    omdb_search_df(omdb_key, "Toy Story", "movie", page = i) %>% 
    bind_rows(search_results)
  Sys.sleep(1)
}

Results

movie_details <- read_csv("omdb_movie_details.csv")

movie_details %>% 
  filter(!is.na(imdbRating), imdbVotes >= 1000) %>% 
  mutate(label = paste(Title, " (", Year, ")", sep = "")) %>% 
  ggplot(aes(x = imdbRating, y = reorder(label, imdbRating))) +
  geom_col(fill = "blue") +
  scale_x_continuous(limits = c(0, 10)) +
  labs(title = "IMDb Ratings of \"Toy Story\" Movies",
       x = "IMDb Rating (out of 10)", y = NULL)

Among movies with at least 1,000 IMDb votes, Toy Story 3 (2010) and the original Toy Story (1995) have the highest ratings, both around 8.3 out of 10. Every title on the chart is rated above 7, which shows the franchise, including its shorts and TV specials, is well liked.