Filter a Netflix Catalog by Genre and Year: Why catalogs=netflix Still Returns Other Services
The assumption goes like this: catalogs=netflix returns Netflix titles, so every entry in each row's streamingOptions must be a Netflix entry. The first half holds. The second half turns a "list Netflix movies" job into a mixed-service export without raising a single error.
The Streaming Availability API filters a country's catalog with search-shows-by-filters, where only country is required. Copy an authorized platform key from the dashboard before running anything. It travels in the query string, so keep it out of logs, tickets and screenshots. Reading or copying anything below sends no request.
A Netflix-filtered row can carry other services too
https://api.opendata-api.com/api/project/streaming-availability/search-shows-by-filters?key=YOUR_API_KEY&country=us&catalogs=netflix&show_type=movie&series_granularity=show
Inside the gateway's data, the response holds shows, hasMore and, when another page exists, nextCursor. This loop looks right:
# Naive: treats every option on a row as a Netflix option
for show in page["shows"]:
print(show["title"], show["streamingOptions"]["us"][0]["link"])
Before fixing it, measure what a page holds:
from collections import Counter
def option_mix(page, country="us"):
mix = Counter()
for show in page["shows"]:
for option in show["streamingOptions"].get(country, []):
mix[(option["service"]["id"], option["type"])] += 1
return mix.most_common()
On one sampled page (country=us, catalogs=netflix, show_type=movie, 20 rows), every row did have a Netflix subscription entry. The same rows held 130 option entries in total, from ten services, spread across subscription, buy, rent, free and add-on types. The first option on the first row was an add-on sold through another service's channel. That matches the documentation: catalogs decides which shows come back, and each show then lists its availability on other services in that country too. Other countries are never included. Your counts will differ, so run option_mix on your own page.
Two catalogs make it murkier: catalogs=netflix,prime matches either, and the sampled rows carried no field saying which one did.
Take genre ids from get-genres before writing the filter
get-genres needs no input and returns a root array of {id, name} objects, 21 in the sample. The ids are lowercase slugs such as scifi, thriller or documentary; the names are labels such as "Science Fiction". The genres filter wants ids, comma-separated, so a display name is the wrong kind of value. output_language changes the labels, not the ids, so key your data on the id. The documentation does not say what an unknown id does, so check ids locally.
Catalog selectors have a directory too: get-countries lists supported country codes, and get-country lists one market's service ids, streamingOptionTypes and add-ons. A selector such as prime.subscription narrows a service to one access type.
Read streamingOptions as a country map and keep only the service you asked for
streamingOptions is an object keyed by lowercase country code, each value a list of options. In the sample, only the requested country appeared. Every option has a service object (id, name), a type (subscription, free, rent, buy or addon), a link, and fields such as quality, audios, subtitles and expiresOn. An add-on entry also carries an addon object; in the sample, service named the hosting channel and addon named the add-on itself. Match the service id and the type together:
def own_options(options, service, types):
return [o for o in options
if o.get("service", {}).get("id") == service and o.get("type") in types]
A row that matched the catalog but returns an empty list for your types is information, not an error, so count it rather than dropping it.
Pin genres_relation, year range and rating range into one reproducible query
genres=scifi,thriller with genres_relation=and keeps shows that have both genres; or keeps shows that have at least one. and is the default, but send it anyway: a query you will rerun next week should not depend on defaults.
year_min and year_max take four-digit years. rating_min and rating_max take integers on the same scale as each row's rating. The documentation does not state that scale; the sampled ratings were integers from 73 to 84, so 0 to 100 looks likely but is unconfirmed.
Set order_by and order_direction explicitly too. Title and release-date orderings hold still between runs; the popularity windows reorder as viewing shifts, good for rankings, bad for diffs.
Page size follows show_type: 20 movies, 15 or 10 otherwise
show_type | series_granularity | Rows per page |
|---|---|---|
movie | any | 20 |
| any or omitted | show (default) | 20 |
series | episode | 10 |
series | season | 15 |
| omitted | season or episode | 15 |
Three consequences follow. Page size is not a constant, so rely on hasMore, not len(shows). Switching a movie query to series at episode granularity halves the page and adds season and episode detail, so the same titles take more calls. And a cursor belongs to one query: pass nextCursor back unchanged with every other parameter identical. requests URL-encodes it when it builds the query string, which matters because the value may contain ? and &.
One script: a single service, a genre pair, rows you can diff next week
The script validates the genre ids, walks the pages, keeps only options from the chosen service and access type, and writes a CSV sorted by show id. The next run reports which ids entered or left. Install requests and export the key as OPENDATA_API_KEY on a server you control.
HTTP status and the gateway's business status are separate checks. A 4xx or 5xx means the call did not run; an HTTP 200 whose code is not 200 is a business failure. The helper avoids raise_for_status() on purpose, because its message embeds the full URL, key included.
import csv
import os
from pathlib import Path
import requests
BASE = "https://api.opendata-api.com/api/project/streaming-availability"
KEY = os.environ["OPENDATA_API_KEY"] # authorized platform key; never hard-code it
COUNTRY, SERVICE, TYPES = "us", "netflix", {"subscription"}
GENRES = ["scifi", "thriller"]
MAX_PAGES = 25
QUERY = {
"country": COUNTRY,
"catalogs": SERVICE,
"show_type": "movie", # 20 rows per page
"series_granularity": "show",
"genres": ",".join(GENRES),
"genres_relation": "and", # stated, not left to the default
"year_min": 2010,
"year_max": 2020,
"rating_min": 70, # same scale as each row's rating
"order_by": "release_date",
"order_direction": "desc",
}
FIELDS = ["id", "imdbId", "title", "releaseYear", "rating", "link"]
SNAPSHOT = Path(f"{SERVICE}_{COUNTRY}_{'-'.join(GENRES)}.csv")
def call(operation, **params):
try:
response = requests.get(
f"{BASE}/{operation}", params={"key": KEY, **params}, timeout=60
)
except requests.RequestException as exc:
# The exception text can contain the key-bearing URL; report the type only.
raise RuntimeError(f"{operation}: {type(exc).__name__}") from None
if not response.ok: # HTTP layer
raise RuntimeError(f"{operation}: HTTP {response.status_code}")
envelope = response.json()
if envelope.get("code") != 200: # gateway business status
raise RuntimeError(f"{operation}: code {envelope.get('code')} {envelope.get('message')}")
return envelope["data"]
def catalog_rows():
cursor = None
for _ in range(MAX_PAGES):
page = call("search-shows-by-filters", **QUERY, **({"cursor": cursor} if cursor else {}))
yield from page["shows"]
if not page.get("hasMore"):
return
cursor = page["nextCursor"]
raise RuntimeError("MAX_PAGES reached; narrow the filters")
def own_options(options, service, types):
return [o for o in options
if o.get("service", {}).get("id") == service and o.get("type") in types]
def main():
known = {genre["id"] for genre in call("get-genres")}
if not set(GENRES) <= known:
raise SystemExit(f"Not genre ids: {sorted(set(GENRES) - known)}")
rows, mixed, empty = [], 0, 0
for show in catalog_rows():
options = show.get("streamingOptions", {}).get(COUNTRY, [])
mine = own_options(options, SERVICE, TYPES)
mixed += len(mine) < len(options)
if not mine:
empty += 1
continue
rows.append({"id": show["id"], "imdbId": show.get("imdbId", ""),
"title": show["title"], "releaseYear": show.get("releaseYear", ""),
"rating": show.get("rating", ""), "link": mine[0]["link"]})
old_ids = set()
if SNAPSHOT.exists():
with SNAPSHOT.open(newline="", encoding="utf-8") as handle:
old_ids = {row["id"] for row in csv.DictReader(handle)}
rows.sort(key=lambda row: row["id"])
with SNAPSHOT.open("w", newline="", encoding="utf-8") as handle:
writer = csv.DictWriter(handle, fieldnames=FIELDS)
writer.writeheader()
writer.writerows(rows)
new_ids = {row["id"] for row in rows}
print(f"{len(rows)} rows; {mixed} also listed other services or types; {empty} had no {SERVICE} option")
if old_ids:
print("entered:", sorted(new_ids - old_ids), "left:", sorted(old_ids - new_ids))
if __name__ == "__main__":
main()
Read "left" carefully: a show can drop out because its rating moved under rating_min, not because it left the service. Look the id up with get-show first.
When a catalog filter is the wrong tool
Browsing returns 10 to 20 rows per call. If you already hold an IMDb or TMDB id, get-show is the direct route; the IMDb id guide walks through it. If you only hold a title, search-shows-by-title returns candidates in one array. If the question is what is arriving or leaving, get-changes is the feed built for it; see the leaving-soon alerts guide. To compare countries, rerun identical filters with another country after rechecking get-country, since each market has its own services. Whatever the filter returns, each link points to a service title page, not to video.