Widget

Streaming Availability API offers a plug-and-play widget for React apps that allows you to easily embed the world-wide streaming availability information within your app. It works with any React framework that supports "use server" directive such as Next.js.

Getting Started

API Key

To use the widget, you need to have an API key. If you don't have one yet, you can follow our Authorization guide to get one.

Installation

If you already have a React app, you can install the widget by running:

npm install react-streaming-availability

If you don't have a React app yet, you can use our Next.js demo as a starting point.

Configuration

To finalize the setup, you need to provide the API key to the widget. The widget automatically fetches the API key from the environment variable STREAMING_AVAILABILITY_API_KEY.

If you are using Next.js, you can add the API key to the .env file in your project root in the following format:

STREAMING_AVAILABILITY_API_KEY=your-api-key

Components

The widget provides 2 main components: Row and Grid.

Row

The Row component displays a horizontal list of posters and a highlighted streaming option with a streaming service catalog logo and a deep link to the shows' page inside the streaming service catalog.

It provides horizontal scrolling and fetches more posters as the user scrolls.

import {newTopShowsSource, Row} from "react-streaming-availability";

<Row
	title="Netflix US Top 10 Series"
	source={newTopShowsSource(
		{
			country: "us",
			showType: "series",
			service: "netflix",
		}
	)}
/>

Grid

The Grid component displays a grid of posters with a title and a streaming option and optionally provides infinite scrolling as the user scrolls down.

import {newTitleSearchSource, Grid} from "react-streaming-availability";

<Grid
	source={newTitleSearchSource(
		{
			country: "us",
			title: "Harry Potter",
			limit: 8,
		}
	)}
/>

Sources

A source is an object that specifies the data to be displayed by the components.

There are many sources available, and you can mix them together to create a richer user experiences.

Top Shows

TopShowsSource fetches the top shows for a specific country and service; and it uses Get Top Shows endpoint underneath, thus it supports the same set of services and parameters.

import {newTopShowsSource, Row} from "react-streaming-availability";

<Row
	title="Prime Video Germany Top Movies & Series"
	source={newTopShowsSource(
		{
			country: "de",
			service: "prime",
		}
	)}
/>

Title Search

TitleSearchSource fetches the titles that match with a query. It uses Search Shows by Title endpoint underneath, thus it supports the same set of parameters with the addition of limit parameter to limit the maximum number of posters to be displayed.

import {newTitleSearchSource, Row} from "react-streaming-availability";

<Row
	title="Harry Potter Movies"
	source={newTitleSearchSource(
		{
			country: "us",
			showType: "movie",
			title: "Harry Potter",
			limit: 8,
		}
	)}
/>

Filtered Search

FilteredSearchSource fetches a list of movies and series based on the provided filters.

It uses Search Shows by Filters endpoint underneath, thus it supports the same set of parameters with the addition of limit parameter to limit the maximum number of posters to be displayed.

import {newFilteredSearchSource, Row} from "react-streaming-availability";

<Row
	title="Highest-Rated Science Fiction Movies"
	source={newFilteredSearchSource({
		country: "us",
		genres: ["scifi"],
		showType: "movie",
		orderBy: "rating",
		orderDirection: "desc",
		limit: 100,
	})}
/>

Id Set

IdSetSource fetches a list of movies and series based on the provided IMDb/TMDB or Streaming Availability IDs. Highlighted streaming option is chosen according to the provided country.

It uses Get a Show endpoint underneath.

import {newIdSetSource, Row} from "react-streaming-availability";

<Row
	title="Mission Impossible Movies"
	source={
		newIdSetSource({
			country: "us",
			ids: ["tt0117060", "tt0120755", "tt0317919", "tt1229238", "tt2381249", "tt4912910", "tt9603212"],
		})
	}
/>

Changes

ChangesSource fetches the shows according to recent or future changes in a given set of streaming catalogs. It uses Get Changes endpoint underneath, thus it supports the same set of parameters, with the addition of limit parameter to limit the maximum number of posters to be displayed.

Via this source, you can create "What's New", "What's Leaving", or "Coming Soon" sections.

import {newChangesSource, Row} from "react-streaming-availability";

<Row
	title="Expiring Movies & Series in the US"
	source={newChangesSource({
		country: "us",
		changeType: "expiring",
		includeUnknownDates: false,
		itemType: "show",
		limit: 100,
	})}
/>

Sequential Multi Source

