How to Build Weighted Festival Fit Scores with Festival API

If you are building for filmmakers, consultants, or submission teams, a raw festival list is only the first step. The real decision happens when someone asks which options deserve attention first. That is where a weighted fit score becomes useful. Instead of relying on vague sorting or a generic recommendation label, you can rank festivals against the actual priorities of a specific project.

Festival API gives you enough structured data to build that ranking in a way that stays explainable. You can start with the main search endpoints, pull a manageable candidate set, layer your own weights for timing, geography, budget, and category match, then produce a shortlist that a human can review quickly. If you want the endpoint reference as you read, start with the Festival API docs. If you are estimating production usage before you ship, the pricing page makes the credit model clear.

What a fit score should actually do

A useful score is not trying to predict whether a film will get accepted. It is helping a team prioritize research and submission effort. In practice, that usually means answering a narrower question: which active festivals look most worth a closer pass for this specific project right now?

That scoring layer becomes practical when it reflects real constraints such as:

• Category fit for short, feature, documentary, animation, horror, or other target lanes
• Geographic priority based on release strategy, travel feasibility, or audience goals
• Deadline timing so near-term opportunities rise appropriately
• Submission cost so expensive outliers do not crowd out better-value options
• Data completeness so weak records do not look equal to stronger ones

The point is not to hide judgment inside a black box. The point is to make the ranking easy to explain. A filmmaker or coordinator should be able to see why a festival landed near the top.

Use Festival API for candidate generation first

Most fit scoring workflows should begin with the broadest cheap query you can justify. In Festival API, GET /v1/festivals is the right first pass for that. It costs 1 credit per request and gives you the structured records needed to build an initial pool.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://festivalapi.com/v1/festivals/?category=documentary&country=United%20States&page_size=50"

That first pass should usually do three things:

1. filter to the broad type of project you care about
2. limit geography if the project has clear market constraints
3. return enough candidates to rank, but not so many that every later step gets expensive

If you need helper interfaces for the filters, the category, country, and state endpoints make that easier. The API exposes GET /v1/categories, GET /v1/countries, and GET /v1/states at 1 credit each, which is useful when you are building filter controls instead of hardcoding values.

Separate platform score from project fit score

One practical pattern is to keep two different scoring concepts instead of one overloaded number.

• Platform score measures how complete or structurally strong a festival record is
• Project fit score measures how well that festival matches the current film and strategy

Festival API already has a scored endpoint for the first problem. In the local API implementation, GET /v1/festivals/scored returns festivals ranked by a composite score and costs 10 credits. That endpoint is useful when you want a quick quality-oriented ordering across candidate records.

For the project fit layer, you should still apply your own weights. That keeps the ranking honest. A record can be well-populated and still be a weak choice for a specific film.

A simple weighted formula

You do not need machine learning to make this useful. A transparent weighted formula is often better because it can be tuned quickly with real feedback.

fit_score =
  0.35 * category_match +
  0.20 * geography_match +
  0.20 * deadline_score +
  0.15 * fee_score +
  0.10 * data_quality_score

Each component can be normalized to a 0 to 100 scale. For example:

• category_match: 100 for direct category fit, lower for adjacent categories
• geography_match: 100 for priority countries, lower for secondary regions
• deadline_score: higher for open opportunities in the preferred time window
• fee_score: higher when the fee stays inside budget
• data_quality_score: derived from record completeness or the scored endpoint

The right weights depend on the user. A producer planning travel-heavy festival strategy may care more about geography. A consultant rushing a late-season push may care more about deadline timing. Keep the weights configurable.

Enrich only the finalists

Do not spend detail credits on every result in the first pass. Rank the broad list, keep the top slice, then enrich only the finalists. That is where GET /v1/festivals/<id> and GET /v1/festivals/<id>/roster become more valuable. In the current implementation, the detail endpoint costs 5 credits and the roster endpoint costs 3 credits.

A practical flow looks like this:

1. pull 30 to 100 candidates from /v1/festivals
2. score them locally with your project weights
3. keep the top 10 to 20 records
4. call detail and roster endpoints only for that smaller finalist set
5. re-rank if the deeper data changes confidence

This is usually the difference between an API workflow that feels production-ready and one that burns credits too early.

Example scoring workflow in Python

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://festivalapi.com/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

weights = {
    "category": 0.35,
    "geography": 0.20,
    "deadline": 0.20,
    "fee": 0.15,
    "quality": 0.10,
}

params = {
    "category": "documentary",
    "country": "United States",
    "page_size": 50,
}

resp = requests.get(f"{BASE}/festivals/", headers=HEADERS, params=params, timeout=30)
resp.raise_for_status()
rows = resp.json().get("results", [])

def score_row(row):
    category_match = 100 if "documentary" in (row.get("categories") or []) else 40
    geography_match = 100 if row.get("country") == "United States" else 60
    deadline_score = 80 if row.get("deadline_regular") else 30
    fee_score = 75
    quality_score = row.get("composite_score") or 60
    return round(
        weights["category"] * category_match +
        weights["geography"] * geography_match +
        weights["deadline"] * deadline_score +
        weights["fee"] * fee_score +
        weights["quality"] * quality_score,
        1,
    )

ranked = sorted(rows, key=score_row, reverse=True)
for festival in ranked[:10]:
    print(festival.get("name"), score_row(festival))

This is intentionally simple. The value comes from the workflow, not from pretending the score is perfect. Once users interact with the shortlist, you can adjust the rules based on what they keep, drop, or revisit.

Keep the score explainable in the interface

The fastest way to lose trust is to show a ranked list with no reason behind it. If you expose a fit score in your product, also show the top factors that created it.

• High fit because: documentary category match, open regular deadline, priority country
• Lower fit because: missing fee data, secondary geography, weak metadata completeness

That extra explanation turns the score into a review aid instead of a mysterious command.

Use scoring to drive shortlist workflows, not replace them

A score should help a team move faster, but it should not replace editorial review. The best use of weighted ranking is operational: deciding which festivals to inspect today, which ones to flag for follow-up, and which ones do not justify more work yet.

That is especially true if you are building for filmmakers. Submission planning is full of qualitative factors that no formula captures well, such as premiere strategy, personal travel constraints, or whether a festival simply feels right for a film. Your score should narrow the field, not pretend to make the final creative call.

Where this works best

Weighted festival fit scores are especially useful in products and workflows such as:

• internal submission dashboards for producers or assistants
• festival research tools for consultants
• AI-assisted planning tools that need structured ranking logic
• saved shortlist systems with weekly refreshes
• CRM-style festival pipelines where priorities change by project

Festival API gives you the structured filtering layer. Your scoring logic turns that layer into an opinionated workflow that actually helps people decide what to do next.

If you are building that kind of tool, start simple. Pull a clean candidate set, apply transparent weights, enrich only the finalists, and let real usage tell you which signals deserve more influence. That approach is easier to ship, easier to debug, and much easier to trust.