# FindLocal Events API

Hyper-local events for 84 metros across the US and UK — concerts, readings, film screenings, talks, classes, trivia, open mics, storytimes — with venues and coordinates. REST + an MCP server, one key for both. Human docs and playground: https://findlocal.community/docs · OpenAPI: https://findlocal.community/openapi.json

## Quickstart
1. Create a free account at https://findlocal.community/signup (no card) and mint a key at https://findlocal.community/dashboard/keys.
2. Send it as a Bearer token:
```bash
curl "https://findlocal.community/api/events?city=boston&when=weekend&free=1" \
  -H "Authorization: Bearer $FINDLOCAL_KEY"
```
3. Read `data` (events) and `meta` (`total`, `page`, `page_size`). Page with `page=2`.
No key yet? The playground at https://findlocal.community/docs runs real queries in the browser, 5 rows a call.

## Authentication
Every `/api/events`, `/api/events/{id}` and `/api/venues` call needs a key: `Authorization: Bearer <key>` (or `X-API-Key: <key>`).
Keep keys server-side where you can; a key in browser code is visible to anyone. One account can hold 5 named keys — use one per app so you can revoke them separately.
The same key authorises the MCP server (https://mcp.findlocal.community/mcp).

## Endpoints

Base URL `https://findlocal.community/api`. JSON over HTTPS, `GET` only, CORS open. Responses are `{ "data": …, "meta": … }`.

### GET https://findlocal.community/api/events
Search upcoming events. Upcoming events in one metro, filtered. Every parameter is optional; with none you get Boston, chronological.

See **Filters** — every parameter is optional.

### GET https://findlocal.community/api/events/{id}
One event. A single event by id — past and delisted events included (`is_deleted`).

- `id` (required) — string

### GET https://findlocal.community/api/venues
Venues in a metro. Active venues with their upcoming-event counts.

- `city` — Metro slug (or name). One of: `ann-arbor`, `atlanta`, `austin`, `baltimore`, `bangor`, `bloomington`, `boise`, `boston`, `brattleboro`, `buffalo`, `burlington`, `cape-cod`, `charleston`, `charlotte`, `chicago`, `cincinnati`, `cleveland`, `columbia-mo`, `columbus`, `dallas`, `denver`, `des-moines`, `detroit`, `duluth`, `fort-collins`, `grand-rapids`, `green-bay`, `hanover`, `harrisburg`, `hartford`, `hilton-head`, `houston`, `hudson-valley`, `indianapolis`, `iowa-city`, `jersey-shore`, `kansas-city`, `lansing`, `las-vegas`, `lincoln`, `london`, `los-angeles`, `madison`, `manchester`, `miami`, `milwaukee`, `minneapolis`, `nashville`, `new-haven`, `new-orleans`, `new-york`, `northampton`, `oklahoma-city`, `orlando`, `philadelphia`, `phoenix`, `pittsburgh`, `pittsfield`, `portland`, `portland-me`, `portsmouth`, `providence`, `raleigh`, `rochester`, `rockland`, `rutland`, `sacramento`, `salt-lake-city`, `san-antonio`, `san-diego`, `san-francisco`, `santa-barbara`, `seattle`, `sonoma`, `spokane`, `st-louis`, `stamford`, `tampa`, `traverse-city`, `tucson`, `washington`, `wenatchee`, `wilmington-nc`, `worcester`. Default `boston`.
- `region` — Neighborhood / sub-area.
- `q` — Substring match on the venue name.
- `type` — Venue type, case-insensitive: Music Venue, Performing Arts Center, Theater, Comedy Club, Bar, Nightclub, Brewery & Winery, Restaurant, Cafe, Bookstore, Library, Museum, Art Gallery, University & College, Arena & Stadium, Park & Outdoors, Community Center, Place of Worship, Market, Festival Grounds, Other.
- `sort` — Order. One of: `name`, `upcoming`. Default `name`.

### Event object

- `id` (string)
- `title` (string)
- `description` (string | null)
- `event_date` (string) — Calendar day in the venue's own time zone.
- `start_time` (string | null) — HH:MM, 24-hour, venue-local.
- `end_time` (string | null)
- `category` (string | null) — music | comedy | theater | dance | literary | film | talks | art | food_drink | family | market | workshop | fitness | nightlife | community | festival | parks
- `event_type` (array)
- `performers` (array) — Who the event is by: the bill, authors, instructors, speakers. Empty when unknown. Search it with `performer` (or `q`).
- `price` (string | null) — Price label as published, e.g. "$18 adv / $22 door".
- `price_amount` (number | null) — Parsed lowest price in the city's local currency (USD for US metros, GBP for London); 0 = free.
- `status` (string | null) — What the source states: scheduled | cancelled | postponed | rescheduled | sold_out. Null when the source does not say.
- `detail_page_url` (string | null)
- `ticket_page_url` (string | null)
- `image_url` (string | null)
- `city` (string) — Metro name. Its currency is the currency of `price_amount` (single-event responses carry no `meta.currency`).
- `region` (string | null)
- `venue_id` (string)
- `venue_name` (string)
- `venue_address` (string | null)
- `venue_lat` (number | null)
- `venue_lng` (number | null)
- `venue_url` (string | null)
- `venue_image` (string | null)
- `venue_region` (string | null)
- `venue_type` (string | null) — The venue's type: Music Venue | Performing Arts Center | Theater | Comedy Club | Bar | Nightclub | Brewery & Winery | Restaurant | Cafe | Bookstore | Library | Museum | Art Gallery | University & College | Arena & Stadium | Park & Outdoors | Community Center | Place of Worship | Market | Festival Grounds | Other.
- `venue_capacity` (integer | null) — Venue capacity, when known.
- `venue_size` (string | null) — Small | Medium | Large | Unknown.
- `author_ids` (array)
- `book_ids` (array)
- `series_count` (integer) — Upcoming dates of the same recurring event at this venue.
- `series_image` (string | null) — First image in the recurring series — a fallback when `image_url` is empty.
- `books` (array) — Single-event responses only: the books behind `book_ids` (title, isbn13, cover_url, publisher, pub_year…).
- `authors` (array) — Single-event responses only: the authors behind `author_ids` (canonical_name, photo_url, bio, wikipedia_url…).
- `is_deleted` (integer)
- `updated_at` (string)

### Venue object

- `id` (string)
- `name` (string)
- `city` (string)
- `region` (string | null)
- `address` (string | null)
- `latitude` (number | null)
- `longitude` (number | null)
- `type` (string | null) — One of: Music Venue | Performing Arts Center | Theater | Comedy Club | Bar | Nightclub | Brewery & Winery | Restaurant | Cafe | Bookstore | Library | Museum | Art Gallery | University & College | Arena & Stadium | Park & Outdoors | Community Center | Place of Worship | Market | Festival Grounds | Other.
- `venue_size` (string | null) — Small | Medium | Large | Unknown. Small is under 100 people, Medium 100-499, Large 500+; derived from `capacity` when that is known, otherwise an estimate.
- `capacity` (integer | null) — Maximum capacity (people), when a source states one: Wikidata, the venue's own website, or a venue directory. null = unknown.
- `categories` (array)
- `url` (string | null)
- `image` (string | null)
- `image_attribution` (string | null) — Credit line for `image` (Wikimedia Commons / Openverse CC licenses). When present you must display it next to the image.
- `description` (string | null)
- `upcoming` (integer) — Upcoming (non-deleted) events at this venue.
- `wikidata_id` (string | null) — Matched Wikidata entity, e.g. Q123456.
- `wikipedia_url` (string | null)
- `image_source` (string | null)
- `description_source` (string | null)

## Filters (`GET /api/events`)
- `city` — metro slug, default `boston`. 84 metros (US and UK): `ann-arbor`, `atlanta`, `austin`, `baltimore`, `bangor`, `bloomington`, `boise`, `boston`, `brattleboro`, `buffalo`, `burlington`, `cape-cod`, `charleston`, `charlotte`, `chicago`, `cincinnati`, `cleveland`, `columbia-mo`, `columbus`, `dallas`, `denver`, `des-moines`, `detroit`, `duluth`, `fort-collins`, `grand-rapids`, `green-bay`, `hanover`, `harrisburg`, `hartford`, `hilton-head`, `houston`, `hudson-valley`, `indianapolis`, `iowa-city`, `jersey-shore`, `kansas-city`, `lansing`, `las-vegas`, `lincoln`, `london`, `los-angeles`, `madison`, `manchester`, `miami`, `milwaukee`, `minneapolis`, `nashville`, `new-haven`, `new-orleans`, `new-york`, `northampton`, `oklahoma-city`, `orlando`, `philadelphia`, `phoenix`, `pittsburgh`, `pittsfield`, `portland`, `portland-me`, `portsmouth`, `providence`, `raleigh`, `rochester`, `rockland`, `rutland`, `sacramento`, `salt-lake-city`, `san-antonio`, `san-diego`, `san-francisco`, `santa-barbara`, `seattle`, `sonoma`, `spokane`, `st-louis`, `stamford`, `tampa`, `traverse-city`, `tucson`, `washington`, `wenatchee`, `wilmington-nc`, `worcester`.
- `when` — Date window, resolved in the metro's own time zone — or one day as YYYY-MM-DD.
- `date_from` — Inclusive start day (YYYY-MM-DD) of an explicit window; used when `when` is absent. Defaults to today.
- `date_to` — Inclusive end day (YYYY-MM-DD) of an explicit window; used when `when` is absent. Open-ended when omitted.
- `updated_since` — Incremental sync: only events changed at or after this ISO-8601 instant, delisted ones included (`is_deleted: 1`). Pass the previous response's `meta.synced_at`.
- `cat` — Comma list of category slugs. `literary` also matches everything at bookstores and libraries.
- `free` — Free events only. One of: `1`.
- `paid` — Paid events only. One of: `1`.
- `max` — Maximum price in the city's local currency (USD for US metros, GBP for London; events with a parsed price).
- `tod` — Comma list of times of day.
- `region` — Neighborhood / sub-area inside the metro, e.g. Cambridge.
- `q` — Free text, matched word by word (up to 4 words; every word must match): event title, venue name, neighbourhood/town, description, performer and author names, and linked book titles. Common words like "the" and "in" are ignored.
- `performer` — Substring match on performer names only.
- `authors` — Only events with a known author on the bill. One of: `1`.
- `near` — Proximity search: `<lat>,<lng>`. Orders by distance and overrides `sort`.
- `radius_km` — Radius for `near` (default 25, max 200). Default `25`.
- `sort` — `date` is chronological; `featured` is the site's editorial ranking. One of: `featured`, `date`. Default `date`.
- `page` — 1-based page of `limit` rows (100 when no `limit`). Ignored by the playground server. Default `1`.
- `limit` — Rows per call (max 500). The playground server caps this at 5 (100 signed in).
- `venue` — A venue uuid: upcoming events at that venue (the metro comes from the venue).

Category slugs for `cat`: `music`, `comedy`, `theater`, `dance`, `literary`, `film`, `talks`, `art`, `food_drink`, `family`, `market`, `workshop`, `fitness`, `nightlife`, `community`, `festival`, `parks`.

## Errors
Errors are JSON: `{ "error": "message" }`.
- `400` — a malformed parameter.
- `401` — missing, invalid, expired or revoked key.
- `404` — unknown event id.
- `429` — per-minute rate limit or monthly quota exceeded. Honour `Retry-After` (seconds).
- `503` — key verification is briefly unavailable; retry with backoff. The API fails closed rather than serving unmetered.

## Rate limits and quotas
Two limits apply. Both are per ACCOUNT: all of an account’s keys share one **monthly quota** (REST and MCP calls alike; more keys never add calls), refilled on the 1st (UTC), and one **per-minute limit**.
- Free: 1,000 calls/month, 30 requests/minute
- Hobby: 10,000 calls/month, 60 requests/minute
- Pro: 75,000 calls/month, 120 requests/minute
Every successful response carries `X-RateLimit-Remaining` (calls left this MONTH on the account), `X-RateLimit-Limit` (requests per MINUTE) and `X-RateLimit-Reset` (Unix seconds when the minute window reopens). Each call costs one credit, cached or not. Unknown query parameters are ignored, never an error — `meta.ignored_params` and the `X-FindLocal-Warning` header list them (e.g. `category` → use `cat`).
On `429`, wait `Retry-After` seconds. For bulk work, stay under the per-minute limit and cache results — events change at most a few times a day. To keep a copy in sync, fetch the window once, then poll with `updated_since=<meta.synced_at>`: only changed rows come back, delisted ones as `is_deleted: 1`.

## Plans
- **Free** — free, no card: 1,000 calls/month, 30/min. For trying the API and small projects.
- **Hobby** — $9/month: 10,000 calls/month, 60/min. For side projects that got serious.
- **Pro** — $49/month: 75,000 calls/month, 120/min. For production apps and agents.
- **Enterprise** — more than Pro (custom quota, higher burst limit, invoicing): email elliot@findlocal.community.
Upgrade, downgrade or cancel at https://findlocal.community/dashboard/billing. Existing keys move to the new limits at once.
**Attribution.** On the Free plan, show a visible link back wherever the data is displayed — `<a href="https://findlocal.community" rel="noopener">Event data by FindLocal</a>` or equivalent wording. Paid plans need no attribution. Full API terms (caching, redistribution): https://findlocal.community/terms#api.

## MCP server
Endpoint: `https://mcp.findlocal.community/mcp` (Streamable HTTP; OAuth 2.1 + PKCE). On first connect you paste an API key.
- Claude Code:
```bash
claude mcp add --transport http findlocal https://mcp.findlocal.community/mcp
```
- Cursor (`~/.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "findlocal": {
      "url": "https://mcp.findlocal.community/mcp"
    }
  }
}
```
- Claude.ai / Claude Desktop: Settings → Connectors → Add custom connector → paste the endpoint.
Event tools cost one credit per call; `get_usage`, `get_api_docs` and `get_setup_guide` are free.

## Widgets (no code)
An embeddable list, calendar or map — one script tag, free, no key. The widget is inserted after the tag:
```html
<script src="https://findlocal.community/widget.js" data-city="boston" data-view="list"></script>
```
Attributes: `data-widget` (a catalogue preset, e.g. `literary-new-england`), `data-city` (one metro or a comma list of up to 25), `data-region`, `data-cat`, `data-when`, `data-from` + `data-to` (YYYY-MM-DD), `data-view` (list | calendar | map | compact | strip — compact is a 5-event sidebar list, strip a row of 8 thumbnails; neither has filters), `data-more` (your full events page: compact/strip link there and open a clicked event there), `data-seo="off"` (no schema.org Event JSON-LD on your page; default on for list/calendar/map, off for compact/strip), `data-theme` (light | dark | auto), `data-limit` (1-300), `data-height` (initial px), `data-max-height` (px or `none`; default 85% of the window, 420-900 px — past it the widget scrolls inside itself), `data-partner`, `data-authors="1"` (only events with a known author), `data-free="1"`, `data-near="<lat>,<lng>"` + `data-radius` (km, default 25; replaces the metro scope), `data-filters="off"` (hide the visitor filter toolbar).
Dates and prices render in the metro's own locale and currency (e.g. 24-hour times and £ for London).
Visitors stay on the host site: clicking an event opens a details panel inside the widget, whose only outbound link is the venue's own ticket/event page.
Live builder: https://findlocal.community/widgets.