# ImprovFetivals.org

> A curated wiki of improv festivals. Data is maintained by hand and verified
> against official sources.

## JSON API

The festivals dataset is available at:
https://improvfestivals.org/api/festivals.json

The response is an envelope object:

{
  "schema_version": 1,
  "source": "https://improvfestivals.org",
  "generated_at": "ISO 8601 datetime",
  "license": "CC BY-SA 4.0",
  "count": 80,
  "festivals": [...]
}

Each festival object has the following structure:

{
  "name": "string",
  "slug": "string (URL-safe identifier)",
  "description": "string (~150 chars)",
  "url": "string (canonical page URL on improvfestivals.org)",
  "date_start": "YYYY-MM-DD",
  "date_end": "YYYY-MM-DD",
  "location": "string (e.g. 'Portland, OR, USA' or 'Sofia, Bulgaria')",
  "websites": ["string (URL)", "..."],
  "languages": ["string", "..."],
  "submissions": {
    "start_date": "YYYY-MM-DD or empty string",
    "end_date": "YYYY-MM-DD or empty string",
    "status": "open | closed | empty string"
  },
  "last_updated": "ISO 8601 datetime"
}

Notes:
- All fields are plain text unless otherwise specified.
- `location` is a single string, not split into city/region/country.
- `websites` is an array (usually one entry, the official site).
- `languages` is an array of spoken/performance languages.
- `submissions` fields may be empty strings when unknown.
- There is no guaranteed unique ID; use `slug` or derive your own.

## Site Structure

### Home Page (`/`)

The home page lists all festivals in a searchable, filterable view. Users can filter by upcoming or past festivals and by submission status. Each entry links to its detail page.

### Festival Pages (`/festivals/{slug}`)

Each festival has its own page at a URL like `/festivals/asheville-improv-festival`. A festival page contains:

- **Title** heading with the festival name
- **Info table** with key facts: dates, edition, location, language(s), organizer, website, and social links (Instagram, Facebook) when available
- **Overview** describing the festival, its history, and mission
- **Headliners** listing featured performers and shows (when available)
- **Workshops** listing instructors and workshop descriptions (when available)
- **Submissions** with details on how to apply and deadlines (when available)
- **Sources** with reference links to official websites and other cited sources

Not all sections appear on every page; content varies by how much is known about a given festival.

### About Page (`/about`)

Describes the project, its maintainer, links to the JSON API, and the CC BY-SA 4.0 license.

## Usage

- Please do not fetch the festivals JSON more than once every 24 hours. The data is updated manually and changes infrequently.
- This data is licensed under CC BY-SA 4.0. If you use it, please attribute it to improvfestivals.org and link back to the source.

## Optional

- [Festival Index](https://improvfestivals.org/festivals): Browsable HTML listing of all festivals
- [Site Index](https://improvfestivals.org/): Top-level entry point for all wiki content