Festival API — Node.js Client

Client library for the Festival API.

npm install festivalapi

Usage

import { FestivalAPI } from "festivalapi";

const client = new FestivalAPI("fes_your_api_key");

// Search festivals by category (supports page/per_page pagination)
const festivals = await client.festivals.list({ category: "short_film" });
// Pagination: client.festivals.list({ category: "short_film", page: 2, per_page: 50 })

// Keyword search
const results = await client.festivals.list({ q: "Cambodia" });

// Get festival detail
const festival = await client.festivals.get(1);

// Get festival roster (supports pagination)
const roster = await client.festivals.roster(1);
// Pagination: client.festivals.roster(1, { page: 2, per_page: 50 })

// Get scored festivals (supports page/per_page)
const scored = await client.festivals.scored({ min_score: 70 });
// Pagination: client.festivals.scored({ page: 2, per_page: 50 })

// Health check (no API key)
const health = await client.health();

// List available country codes (requires auth)
const countries = await client.countries();
for (const c of countries.results) {
    console.log(`${c.country} (${c.count})`);
}

API Key

Sign up at festivalapi.com to get your API key. You can also set the FESTIVALAPI_KEY environment variable.

Error Handling

import {
  FestivalAPI,
  AuthenticationError,
  InsufficientCreditsError,
  NotFoundError,
} from "festivalapi";

try {
  await client.festivals.get(999999);
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log("Festival not found");
  }
}

Requirements

• Node.js 18+ (uses built-in fetch)
• No dependencies

License

MIT