Using the OMDb API

Introduction to the OMDb API

The Open Movie Database (OMDb) API is a RESTful web service providing access to a vast database of movie, TV show, and video game information. It allows developers to retrieve metadata (e.g., titles, release dates, plot summaries, cast and crew details, and ratings) through simple HTTP requests. The API returns data in JSON format and offers a free tier with usage limitations upon obtaining an API key.

Developers and website owners utilize the OMDb API for building movie and TV show information websites and apps, creating recommendation systems, and managing personal media libraries. It eliminates the the need for manual data curation, providing up-to-date and comprehensive information directly to applications.

Obtaining Your API Key

Let’s walk through the steps for setting up the OMDb API key. First, open your web browser and go to the official OMDb API website: https://www.omdbapi.com/

Click the button called “API Key” in the navigation menu, which directs you to the API key registration page. Choose the account type you prefer and provide your email address. Once submitted, your API key will be sent your email. This might take a few moments, so be patient and check your spam or junk folder if you don’t see it in your inbox.

Accessing the API in R

In any URL for the API, the title of the movie/show/game and your API key are required. The rest of the parameters are optional. The following code will run you through how to build the most basic URL for the OMDb API.

First, you load the following R packages: tidyverse for general data manipulation, jsonlite for converting JSON responses into data frames, magrittr for using the pipe operator (%>%) to streamline operations on list objects, and httr for making HTTP requests to interact with web services.

library(tidyverse) # All the tidy things
library(jsonlite)  # Converting json data into data frames
library(magrittr)  # Extracting items from list objects using piping grammar
library(httr)      # Interacting with HTTP verbs
library(knitr)     # Pretty HTML tables

The create_url function takes two arguments: the title you’re searching for and your unique OMDb API key.

create_url <- 
  
  # For the URL to run, there must be a title and API key included. 
  # The API key must go after the title
  function(title_to_search_for, apikey, program_type, year_released) {
    
    base_url <- "https://www.omdbapi.com/?"
    
    title_to_search_for <- paste("s=",title_to_search_for, sep="")
    apikey <- paste("&apikey=", apikey, sep= "")
    
    # Program types include movie, series, or episode.
    if(missing(program_type)) {
      program_type <- ""
    } else {
      program_type <- paste("&type=",program_type, sep = "")    
    }
    
    if(missing(year_released)) {
      year_released <- ""
    } else {
      year_released <- paste("&y=",year_released, sep = "")    
    }
    
    final_url <- 
      paste(base_url, title_to_search_for, apikey, program_type, year_released, sep="")
    
    return(final_url)
}

The following code combines the URL function into a function that takes a URL and puts it into a data frame.

create_url_df <- 
  
  # For the URL to run, there must be a title and API key included. 
  # The API key must go after the title
  function(title_to_search_for, apikey, program_type, year_released) {

    base_url <- "https://www.omdbapi.com/?"
        
    title_to_search_for <- paste("s=",title_to_search_for, sep="")
    apikey <- paste("&apikey=", apikey, sep= "")
        
        # Program types include movie, series, or episode.
    if(missing(program_type)) {
      program_type <- ""
    } else {
      program_type <- paste("&type=",program_type, sep = "")    
    }
        
    if(missing(year_released)) {
      year_released <- ""
    } else {
      year_released <- paste("&y=",year_released, sep = "")    
    }
        
    final_url <- 
      paste(base_url, title_to_search_for, apikey, program_type, year_released, sep="")
    
    omdb_df <- 
      final_url %>% 
      GET() %>% 
      content(as = "text",
              encoding = "UTF-8") %>% 
      fromJSON() %>% 
      use_series(Search)
    
    return(omdb_df)
    
  }

This example will load the information about all TV shows with the title “Twilight” somewhere in the name that was released in 2010.

Title	Year	imdbID	Type	Poster
The Twilight Saga - Eclipse: Red Carpet Premiere BUZZscene Interviews	2010–2013	tt16409406	series	N/A
The Twilight Saga - Eclipse: Taylor Lautner - Buzzine Interviews	2010–2013	tt16409628	series	N/A