A festival listing can tell a filmmaker where to look next. A roster explorer adds the evidence a producer or submission consultant needs before deciding whether a festival deserves more attention. Instead of reducing past programming to one opaque score, it lets a reviewer inspect the titles, directors, years, and award labels behind the pattern.
Festival API exposes that history through GET /v1/festivals/{id}/roster. This article shows a practical implementation pattern for a roster explorer that is fast to browse, clear about what the data means, and honest about missing values. It is useful in a filmmaker portal, a submission-research workspace, or an internal producer tool.
Use the list endpoint to find a festival ID
A roster belongs to one festival, so begin with GET /v1/festivals. The list endpoint supports filters such as category, country, genre, deadline windows, fee ceilings, and name search. Return a focused set of candidates, then pass the selected festival ID to the roster endpoint.
curl -G "https://festivalapi.com/v1/festivals" \
-H "Authorization: Bearer $FESTIVAL_API_KEY" \
--data-urlencode "q=example festival"Keep the ID in your application state, not only the festival name. Names can be similar, while the API ID gives the roster view a stable reference. The Festival API docs describe the search filters and the festival-detail endpoint if your interface also needs current submission information.
Fetch a page of historical programming
The roster endpoint returns films previously screened at a festival. Each result can include a film title, director, release year, genre, category, and award. It is separate from the festival-detail endpoint, which is important: a current festival listing and a record of past programming answer different questions.
curl -G "https://festivalapi.com/v1/festivals/301/roster/" \
-H "Authorization: Bearer $FESTIVAL_API_KEY" \
--data-urlencode "page=1" \
--data-urlencode "per_page=20"The response includes festival_id, festival_name, count, page, per_page, total_pages, and results. The documented default is 20 results per page, with up to 100. Use the paging metadata from the response rather than guessing whether another request is available.
Build the interface around inspection, not false certainty
A useful roster explorer has a compact festival header and a chronological or paginated list of film records. Keep each row legible:
- Film title as the primary label.
- Director and film year as supporting context when present.
- Award as a distinct badge when the record has one.
- Genre and category as descriptive metadata, not a claim that every festival lane is represented.
Do not replace an empty field with an invented value. A missing genre or category means the roster record does not provide that attribute. In the UI, show a neutral omission or “not listed” label rather than treating the absence as proof that the film did not fit a category. This distinction prevents a clean interface from overstating what the data supports.
Use a small server-side proxy
Keep the Festival API key on the server. A browser should call your own route, which validates the requested ID and page number before forwarding the request. This pattern avoids exposing credentials in client-side code and gives you one place to impose sensible limits.
import os
import requests
def festival_roster(festival_id, page=1):
page = max(1, int(page))
response = requests.get(
f"https://festivalapi.com/v1/festivals/{festival_id}/roster/",
headers={"Authorization": f"Bearer {os.environ['FESTIVAL_API_KEY']}"},
params={"page": page, "per_page": 20},
timeout=15,
)
response.raise_for_status()
return response.json()Validate festival_id as an integer, cap per_page at the documented maximum, and return an error state that is separate from an empty roster. An empty result can be a valid response. A failed request needs a retry path and should not be presented as proof that the festival has no history.
Make pagination predictable
Use the API’s page and total_pages fields to drive previous and next controls. Preserve the selected festival ID and page in the URL or app state so a producer can share a specific review view internally. If you cache responses, key the cache by festival ID, page, and page size, then keep the cache short-lived. Historical programming is valuable context, but it is not a substitute for checking the festival’s current rules before a submission.
For a longer roster, load one page at a time instead of fetching every record before rendering the first screen. That keeps the review experience responsive and makes API usage predictable. The roster endpoint costs 3 credits per request, so a page-aware interface is easier to plan for than a background process that repeatedly pulls everything.
Pair raw evidence with a summarized view
Raw roster records work best alongside, not instead of, a higher-level research view. Festival API’s Programming Profiles endpoint summarizes historical patterns and includes confidence information. A roster explorer lets a reviewer inspect the underlying entries when a summary raises a question, such as why a festival appears to favor a particular category or award type.
That combination is more credible than a black-box recommendation. The summary helps teams scan a large universe of festivals. The roster explorer gives them the evidence needed to discuss a smaller set of candidates, record their judgment, and move to current submission research.
Ship the smallest useful version
Start with a festival selector, a server-side roster route, a paginated list, and clear empty and error states. Add saved views or annotations only when the core inspection flow is useful. You can then connect the explorer to a shortlist, research brief, or submission decision log without asking users to trust a score they cannot inspect.
Review the documentation for endpoint details, then see the Festival API pricing page to plan production usage. The practical goal is simple: turn past programming records into a reviewable research surface while keeping human judgment in the loop.