festivalapi 0.2.3

Python client for the Festival API — film festival data for developers

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
festivals = client.festivals.list(category="short_film")

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

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

# Get festival roster (past winners / screened films)
roster = client.festivals.roster(1)

# Get scored festivals
scored = client.festivals.scored(min_score=70)

# List available category codes (requires auth)
categories = client.categories()
for cat in categories["results"]:
    print(f'{cat["category"]} ({cat["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").

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