Catalog filters

client.catalog.releases() browses the whole release catalog with filters, sorting and pagination — the "Catalog" page of the site. For finding one title by name, client.app.search_releases() is simpler.

A first query

page = await client.catalog.releases(types=["TV"], year_from=2020, sorting="RATING_DESC", limit=10)
print(f"{page.total} releases, page {page.page} of {page.total_pages}")
for release in page.items:
    print(release.year, release.name.main)

Every filter is optional and keyword-only; without any, you get the whole catalog (about two thousand releases), most recently updated first.

Where the values come from

client.catalog.references returns the lists the site's own filters show. Their items can be passed to the filters directly — no need to copy IDs or strings by hand:

refs = client.catalog.references
genres = {genre.name: genre for genre in await refs.genres()}
page = await client.catalog.releases(genres=[genres["Экшен"], genres["Фэнтези"]], limit=5)

refs.types(), refs.seasons(), refs.age_ratings(), refs.publish_statuses(), refs.production_statuses() and refs.sorting() work the same way: pass the items, or their .value. refs.years() lists only the years that have releases.

for option in await refs.sorting():
    print(option.value, "—", option.label)

FRESH_AT_DESC — Обновлены недавно
FRESH_AT_ASC — Обновлены давно
RATING_DESC — Самый высокий рейтинг
RATING_ASC — Самый низкий рейтинг
YEAR_DESC — Самые новые
YEAR_ASC — Самые старые

How filters combine

Checked against the live API (see API notes):

• genres — all of them. genres=[14, 29] returns releases that have both genres.
• Every other list — any of them. types=["TV", "ONA"] returns TV or ONA releases; the same for seasons, age_ratings, publish_statuses, production_statuses.
• Different filters — all of them. genres=[14], types=["TV"] means genre 14 and TV.
• Years are inclusive. year_from=2018, year_to=2020 includes 2018 and 2020; either bound can be used alone.

# Action AND fantasy, TV or ONA, released 2018–2020
page = await client.catalog.releases(
    genres=[14, 29], types=["TV", "ONA"], year_from=2018, year_to=2020
)

Sorting

sorting takes one value; the default is "FRESH_AT_DESC" (recently updated first).

• FRESH_AT_* — by when a release was last updated (usually a new episode).
• YEAR_* — by release year.
• RATING_* — by popularity: in every live check, the order followed added_in_users_favorites (how many users added the release to favorites), not the average score in release.rating.

Search

search uses the same matching as the quick search: Russian and English names and aliases, sensitive to punctuation. It also shares its cap — at most about 20 matches in total, whatever the other filters and the page size. Use it to narrow down a title, not to list "everything with the word magic".

page = await client.catalog.releases(search="frieren", types=["TV"])

An empty search="" is the same as no search.

All pages

releases() returns one Page; iter_releases() takes the same filters (minus page) and walks all pages, requesting the next one only when you reach it:

async for release in client.catalog.iter_releases(
    publish_statuses=["IS_ONGOING"], sorting="FRESH_AT_DESC", limit=50
):
    print(release.name.main)

Use limit=50 with iter_releases() — it only changes how many requests are made. Breaking out of the loop stops the requests. A page number past the last page returns an empty page. More in the Pagination guide.

Invalid values

The API doesn't report wrong filter values: an unknown type silently returns no releases, an unknown sort order or a non-numeric year is silently ignored. So the SDK checks them before sending and raises right away:

await client.catalog.releases(types=["tv"])
# ValueError: Unknown types value 'tv'; expected one of: TV, ONA, WEB, OVA, OAD, MOVIE, DORAMA, SPECIAL

• An unknown value of a list filter or of sorting → ValueError.
• year_from after year_to → ValueError (the API would return nothing).
• A single string instead of a list, e.g. types="TV" → TypeError.
• page below 1 or limit outside 1–50 → the API's own ValidationError.

The allowed values are the enums of the API's OpenAPI spec; with a type checker, the parameters' Literal types catch typos before the code even runs.