Shows

In this guide we will go over the primary resource of the Streaming Availability API, shows, and how you can use it for your specific use-cases.

Show object

Show object is the main entity in the Streaming Availability API. It represents either a movie or a series, and it contains all the necessary information regarding it, such as the title, description, release year, images, seasons, episodes, and most importantly, the streaming availability information.

Here you can see some examples of the Show object and the fields it contains:

Via show object you can create visually and informationally rich experiences for your users. You can display the general information about the show, such as the title, description, genres, release year etc. You can also use high quality images based on your needs. Shows come with 4 different image types. Vertical posters (which is basically a regular movie/series poster), horizontal posters (similar to how Netflix displays their shows), horizontal backdrops (which do not contain any text, and are usually used as a background image), and vertical backdrops (which are similar to horizontal backdrop images, but are vertical, ideal for mobile devices).

And of course you can display the streaming availability information, which includes deep links into streaming apps, including links for individual seasons and episodes, available subtitles and audio languages, supported maximum video qualities, expiry dates, streaming option type (e.g. if it's available via a subscription plan such as Netflix, or if it's available for rent or purchase on platforms like Amazon Prime Video, or is it available via addons such as Apple TV and Amazon Prime Video channels), price information (if the streaming option is either for rent or purchase), and more.

Fetching shows

There are multiple ways to fetch shows from the Streaming Availability API. You can fetch them by using IMDb or TMDB ids, by searching for them via their titles, or by using various filters such as genres, release years, streaming catalogs and more.

Here we will take a look at some of the common use-cases and the best practices for each.

You already have a local database of shows

If you already have a local database of shows with either TMDB or IMDb ids, and looking to enrich it with the data from the Streaming Availability API, you can use Get a show endpoint to fetch the shows and their streaming availability information by using their IMDb or TMDB ids.

If you are only interested in the streaming availability information for a single country, you can specify the country code in the country query parameter. This way the show object will only contain the streaming availability information for the specified country, thus reducing the bandwidth usage and speeding up the response time.

Here's an example of fetching "The Godfather" via its IMDb id and only fetching the streaming availability information for the US:

curl -G https://streaming-availability.p.rapidapi.com/shows/tt0068646 \
	-H "X-RapidAPI-Key: {YOUR_API_KEY}" \
	--data-urlencode country="us"

If instead, you are interested in fetching the streaming availability information globally, you can simply omit the country query parameter:

curl -G https://streaming-availability.p.rapidapi.com/shows/tt0068646 \
	-H "X-RapidAPI-Key: {YOUR_API_KEY}"

This way you will get the streaming availability information for all the countries where the show is available.

You would like to create a database from scratch

If you are starting from scratch and would like to create a local database of shows from the Streaming Availability API, you can use Search shows by filters endpoint to fetch shows based on various filters.

As an example, if you'd like to fetch all the shows that are available on Netflix in the US, you can send a request like this:

curl -G https://streaming-availability.p.rapidapi.com/shows/search/filters \
	-H "X-RapidAPI-Key: {YOUR_API_KEY}" \
	--data-urlencode country="us" \
	--data-urlencode catalogs="netflix"

This request will return a list of shows that are available on Netflix in the US. Of course, not all the shows will be returned in a single response. The responses for this endpoint are paginated. However, by using the auto pagination feature of the official client libraries, you can easily fetch all the shows that match the specified filters.

If you are interested in fetching all the shows available in a country, you can simply omit the catalogs query parameter. You can also further filter the shows based on the genres, release years, and also prefer to only fetch either movies or series.

Here's an example of fetching all the science fiction movies available in the United Kingdom across all the streaming services:

curl -G https://streaming-availability.p.rapidapi.com/shows/search/filters \
	-H "X-RapidAPI-Key: {YOUR_API_KEY}" \
	--data-urlencode country="gb" \
	--data-urlencode show_type="movie" \
	--data-urlencode genres="scifi"

Keeping your local database up-to-date

Of course, once you created/updated your local database with the shows from the Streaming Availability API, ideally you would like to keep it up-to-date as well. One way to do this is periodically fetching the shows. However, since the changes in the streaming availability information are frequent, this way of updating the local database is not the most efficient way to keep up with latest releases. This is why we have our Get changes endpoint.

This endpoint simply returns the list of changes occurred in a streaming catalog within a specified time range, as well as the up-to-date details of the shows affected by those changes. For more information, you can visit the Changes pages.

I'd prefer to not deal with self-hosted databases

If you want to create feature-rich applications without dealing with self-hosted databases, the Streaming Availability API offers powerful endpoints so that you can get any necessary information on-the-fly.

Here are some example feature ideas and how you can implement them using the Streaming Availability API:

