Festival API — Python Client

Client library for the Festival API.

pip install festivalapi

Usage

from festivalapi import FestivalAPI

client = FestivalAPI("fes_your_api_key")

# Search festivals by category (supports page/per_page pagination)
festivals = client.festivals.list(category="short_film")
# Pagination: client.festivals.list(category="short_film", page=2, per_page=50)

# Keyword search
results = client.festivals.list(q="Cambodia")

# Get festival detail
festival = client.festivals.get(1)

# Get festival roster (past winners / screened films, supports pagination)
roster = client.festivals.roster(1)
# Pagination: client.festivals.roster(1, page=2, per_page=50)

# Get scored festivals (supports page/per_page)
scored = client.festivals.scored(min_score=70)
# Pagination: client.festivals.scored(page=2, per_page=50)

# List available category codes (requires auth)
categories = client.categories()
for cat in categories["results"]:
    print(f'{cat["category"]} ({cat["count"]})')

# List available countries with festival counts (requires auth)
countries = client.countries()
for c in countries["results"]:
    print(f'{c["country"]} ({c["count"]})')

# Health check (no auth)
client.health()

Categories

Call client.categories() to get all available category codes. Returns:

{
  "count": 158,
  "results": [
    {"category": "short_film", "count": 60},
    {"category": "feature", "count": 55},
    {"category": "documentary", "count": 31},
    {"category": "animation", "count": 14},
    {"category": "horror", "count": 12},
    {"category": "experimental", "count": 10},
    {"category": "ai", "count": 10},
    {"category": "music_video", "count": 14},
    {"category": "web_series", "count": 9},
    {"category": "comedy", "count": 5},
    {"category": "sci_fi", "count": 5},
    {"category": "student", "count": 5},
    {"category": "lgbtq", "count": 3},
    {"category": "vr_360", "count": 2},
    ...
  ]
}

Common filters: short_film, feature, documentary, animation, horror, sci_fi, comedy, experimental, music_video, ai, web_series, student, lgbtq, vr_360.

Use the category field (lowercase) as the filter value — e.g. client.festivals.list(category="horror").

Countries

Call client.countries() to get all countries with festival counts. Returns:

{
  "count": 70,
  "results": [
    {"country": "United States", "count": 448},
    {"country": "United Kingdom", "count": 48},
    {"country": "Canada", "count": 46},
    {"country": "India", "count": 35},
    {"country": "Germany", "count": 37},
    {"country": "Italy", "count": 33},
    {"country": "France", "count": 20},
    ...
  ]
}

Use the country name as the filter value — e.g. client.festivals.list(country="United States").

API Key

Sign up at festivalapi.com to get your API key (starts with fes_). You can also set the FESTIVALAPI_KEY environment variable.

Error Handling

from festivalapi import FestivalAPI, NotFoundError, InsufficientCreditsError

client = FestivalAPI("fes_your_api_key")

try:
    festival = client.festivals.get(999999)
except NotFoundError:
    print("Festival not found")
except InsufficientCreditsError as e:
    print(f"Need more credits: {e}")

Requirements

• Python 3.9+
• Zero dependencies (uses only stdlib urllib)

License

MIT