Pagination

In this guide, we will look at how to work with paginated responses. Streaming Availability API uses cursor-based pagination to navigate through large sets of data. If you are using one of the official client libraries, you don't need to worry about pagination, since they provide auto-pagination out of the box.

Cursor

When you request a large list of objects, the API will return a subset of the objects and provide you with a boolean hasMore to let you know whether there are more objects to fetch, and if so, it will provide you with a nextCursor to use in the next request to fetch the next set of objects.

Let's imagine we are trying to fetch all the comedy movies available on Netflix US. This is how the first request would look like:

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" \
	--data-urlencode show_type="movie" \
	--data-urlencode genres="comedy"

And the response would look like this:

{
	"shows":  [
		...list of movies...
	],
	"hasMore": true,
	"nextCursor": "47196:A California Christmas: City Lights"
}

hasMore field is true, which means there are more movies to fetch. The nextCursor field contains the cursor to use in the next request to fetch the next set of movies. So, to fetch the next set of movies, you would make the same request, but with the cursor parameter set as the value of nextCursor:

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" \
	--data-urlencode show_type="movie" \
	--data-urlencode genres="comedy" \
	--data-urlencode cursor="47196:A California Christmas: City Lights"

We can keep making requests using the nextCursor until the hasMore field is false:

{
	"shows":  [
		...list of movies...
	],
	"hasMore": false
}

Auto Pagination

If you are using one of the official client libraries, you don't need to worry about pagination, you can simply use the auto-pagination feature provided by the client libraries.

Here is an example of how you would fetch the comedy movies available on Netflix US using the TypeScript client library with auto-pagination enabled:

import * as streamingAvailability from "streaming-availability";

const RAPID_API_KEY = "<YOUR_RAPID_API_KEY>";

// Fetch up to 10 pages of results.
// You can increase this number if you want to fetch more results,
// or set it to 0 to fetch all pages.
const PAGES_TO_FETCH = 10;

const client = new streamingAvailability.Client(new streamingAvailability.Configuration({
	apiKey: RAPID_API_KEY
}));

const movies = client.showsApi.searchShowsByFiltersWithAutoPagination({
	country: "us",
	catalogs: ["netflix"],
	genres: ["action"],
	showType: streamingAvailability.ShowType.Movie,
}, PAGES_TO_FETCH);

for await (const movie of movies) {
	// Do something with the movie
	// You can break the loop at any time if you don't want the rest of the pages
}

All the official client libraries provide similar functionality to fetch paginated results. You can find sample codes for auto-pagination for each client library in the respective client library documentation. To find more about the client libraries, check the Client Libraries guide and click on the client library you are interested in to see the documentation.