Browse a streaming catalog by genre, year, rating and keyword

View all Streaming Availability endpoints →

Searches the streaming catalog of one country, optionally limited to chosen services, and returns a cursor-paginated list of movies and series. The only required input is country (ISO 3166-1 alpha-2). Optional filters are catalogs (up to 32 comma-separated entries such as netflix, prime.subscription or hulu.addon.hbo), genres with genres_relation (and or or), keyword matched against title and overview, show_original_language, year_min and year_max, and rating_min and rating_max. Sorting uses order_by (original_title, release_date, rating or one of four popularity windows) with order_direction; series_granularity (show, season or episode) sets how much series detail is returned, output_language selects en, es, tr or fr, and cursor fetches the next page. Documented response: an object with a shows array, a hasMore flag and a nextCursor string. Each show carries its title, IMDb and TMDb ids, release year, and streaming options with deep links, subtitles, audios and video quality. Besides the requested services, each show also lists availability on other services in the same country; availability from other countries is never included. Page size is 20 when show_type is movie or series_granularity is show, 10 for series at episode granularity, and 15 otherwise. Observed in a sample call (country us, catalogs netflix, show_type movie, order_by popularity_alltime, series_granularity show): HTTP 200 with 20 shows, hasMore true and a string nextCursor. Each sample show exposed itemType, showType, id, imdbId, tmdbId, title, overview, releaseYear, originalTitle, genres, directors, cast, rating, runtime, streamingOptions (an object keyed by country code holding a list of options) and imageSet. Each option exposed service, type, addon, link, videoLink, price, quality, audios, subtitles, expiresSoon, expiresOn and availableSince. The source response example is cut off and its image links carry expiry data, so only the sample field list above should be treated as verified.

API Features

Service and offer-type catalog scoping The catalogs parameter takes up to 32 entries such as netflix, prime.subscription, peacock.free or hulu.addon.hbo, so a search can target a whole service, one offer type or one add-on; omit it to search every catalog in the country.
Genre filter with and/or logic Pass comma-separated genre ids in genres and choose genres_relation: and (the default) keeps shows that have every listed genre, or keeps shows that have at least one.
Year and rating windows year_min, year_max, rating_min and rating_max are integer bounds that narrow results to a release-year range and a rating band in a single request.
Title and overview keyword match The keyword parameter keeps only shows whose title or overview contains the term, so a keyword can be combined with genre and year filters inside one catalog slice.
Original-language slicing show_original_language takes an ISO 639-1 code such as ko or fr and keeps only shows originally made in that language, useful for niche discovery pages.
Seven sort orders with direction control order_by supports original_title, release_date, rating and four popularity windows (all time, 1 year, 1 month, 1 week), while order_direction switches between asc and desc.
Series detail levels series_granularity chooses show, season or episode depth; show keeps the payload small, and episode adds season and episode data with their own streaming options and deep links.
Cross-service availability on each title Every show lists streaming options from other services in the same country alongside the requested catalog; the sample call with catalogs=netflix returned options from ten services.
Cursor pagination Each response includes hasMore and nextCursor; resend the same filters with cursor set to nextCursor to read the next page until hasMore is false.

Live API Demo

GET /api/project/streaming-availability/search-shows-by-filters

Request cost is temporarily unavailable. No price is assumed.

View pricing

API Response (JSON)

{}
curl -X GET 'https://api.opendata-api.com/api/project/streaming-availability/search-shows-by-filters?key=<API_KEY>&country=<country>&genres_relation=and&order_by=original_title&output_language=en&series_granularity=show'
📢
Need Help?
If you encounter API issues or need other API requirements, please contact us.
Contact Us

Use Cases

Frequently asked questions

Which parameter is required?

Only country, a two-letter ISO 3166-1 alpha-2 code such as us. Every other parameter is optional, and with no catalogs value the search covers all catalogs available in that country.

How do I write the catalogs value?

Use a comma-separated list of up to 32 entries. A bare service id such as netflix searches that whole service; service.type (for example prime.subscription, peacock.free, prime.rent) limits it to one offer type among subscription, free, rent, buy and addon; service.addon.addon_id (for example hulu.addon.hbo) limits it to one add-on. A show matching any entry is included.

How does pagination work?

The response contains hasMore and nextCursor. When hasMore is true, send the same parameters again with cursor set to the previous nextCursor, URL-encoded because it may contain characters such as ? and &. The first request has no cursor. The sample call returned hasMore true with a string nextCursor.

How many shows come back per page?

20 when show_type is movie or series_granularity is show, 10 when show_type is series and series_granularity is episode, and 15 otherwise. The sample movie call returned 20 shows.

Does catalogs limit the streaming options inside each show?

No. The documentation says each show also lists availability on other services in the same country, and the sample call with catalogs=netflix returned options from ten services. Availability from other countries is never included.

How do genres and genres_relation work together?

genres takes comma-separated ids from the genres endpoint, for example scifi,thriller. genres_relation only matters when more than one id is given: and (the default) returns shows with all of the genres, or returns shows with at least one.

How do I get the highest-rated or most popular titles first?

Set order_by to rating or one of popularity_alltime, popularity_1year, popularity_1month or popularity_1week. The documentation says direction defaults to asc for title and date ordering and desc for rating and popularity, and order_direction lets you set it explicitly. The sample call used popularity_alltime without order_direction.

What scale do rating_min and rating_max use?

They are integer bounds applied to the same rating value each show returns. The source does not state the scale; the 20 shows in the sample call had integer ratings between 73 and 84, so a 0 to 100 style scale is likely but unconfirmed.

Do series include season and episode data?

Only when series_granularity is season or episode. The default show leaves season and episode info out and is recommended when you do not need it, because the response is smaller and faster. Movies are not affected by this parameter.

Are the image links in the response permanent?

Treat them as temporary. The source response example shows image links with expiry and signature query parameters, so request fresh results rather than storing those links long term.

Related operations

Guides

View Subscription Plans →