FilmFreeway APIfilmfreeway.com ↗
Search and retrieve film festival data from FilmFreeway: deadlines, submission categories, fees, rules, organizers, and photos via 6 structured endpoints.
What is the FilmFreeway API?
The FilmFreeway API provides access to film festival data across 6 endpoints, covering everything from full-text festival search to per-festival submission categories, fee schedules, rules, and photo galleries. The get_festival_details endpoint returns deadlines with ISO-formatted dates, category fees broken down by deadline tier, organizer names, and contact information for any festival identified by its slug.
curl -X GET 'https://api.parse.bot/scraper/24cb03f5-ea57-4eba-8e6b-43bc74bc264a/search_festivals?page=1&query=documentary' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace filmfreeway-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""FilmFreeway SDK — discover festivals, inspect details, compare submissions."""
from parse_apis.filmfreeway_api import FilmFreeway, FilmCategory, FestivalNotFound
client = FilmFreeway()
# Search festivals by category — limit caps total items fetched
for summary in client.festivalsummaries.by_category(categories=FilmCategory.DOCUMENTARY, limit=3):
print(summary.name, summary.location)
# Drill into the first result's full details
summary = client.festivalsummaries.search(query="Nantucket", limit=1).first()
if summary:
festival = summary.details()
print(festival.name, festival.url)
for deadline in festival.deadlines:
print(deadline.type, deadline.date, deadline.iso_date)
# Fetch a festival directly by slug and browse its photos
festival = client.festivals.get(slug="NantucketFilmFestival")
for photo in festival.photos.list(limit=3):
print(photo.href, photo.width, photo.height)
# Get focused category/fee info via an instance method
cat_info = festival.get_categories()
for cat in cat_info.categories:
print(cat.name, [f.fee for f in cat.fees[:2]])
# Typed error handling
try:
client.festivals.get(slug="NonExistentFestival12345")
except FestivalNotFound as exc:
print(f"Not found: {exc.slug}")
print("exercised: festivalsummaries.by_category / .search / .details / festivals.get / photos.list / get_categories")
Full-text search over film festivals. Returns paginated summaries (up to 50 per page). Omitting the query returns all festivals ordered by relevance. Each summary carries the slug needed to fetch full details.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| query | string | Search keyword (e.g. 'grant', 'documentary'). Omitting returns all festivals. |
{
"type": "object",
"fields": {
"page": "integer current page number",
"has_more": "boolean indicating if more pages are available",
"festivals": "array of festival summary objects with name, slug, url, location, and description_snippet"
},
"sample": {
"data": {
"page": 1,
"has_more": true,
"festivals": [
{
"url": "https://filmfreeway.com/DOCLA",
"name": "DOC LA. Los Angeles Documentary Film Festival",
"slug": "DOCLA",
"location": "Los Angeles, California, United States\n\n\n 12 Years",
"description_snippet": "Next Deadline: June 22, 2026"
}
]
},
"status": "success"
}
}About the FilmFreeway API
Search and Discovery
The search_festivals endpoint accepts an optional query string and returns paginated summaries of up to 50 festivals per page. Each result includes the festival's name, slug, url, location, and description_snippet. The slug field is the key identifier passed to all detail endpoints. Omitting query returns all festivals ordered by relevance. For category-scoped searches, search_festivals_by_category accepts a comma-separated categories string, allowing you to filter festivals that accept submissions in specific categories such as documentary, short film, or animation.
Festival Details and Fees
get_festival_details is the most data-dense endpoint, returning a festival's full description, rules, awards, address, organizers array, and structured deadlines — each deadline carries a human-readable date and an iso_date for reliable date parsing. The categories array lists each submission category alongside its associated fees. When you only need fee schedules, get_festival_categories_and_fees returns the same categories structure with fees broken down per deadline tier (early, regular, final, extended) and distinguishes standard pricing from Gold Member pricing.
Rules and Photos
get_festival_rules is a lightweight endpoint that returns only the rules and terms text for a given festival slug, returning null if no rules are published — useful when building submission eligibility checkers without pulling the full detail payload. The get_festival_photos endpoint returns a photo gallery array where each object includes id, href, caption, width, height, and order fields. The array may be empty if no photos have been uploaded for that festival.
The FilmFreeway API is a managed, monitored endpoint for filmfreeway.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when filmfreeway.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official filmfreeway.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a deadline tracker that parses
iso_datefields fromget_festival_detailsto alert filmmakers before submission windows close. - Aggregate per-category fee schedules across hundreds of festivals using
get_festival_categories_and_feesto help filmmakers budget their submissions. - Filter festivals by genre using
search_festivals_by_categorywith categories like 'documentary' or 'animation' to build niche festival directories. - Create an eligibility screener that checks
get_festival_rulesfor specific rule text relevant to runtime, language, or premiere status requirements. - Populate a festival discovery app with photos and descriptions by combining
get_festival_photosandsearch_festivalsresults. - Extract organizer contact info from
get_festival_detailsto build outreach lists for film industry directories. - Compare early vs. final deadline fee differences across festivals by parsing the tiered fee arrays from
get_festival_categories_and_fees.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does FilmFreeway have an official public developer API?+
How does pagination work across the search endpoints?+
search_festivals and search_festivals_by_category both return a page integer and a has_more boolean. When has_more is true, increment the page parameter to retrieve the next batch of up to 50 festival summaries.Does the API return filmmaker or film submission records?+
Are Gold Member fees consistently available for every festival's categories?+
get_festival_categories_and_fees when the festival publishes it. Some festivals may only list standard fees, so the Gold Member field may be absent or null for those entries.