• Where to watch: Let's say we want to create a feature that allows users to search for a show via its title and get the list of available streaming options (along with the deep links) in their country. To achieve this, you can use the Search shows by title endpoint. Here's an example of fetching the streaming availability information for "The Godfather" in the US:
  cURLGoTypeScriptJavaScript

  curl -G https://streaming-availability.p.rapidapi.com/shows/search/title \
  	-H "X-RapidAPI-Key: {YOUR_API_KEY}" \
  	--data-urlencode title="The Godfather" \
  	--data-urlencode country="us"

  CopyCopied!
• Movie search engine: Using the Search shows by filters endpoint, you can create a powerful movie (or series) search engine that allows users to filter movies based on genres, release years, streaming platforms and keywords. Moreover, you can also provide multiple ordering options, such as ordering by popularity, rating, release date etc. Here's an example of fetching all the zombie action movies from 2000s available on either Netflix or Hulu in the US, ordered by their ratings:
  cURLGoTypeScriptJavaScript

  curl -G https://streaming-availability.p.rapidapi.com/shows/search/filters \
  	-H "X-RapidAPI-Key: {YOUR_API_KEY}" \
  	--data-urlencode country="us" \
  	--data-urlencode catalogs="netflix,hulu" \
  	--data-urlencode show_type="movie" \
  	--data-urlencode genres="action" \
  	--data-urlencode keyword="zombie" \
  	--data-urlencode year_min="2000" \
  	--data-urlencode year_max="2009" \
  	--data-urlencode order_by="rating"

  CopyCopied!
• What's new/expiring/upcoming on Netflix: Using Get changes endpoint, you can create a feature that shows the latest shows added to a specific streaming service, the shows that are about to expire, and the shows that are coming soon. Here's an example of fetching the latest releases in the Netflix catalog in the US:
  cURLGoTypeScriptJavaScript

  curl -G https://streaming-availability.p.rapidapi.com/changes \
  	-H "X-RapidAPI-Key: {YOUR_API_KEY}" \
  	--data-urlencode country="us" \
  	--data-urlencode change_type="new" \
  	--data-urlencode item_type="show" \
  	--data-urlencode catalogs="netflix"

  CopyCopied!
  You can change the change_type query parameter to expiring or upcoming to get the shows that are about to expire or coming soon. You can also change the item_type query parameter to season or episode to get the latest seasons or episodes.
• What's popular in the UK: Using the Search shows by filters endpoint, you can create a feature that shows the most popular shows in a country. Here's an example of fetching the most popular shows of the past week in the United Kingdom:
  cURLGoTypeScriptJavaScript

  curl -G https://streaming-availability.p.rapidapi.com/shows/search/filters \
  	-H "X-RapidAPI-Key: {YOUR_API_KEY}" \
  	--data-urlencode country="gb" \
  	--data-urlencode order_by="popularity_1week"

  CopyCopied!

Streaming Options

Before we finish, let's take a closer look at the streaming availability information provided by the Streaming Availability API for the shows.

All the streaming availability info is contained within the streamingOptions field of the Show object. Under this field, you can find the list of streaming options available, mapped by the country code.

The individual streaming availability information for seasons and episodes can be found within the streamingOptions field of the season and episode objects respectively. These streaming options contain the same information as the show streaming options, but are specific to the season or episode.

Let's take a look at some sample streaming options and the information they contain:

The examples above contain 3 different streaming option types.

Streaming option for Netflix is a subscription type, which means that the show is available via a paid subscription plan. Rest of the fields contain the information about the streaming option, such as the deep link, video link, video quality, subtitles, audio languages and timestamp of the date that this streaming options was first detected.

Streaming option of Rental is a rent type, which means that the show is available for rental. Here, you can see the price information under price field which is $3.79 in this case. Price field is only populated when the streaming option is either rent or buy type. Note that for some series and seasons, the price information might be omitted even if the streaming option is rent or buy type. This means that this series or episode is rentable or buyable, but not as a whole. As an example, if a series has a buy type streaming option without price information, this means that you cannot buy the whole series at once, but you can buy individual seasons or episodes. In these cases, the price information will be provided under the streaming options of the individual seasons or episodes.

Finally, we have the Addon streaming option, which is an addon type. In this case, the show is available via an addon on Hulu called "Paramount+ with Showtime". The extra addon field contains the information about the addon itself. In this example you can also see that this streaming option is expiring soon, and the timestamp of the expiry date is provided under expiresOn field. expiresSoon field is set as true for all the streaming options that are set to expire within a month. Note that, sometimes expiresOn field might be populated even if expiresSoon field is false. For all the streaming options with a known expiry date, the expiresOn field will be populated even if the expiry date is far in the future. There might be also cases where the exact expiry date is not known, but it's known that the streaming option is about to expire soon. In these cases expiresSoon field will be set as true but expiresOn field will be omitted.