Search the Filimo and Namava catalogs by title and return matching movies and series with a ref for each.

Use first when the user names a title. Each hit has a ref to pass to vod_title (full details), vod_episodes (series seasons and episodes). Use vod_where instead to learn which service has one specific title. Filimo hits include year, rating, genres and a summary; Namava search only returns title, kind and year.

Tell which of Filimo and Namava carries a title, by searching both and matching the title text.

Use for "is X on Filimo or Namava". Returns the matching titles per site (exact title match first, then titles that contain the words) and available_on. Only the catalogs are checked, not whether a title needs a subscription; use vod_title for that. Pass vod_search results to vod_title for details.

Get full details of one movie or series on Filimo or Namava: synopsis, genres, year, rating, age rating, cast, director.

Use after vod_search, vod_browse or vod_new with the ref of a hit. For a series, follow with vod_episodes to list seasons and episodes; vod_related gives similar titles and vod_person a cast member's filmography. Ratings differ per site: Filimo gives stars out of 5 with a vote count and an IMDb score; Namava gives like and dislike counts (and an IMDb score for newer titles). Filimo's cast for a movie is the names in its description text; for a series it is the actors Filimo features (a few main ones). Namava people maps each name to a ref for vod_person.

List the seasons of a series and the episodes of one season (title, summary, length, publish date).

Use after vod_search or vod_title when the user wants episodes, how many seasons exist or the newest episode. Takes a series ref; a movie ref returns an error. Default season is the latest. Streaming links are not provided.

List the newest titles added to Filimo and Namava, most recent first.

Use for "what is new on Filimo/Namava". Filimo lists include year, rating and summary; Namava lists only title and kind (call vod_title for more). Use vod_featured for what each site promotes on its front page instead.

Show what Filimo and Namava promote right now: Filimo's front-page rows (new, popular, box office, genres) and Namava's top slider and top list.

Use for "what is popular / trending on Filimo or Namava". These are editorial picks, not view counts. Take a ref from here to vod_title for details. For Namava's most-viewed list use vod_collection(key="namava:popular").

List the genre names vod_browse accepts for Filimo and Namava, with the English aliases.

Use before vod_browse when unsure of a genre name. Persian names work for both sites; English aliases such as comedy or drama work too. Filimo also takes sort and country filters (see vod_browse).

List movies and series of one genre on Filimo and Namava, with Filimo's sort and country filters.

Use for "best comedy series on Filimo", "Iranian dramas", "new documentaries". Filimo rows carry year, rating, IMDb and summary; Namava rows only title, kind and id (use vod_title). Next: vod_title or vod_episodes. For themed lists (IMDb top 250, Oscar, kids, coming soon) use vod_collections instead.

Look up an actor, director or writer on Filimo and Namava: short bio and the titles they appear in.

Use for "what has X acted in / directed on Filimo or Namava". Titles carry a ref for vod_title. Filimo gives birth date and place when it has them; Namava gives a bio text. A name matches the first search hit (exact name first); other_matches lists further people with similar names. Series appear once, not per episode.

List titles similar to one movie or series on Filimo or Namava ("viewers also watch").

Use after vod_title when the user wants more like it. Filimo also returns its related rows (more by the same actors or writer, same genre and decade) and the featured actors and writers; Namava returns one recommendation list. Take a ref from the result to vod_title.

List the curated lists vod_collection can open on Filimo and Namava: IMDb top 250, Oscar, kids, coming soon and more.

Use when the user asks for a themed list (best-of, festival winners, kids, Korean or Turkish series, true stories). Each entry has a key to pass to vod_collection. Namava category groups (any slug from vod_genres) also work as namava:category:<slug>.

Show the titles of one curated list on Filimo or Namava, such as the IMDb top 250 or coming soon.

Use after vod_collections. Filimo lists accept sort and country filters and reach about 200 titles; Namava lists are fixed (newest or editorial order, upcoming marks titles without a release date). The Filimo key 'kids' opens the kids home page as several rows. Next: vod_title with a ref.

Show Namava's public subscription plans and prices (Filimo's prices are not available in its JSON API).

Use for "how much is a Namava subscription". Prices are in toman before 10% VAT. price is the list price, price_new_user the discounted price shown to new users (what a guest sees); auto_renew is the monthly plan that renews itself. Filimo shows its prices only in its payment page (https://www.filimo.com/payment).