SequentialMultiSource fetches the shows from multiple sources sequentially. Sequential here means that it fetches the shows from the first source until it uses all the shows from that source, then it moves to the next source.

import {newSequentialMultiSource, newTopShowsSource, Row} from "react-streaming-availability";

<Row
	title="Top Movies on Netflix & Prime Video in Germany"
	source={
		newSequentialMultiSource({
			sources: [
				newTopShowsSource({
					country: "de",
					service: "netflix",
					showType: "movie",
				}),
				newTopShowsSource({
					country: "de",
					service: "prime",
					showType: "movie",
				}),
			],
		})
	}
/>

Round-Robin Multi Source

RoundRobinMultiSource fetches the shows from multiple sources in a round-robin fashion. Meaning, if there are 3 sources, it fetches the first show from the first source, the second show from the second source, the third show from the third source, the fourth show from the first source, and so on.

import {newRoundRobinMultiSource, newTopShowsSource, Row} from "react-streaming-availability";

<Row
	title="Top Movies on Netflix & Prime Video in Germany"
	source={
		newRoundRobinMultiSource({
			sources: [
				newTopShowsSource({
					country: "de",
					service: "netflix",
					showType: "movie",
				}),
				newTopShowsSource({
					country: "de",
					service: "prime",
					showType: "movie",
				}),
			],
		})
	}
/>

Random Multi Source

As you might guess by its name, RandomMultiSource fetches the shows from multiple sources randomly.

import {newRandomMultiSource, newTopShowsSource, Row} from "react-streaming-availability";

<Row
	title="Top Shows on Netflix & Prime Video & Apple TV+ in Germany"
	source={
		newRandomMultiSource({
			sources: [
				newTopShowsSource({
					country: "de",
					service: "netflix",
				}),
				newTopShowsSource({
					country: "de",
					service: "prime",
				}),
				newTopShowsSource({
					country: "de",
					service: "apple",
				}),
			],
		})
	}
/>

Customization

All the components are highly customizable in terms of behavior and styling. Let's look at some examples:

Poster Type

You can change the poster image type to horizontal or vertical for both Row and Grid components.

import {newFilteredSearchSource, Row} from "react-streaming-availability";

<Row
	title="Fantasy Movies on Netflix and Hulu"
	posterType="vertical"
	source={newFilteredSearchSource({
		country: "us",
		genres: ["fantasy"],
		showType: "movie",
		catalogs: ["netflix", "hulu.subscription"],
		orderBy: "popularity_1year",
		orderDirection: "desc",
	})}
/>

Priority Catalogs

If you want to prioritize some streaming service catalogs over others, you can provide a list of priorityCatalogs to the Row and Grid components.

Some sources already have an internal priority list (e.g. if you are trying to show Top 10 movies on Netflix, setting Hulu as a priority catalog won't have any effect), but for the sources that don't have an internal priority list, supplying a list of priorityCatalogs will make sure that the deep link and catalog logo will belong to one of the priority catalogs (the first catalog taking the highest priority), if applicable.

For example, when displaying a movie, if it's available both on Netflix and Prime Video, and you set Netflix as the priority catalog, the deep link and catalog logo will belong to Netflix.

import {newIdSetSource, Row} from "react-streaming-availability";

<Row
	title="Mission Impossible Movies"
	priorityCatalogs={[
		{
			service: "netflix",
		}
	]}
	source={
		newIdSetSource({
			country: "us",
			ids: ["tt0117060", "tt0120755", "tt0317919", "tt1229238", "tt2381249", "tt4912910", "tt9603212"],
		})
	}
/>

Styling

Finally, you can also customize the styling of the components by providing styling props.

import {newFilteredSearchSource, Row} from "react-streaming-availability";

<Row
	arrowColor="black"
	arrowButtonBaseStyle={{
		backgroundColor: "white",
	}}
	titleDivProps={{
		style: {
			color: "lightgray",
		}
	}}
	posterContainerAnchorProps={{
		style: {
			backgroundColor: "white",
		}
	}}
	catalogLogoType="light"
	rootDivProps={{
		style: {
			backgroundColor: "darkred",
			borderRadius: "32px",
		}
	}}
	title="Music-Related Shows"
	source={newFilteredSearchSource({
		country: "us",
		genres: ["music"],
		orderBy: "popularity_1year",
		orderDirection: "desc",
	})}
/>

Reference

For full reference, you can click here.