IMDb API Tutorial

The IMDB, or the Internet Movie Database is an online repository of movies, films, television & web series and more. You can visit the website and browse through its exhaustive source of information about the cast, the crew, plot summaries and trivia. Thankfully, all of this is also available as an API.

The IMDb API makes it easy to search and find information about movies and TV shows. It has an extensive set of API endpoints to query each aspect of a movie. In this tutorial, you will learn about the information that you can retrieve from the IMDb API. IMDb API is integrated with Rakuten RapidAPI so you can login to your account and access it using your universal subscription key.

In case you don’t have an account on Rakuten Rapid API, sign up now and get your universal API key to access the IMDb API and thousands of other APIs hosted on Rakuten Rapid API.

Overview of IMDb API

What’s the first thing that comes to your mind when you hear about an upcoming movie? The cast comprising of the actors and the actresses. The crew, consisting of the director, the writer, and maybe the cinematographer. You would also want to know the release date and get a summary about the plot. You can query all this and more with the IMDb API.

The IMDb API is organized into several specific endpoints that provide all the above information and more. To get a closer look, jump to the IMDb API console.

Check out the list of endpoints on the left side of the API console, and you can see how neatly it is organized in a way to query different aspects of a movie.

This is a good example of a well defined information architecture about a subject, which in this case, is a movie, a television show or a streaming entertainment video.

Since the endpoint list is extensive, a complete description of all the endpoints is a beyond the scope of this tutorial. However, we will cover the main endpoints which are in line with your curiosity questions when you hear about a new movie release.

Before you begin, take a look at the Pricing tab in the API console. The IMDB API has a freemium pricing model with a BASIC subscription tier that gives you 500 API calls free, per month. Make sure you opt for the BASIC subscription before you proceed with this tutorial further.

Working With IMDb API

Let’s take a look at some of the prominent endpoints of IMDb API which provide key information about a movie.

Be sure to subscribe to the API and keep the API console page open to test the endpoints that we are going to explain now.

Searching for a Movie Name

The “GET title/find” endpoint is used to search for a movie by its name. This endpoint accepts a string as the name of a movie or TV show to search for. It returns a list of all movies and shows which match the string, even if it is a partial match.

Select the “GET title/find” endpoint and try searching for “titanic”.

And the API response is somewhat like this.

Under the “results” key you can see a list of all the matching movies. The first one is the popular movie featuring  Leonardo DiCaprio & Kate Winslet. You can see their name inside the “principals” key.

Another important thing to remember about the search results is the id of each movie.

In the case of Titanic, the id is “/title/tt0120338/”. The string prefixed with “tt” followed by a number sequence is the unique identifier for this movie. The IMDb API uses this id to search for other information related to this movie.

So if you want to perform further queries on any movie, then you must take a note of the id. Now that we know the id of Titanic, let’s find out some more information about this movie.

Searching for a Movie Cast

After you know the movie name, the next logical thing is to know the cast. Although the “GET title/find” endpoint gives you the names of the leading actors, it does not provide the full list of cast.

To get the list of complete cast, you can use the “GET title/get-top-cast”. This endpoint takes the movie id as a parameter returns the cast list. So if you choose “GET title/get-top-cast” endpoint on the API console and feed in the id of the movie “Titanic”, this is what the request looks like.

Trigger the API and you will get a list of cast as follows.

What you see in the API response is a list of ids of cast. Similar to the movie id, each person also has an id starting with nm followed by a number.

In order to get the name and other details of the cast, you need to call another endpoint, “GET title/get-charname-list”. This endpoint takes in the movie id and cast id as parameter. Select this endpoint and enter the movie id of “Titanic” and the name id of the first item you got from the API response of “GET title/get-top-cast”.

You should now see some meaningful information about the cast.

Here you go. The API response contains the name of the cast along with information about the character in the movie. In this way, you can call this endpoint for all the name ids, and get individual information about them and their role in the movie.

Getting Information About Movie Crew

“GET title/get-top-crew” returns the list of crew,mainly the director and the writer for a movie id.

Let’s see what does it return for the crew of “Titanic”.

{

  "directors":[1 item

    0:{7 items

      "akas":[...]4 items

      "disambiguation":"I"

      "id":"/name/nm0000116/"

      "image":{...}4 items

      "legacyNameText":"Cameron, James (I)"

      "name":"James Cameron"

      "category":"director"

    }

  ]

  "writers":[1 item

    0:{10 items

      "akas":[...]4 items

      "disambiguation":"I"

      "id":"/name/nm0000116/"

      "image":{...}4 items

      "legacyNameText":"Cameron, James (I)"

      "name":"James Cameron"

      "category":"writer"

      "job":"written by"

      "writerCategoryBilling":1

      "writerTeamBilling":1

    }
  ]
}

You have your answer.

Wrapping Up

We have just covered the tip of the iceberg in this tutorial. Go ahead and try the IMDb API and search for your favorite movies. You can even retrieve information about awards, reviews, shooting locations and images and more. This is a complete treasure trove of data. You can build movie quizzes and perform data analytics to unearth useful information.

Also if you are looking to build apps around movies and entertainment then check out our other APIs related to movies.