OMDb API - Assignment 6

Author

Diego Valdes

Introduction

This document’s purpose is to walk-through the OMDb (Open Movie Database) API. The OMDb API allows users to retrieve “movie information”. This includes their title, release year, genre, etc.

This API is very helpful for anyone interested in analyzing movie data, building data sets for research, and anything else related to movies and TV.

Setting Up the API

Before we’re able to use the OMDb API, we first need to obtain an API key:

  1. Visit https://www.omdbapi.com/apikey.aspx
  2. Select the FREE! account option
  3. Check your email for your API key
api_key <- "YOUR_API_KEY"

First API Call: Retrieving Information for a Specific Movie

Now that we have our API key, we can create a function to make an OMDb API GET request:

OMDb_api_GET_url <-
  function(api_key, IMDb_id){
    
    OMDb_endpoint <- "https://www.omdbapi.com/"
    
    api_key <- paste("?apikey=", api_key, sep = "")
    
    IMDb_id <- paste("&i=", IMDb_id, sep = "")
    
    OMDb_api_GET <- 
      paste(OMDb_endpoint, api_key, IMDb_id, sep = "")
    
    return(OMDb_api_GET)
  }

This function requires an API key and the IMDb ID of any movie.

We can test it out using Spider-Man: Into the Spider-Verse’s IMDb ID:

into_the_spiderverse <- OMDb_api_GET_url(api_key, "tt4633694")
into_the_spiderverse # Copy and paste this link into a browser
[1] "https://www.omdbapi.com/?apikey=YOUR_API_KEY&i=tt4633694"

Or with Kung Fu Panda 2’s IMDb ID:

kung_fu_panda_2 <- OMDb_api_GET_url(api_key, "tt1302011")
kung_fu_panda_2 # Copy and paste this link into a browser
[1] "https://www.omdbapi.com/?apikey=YOUR_API_KEY&i=tt1302011"

We can create another function to turn the URL arguments directly into a data-frame:

OMDb_api_GET_df <-
  function(api_key, IMDb_id){
    
    OMDb_api_url <- OMDb_api_GET_url(api_key, IMDb_id)
    
    OMDb_df <-
      OMDb_api_url %>% 
      GET() %>% 
      content(as = "text",
              encoding = "UTF-8") %>% 
      fromJSON() %>% 
      as.data.frame()
    
    return(OMDb_df)
  }

We can test it out again with the same 2 movies:

kung_fu_panda_2 <- OMDb_api_GET_df(api_key, "tt1302011")
kung_fu_panda_2
  Response            Error
1    False Invalid API key!
into_the_spiderverse <- OMDb_api_GET_df(api_key, "tt4633694")
into_the_spiderverse
  Response            Error
1    False Invalid API key!

Due to the “Ratings” field having a nested list, this function will produce multiple rows of what at first glance appears to be the exact same thing.

This is not the case. If you look closely you will see that each row of the movie has different values under the “Ratings.Source” and “Ratings.Value” columns. We could utilize use_series() to extract the singular field, but that would leave us with barely any information.

This is why instead of retrieving information from a singular movie, let’s retrieve it from multiple!

Second API Call: Retrieving information from Multiple Movies

Let’s make a new function to make an OMDb API GET request, except let’s slap a 2 at the end of it’s name:

OMDb_api_GET_url_2 <-
  function(api_key, movie_search){
    
    OMDb_endpoint <- "https://www.omdbapi.com/"
    
    api_key <- paste("?apikey=", api_key, sep = "")
    
    movie_search <- paste("&s=", movie_search, sep = "")
    
    OMDb_api_GET <- 
      paste(OMDb_endpoint, api_key, movie_search, sep = "")
    
    return(OMDb_api_GET)
  }

This function requires an API key and any word of your choosing.

Next, let’s slap a 2 at the end of the GET_df function as well:

OMDb_api_GET_df_2 <-
  function(api_key, movie_search){
    
    OMDb_api_url <- OMDb_api_GET_url_2(api_key, movie_search)
    
    OMDb_df <-
      OMDb_api_url %>% 
      GET() %>% 
      content(as = "text",
              encoding = "UTF-8") %>% 
      fromJSON() %>% 
      use_series(Search)
    
    return(OMDb_df)
  }

This function does the same as the previous one, except it takes in movie_search as a parameter and utilizes use_series() instead of as.data.frame()

We can test it out using the keyword “Spider-Man”:

spiderman_movies <- OMDb_api_GET_df_2(api_key, "Spider-Man")
spiderman_movies
NULL

Since we’re using the parameter &s= instead of &t=, the OMDb API returns less information than it would if we were searching for a specific movie. This is why having functions for both parameter types is very helpful.

For example, I could look for movies using the keyword “Spider-Man”, extract the IMDb id of one of the movies returned, and plug that value into the other function to retrieve information for that specific film:

spiderman_id_1 <- spiderman_movies$imdbID[1]
spiderman_df_1 <- OMDb_api_GET_df(api_key, spiderman_id_1)