A festival-search experience is only as useful as the information collected before the first API request. Ask for too little and the results are broad. Ask users to make choices the API cannot use and the application has to guess. Festival API provides a practical way to design a project intake form around the fields that actually drive film festival discovery: category, genre, territory, budget, and timing.
This is a useful pattern for filmmaker platforms, submission consultants, and internal producer tools. The goal is not to automate a submission decision. It is to turn a film’s basic constraints into a repeatable first-pass search that a person can review.
Start with a search contract, not a long questionnaire
An intake form should collect the minimum information needed to form a defensible query. For a first version, that usually means:
- Project format or category: such as short film, feature, documentary, animation, experimental, music video, student, or web series.
- Genre: when genre should further narrow the candidate set.
- Target territory: a country, and optionally a state or province.
- Submission budget: a maximum regular fee in USD.
- Submission window: a date range that starts after today and ends before the team’s planning cutoff.
Keep filmmaker language separate from API values. A filmmaker may select “short documentary” in the form, while the search contract maps that choice to a category and genre combination. This preserves a clear user experience without forcing the search layer to interpret free-form answers every time.
Populate category choices from the API
Use GET /v1/categories to retrieve available category codes and their current record counts. This is better than maintaining a hard-coded list that can drift from the dataset. Store the codes your product supports, then present human-readable labels in the form.
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://festivalapi.com/v1/categoriesFor example, a form can display “Short Film” while sending short_film, or display “VR / 360” while sending vr_360. Do not silently map a vague label like “narrative” to a category unless your product explains the rule. When a project cannot be represented by one category, allow a broader search and make that uncertainty visible in the results.
Turn a completed form into one transparent request
The festival list endpoint accepts structured filters for category, country, genre, deadlines, fees, state or province, and sorting. A practical intake result is a saved query object, not merely a request URL. Save both the original answers and the resolved parameters so a user can see why a result appeared.
{
"project_name": "Untitled Short Documentary",
"answers": {
"format_label": "Short Film",
"genre_label": "Documentary",
"country": "Canada",
"fee_ceiling_usd": 50,
"deadline_horizon_days": 60
},
"festival_api_query": {
"category": "short_film",
"genre": "documentary",
"country": "Canada",
"fee_max": 50,
"deadline_after": "2026-09-01",
"deadline_before": "2026-10-31",
"sort": "deadline",
"sort_dir": "asc"
}
}Then send the resolved query to GET /v1/festivals. The endpoint returns up to 100 results and keeps unknown dates last when sorting by a date field. Using an explicit date range is more useful than an undefined “open now” checkbox because the product can show the exact planning window it searched.
curl -G https://festivalapi.com/v1/festivals \
-H "Authorization: Bearer YOUR_API_KEY" \
--data-urlencode "category=short_film" \
--data-urlencode "genre=documentary" \
--data-urlencode "country=Canada" \
--data-urlencode "fee_max=50" \
--data-urlencode "deadline_after=2026-09-01" \
--data-urlencode "deadline_before=2026-10-31" \
--data-urlencode "sort=deadline" \
--data-urlencode "sort_dir=asc"Design for incomplete answers
Real projects often arrive before every decision is settled. A useful intake form does not turn missing answers into false precision. If the user has not chosen a country, omit the country parameter. If the budget is undecided, omit fee_max and label fee as a review field. If category is uncertain, let the user search a broader set and ask them to refine after seeing the first results.
That distinction matters because filtering is irreversible within a request. A strict but unsupported guess can hide viable festivals. A wider result set with a visible “needs project detail” state gives a producer a clear next action.
Separate eligibility signals from recommendation signals
A category match, an upcoming deadline, and a fee below budget are eligibility signals. They do not prove that a festival is artistically or strategically right for the project. Keep the first search focused on facts returned by the API, including location, categories, genres, deadline fields, event dates, fee, website, and direct submission URL when available.
For candidates that move beyond the first pass, retrieve the individual festival record and, where appropriate, examine its roster or programming profile. Festival API’s programming profile reports historical programming patterns along with sample size and confidence. That lets a workflow distinguish “matches the listed category” from “has evidence of programming similar work,” without pretending the data can make the final call.
Keep the saved query current
Festival data is operational data. Deadlines, fees, and submission links may change after a query is saved. Store the time of the last refresh alongside the query parameters, and rerun active searches on a schedule that matches the submission window. A 60-day search might be refreshed weekly, while a closing-soon view may need a daily refresh.
When the results change, show what changed: a newly qualifying festival, a deadline that moved inside the window, a fee that now exceeds the ceiling, or a record that needs human review. This keeps the intake form connected to a real workflow instead of becoming a one-time lead form.
Build the smallest useful flow
The first implementation can be a five-field form, a saved query object, and a results table sorted by deadline. Add team notes, scoring, CRM sync, or calendar output only after the project-to-query mapping is reliable. The durable value is the translation layer: it converts a filmmaker’s project description into structured constraints that can be reviewed, repeated, and improved.
See the Festival API documentation for the complete parameter reference, endpoint costs, and response fields. When you are ready to move from a prototype to recurring searches, review Festival API pricing and choose a refresh cadence that matches how your users plan submissions.