How to Build a Country-by-Country Festival Opportunity Map with Festival API

Festival strategy gets harder when a project is ready for more than one territory. A spreadsheet with names and dates is useful, but it does not show where the real opportunities are, which markets fit the film, or what needs attention first. Festival API gives you structured country, category, deadline, fee, and event-date data that can become a practical country-by-country opportunity map.

Start with the decision the map needs to support

An opportunity map is not a list of every festival in every market. It is a planning view for a specific film and a specific submission window. Decide what the map should answer before making requests:

• Which countries have festivals that accept the project’s category?
• Where are upcoming deadlines inside the next 30, 60, or 90 days?
• Which territories meet the available fee budget?
• Which markets should be researched now and which can wait?

For example, a documentary producer may start with a 60-day horizon, a maximum fee, and a short list of target countries. That produces a defensible first pass instead of a worldwide list with no priority.

Use the country endpoint to establish coverage

Begin with GET /v1/countries. It returns the countries in the dataset with their festival counts. This is a useful coverage check before you build filters around a market that may have limited records. It also gives a lightweight way to populate a territory selector in an internal tool.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://festivalapi.com/v1/countries

Do not treat a larger count as a recommendation. It is simply a coverage signal. Your project’s language, format, release goals, travel plans, and rights strategy still matter. The map should make those decisions easier to review, not hide them behind one generic score.

Query each territory with constraints that match the film

Use GET /v1/festivals to request a focused set for each country. The endpoint supports country, category, genre, deadline_after, deadline_before, fee_max, and date sorting. An upcoming-deadline filter is especially helpful because a deadline after today is the practical equivalent of an accepting-submissions view.

curl -G https://festivalapi.com/v1/festivals \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "country=Canada" \
  --data-urlencode "category=documentary" \
  --data-urlencode "deadline_after=2026-08-25" \
  --data-urlencode "deadline_before=2026-10-24" \
  --data-urlencode "fee_max=60" \
  --data-urlencode "sort=deadline" \
  --data-urlencode "sort_dir=asc"

Run the same request for each target country. Store the response alongside the date you fetched it, since deadlines and fees are operational data that can change. The returned records include location, categories, genres, regular fee, deadlines, event dates, submission platforms, website, and direct submission URL when available.

Turn returned records into map-ready fields

A map does not need every API field on the first screen. Normalize the result into a compact territory summary, then retain the full record behind a detail view. A useful row or map tooltip includes:

• Territory: country, city, and state or province when present
• Timing: nearest relevant deadline and event start date
• Cost: regular fee, plus a budget flag if it exceeds the project rule
• Fit: matched categories and genres
• Action: submission URL, website, and a link to the saved research record

Use visual encoding sparingly. A deadline color, a fee band, and a marker size based on the number of matching festivals are usually enough. Avoid implying that a large marker means a better festival. It means only that the current query returned more candidates in that territory.

Add a second layer for event dates

Submission timing is only half of a territory plan. The GET /v1/calendar endpoint provides a unified feed of upcoming deadlines and event dates, with optional country and category filters. Use it to identify when several target festivals take place in the same region, or to plan outreach and travel around the festivals that matter most.

curl -G https://festivalapi.com/v1/calendar/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "days=90" \
  --data-urlencode "country=Canada" \
  --data-urlencode "category=documentary"

The calendar can also return iCal with export=ics, which is useful when the people making submission decisions live in Google Calendar or Apple Calendar rather than a custom dashboard.

Keep the map honest with a review workflow

Structured data reduces research time, but it should not replace judgment. Before a festival becomes a submission candidate, assign a simple review state such as research, ready to submit, submitted, or not a fit. Record the reason for the last state. That feedback improves the next territory query and keeps the map from becoming an attractive but passive report.

For higher-stakes choices, call the individual festival and historical programming endpoints to add context. The roster and programming profile can help you distinguish a listing that accepts a category from a festival that has demonstrably programmed work like yours. Keep the data-supported signals separate from qualitative notes from the producer or filmmaker.

Build the smallest useful version first

The first version can be a filtered table grouped by country, a shared spreadsheet, or a simple map layer. What matters is the repeatable workflow: establish coverage, query with project constraints, preserve the returned fields, review candidates, and refresh the data on a schedule. Once that is working, add notifications, team assignments, or a submission CRM.

Read the Festival API documentation for endpoint details and request parameters. You can also review credit pricing before choosing a refresh cadence for a multi-country workflow.