A festival list is not yet a decision tool. Producers and submission teams need to understand why a festival belongs on a list, what still needs checking, and which next action is worth taking. Festival API can supply the structured record layer for that work. A small application can turn it into a concise research brief that is useful in a production meeting, a client update, or a filmmaker’s submission review.
This tutorial outlines a practical pattern: collect a focused set of festival records, preserve the fields that drive decisions, add transparent project-specific notes, and export a brief that separates source data from your team’s judgment.
Define the brief before you query
Start with the reader’s decision. A producer-ready brief should not attempt to reproduce every field from an API response. It should answer a short set of questions:
- Is this festival relevant to the project’s format, genre, or audience?
- Where and when does it take place?
- Which deadline and fee information need attention?
- What evidence supports the fit?
- What should the team do next: research, verify, save, or submit?
Keep the project profile in your application. Festival API provides the structured festival information, while your product should own the constraints and editorial reasoning for a particular film.
project = {
"title": "River City",
"format": "short",
"genres": ["drama", "coming of age"],
"target_countries": ["US", "CA"],
"fee_ceiling": 65,
"latest_deadline": "2026-10-15"
}
Pull a focused candidate set
Use the filtering and search options documented in the Festival API documentation to narrow the candidate set before presenting anything to a producer. The narrower the initial request, the less cleanup the brief requires.
For each returned festival, retain the stable identifier along with the core factual fields you expect to cite: name, location, categories or genres, event dates, deadlines, fees, website, and submission destination when available. Do not discard source values simply because a derived label looks cleaner. You will need the original data for refreshes and verification.
candidates = festival_api.search({
"query": "short drama",
"country": "US"
})
records = [
{
"festival_id": item["id"],
"name": item["name"],
"country": item.get("country"),
"categories": item.get("categories", []),
"deadline_regular": item.get("deadline_regular"),
"submission_fee": item.get("submission_fee"),
"submission_url": item.get("submission_url")
}
for item in candidates
]
The field names and available filters can vary by endpoint. Treat the example as an application pattern and consult the docs for the current response shape rather than hard-coding assumptions from a single test response.
Add reasoning without overwriting source data
Next, create a separate assessment object for each candidate. This keeps a useful boundary between facts returned by Festival API and conclusions made for this project.
def assess(festival, project):
reasons = []
actions = []
category_text = " ".join(festival.get("categories", [])).lower()
if project["format"] in category_text:
reasons.append("category appears aligned with the project format")
fee = festival.get("submission_fee")
if fee is not None and fee <= project["fee_ceiling"]:
reasons.append("listed fee is within the project ceiling")
elif fee is None:
actions.append("verify submission fee")
if not festival.get("deadline_regular"):
actions.append("verify current deadline")
if not festival.get("submission_url"):
actions.append("confirm submission path")
return {
"fit_reasons": reasons,
"next_actions": actions,
"review_state": "verify" if actions else "ready_for_review"
}
That distinction matters. “Listed fee is within the project ceiling” is a derived judgment. The actual fee remains source data. If the next API refresh changes it, the assessment can be recalculated without losing notes from a producer or researcher.
Write the brief in a scan-friendly structure
A good brief can be read quickly, then audited when someone asks a follow-up. Give each festival the same compact structure:
- Identity: name, city, country, and event dates.
- Fit: two or three specific reasons it belongs in this project’s research set.
- Submission facts: deadline, fee, and direct submission path when present.
- Open questions: missing or stale-looking fields that need confirmation.
- Recommended action: save, research further, verify, or prepare a submission.
## Northstar Short Film Festival
Chicago, United States | Event dates: Oct 8 to Oct 12
Why it is here
- Category appears aligned with the project format
- Listed fee is within the project ceiling
Submission facts
- Regular deadline: 2026-08-20
- Fee: $45
- Submission path: available
Open questions
- Confirm current deadline before submitting
Recommended action: Assign to producer review
This format works as a web view, a Notion page, a CRM note, or a generated PDF. The important part is consistency. A producer should not have to hunt through a long table to learn why one festival was included or what is unresolved.
Rank by actionability, not just a single score
A composite score can be a useful input, but it should not become a black-box instruction. In a research brief, rank candidates with separate signals for project fit, readiness, and urgency. A strong fit with an unverified deadline may deserve a place in the brief, but it should be marked for verification before it is treated as an immediate opportunity.
- Fit: how closely the record aligns with the project profile.
- Readiness: whether the minimum decision fields are present.
- Urgency: whether a deadline or event date makes the next action time-sensitive.
Use clear labels such as “ready for producer review,” “verify before recommending,” and “monitor.” They are more useful than hiding uncertainty behind a single number.
Refresh facts and preserve team notes
Festival details change. Store the Festival API identifier, last refresh time, and a snapshot of the source fields used in the brief. On the next refresh, compare the deadline, fee, submission URL, event dates, and active status. Recalculate your derived assessment when those inputs change, but retain human notes and decisions in a separate table or document.
This creates a manageable operating loop: discover candidates, generate the brief, assign verification tasks, refresh time-sensitive facts, and record the team’s decision. It is more reliable than copying one-off research into static spreadsheets that quickly lose their connection to the underlying data.
Start with one real project
Build the first version around a single film and a single producer workflow. Ask which fields are actually read in the review meeting, which missing fields trigger manual research, and what action follows each brief. Then adjust the project profile and assessment rules around that behavior.
Festival API gives developers a structured starting point for festival discovery and detail lookup. A producer-ready brief turns those records into an honest, repeatable decision workflow. Review the documentation for current endpoint details and pricing when you are ready to take the workflow beyond a prototype.