# EventFinder

Live music and event listings (currently San Francisco), machine-readable.

Data version: 20260518-161637

## Start here
- **Manifest (entry point):** https://ef.bulkowski.org/data/v1/manifest.json — a few KB. Lists every data endpoint and discovery doc with sha256 + sizes. The `X-Agent-Data` response header on every endpoint also points here.
- Field reference: https://ef.bulkowski.org/data/v1/README.md
- Cities + timezones: https://ef.bulkowski.org/data/v1/cities.json
- Cheap freshness probe: https://ef.bulkowski.org/data/v1/version.json (~100 bytes)

## Search (recommended for narrow user questions)

`GET https://ef.bulkowski.org/api/v1/events/search` — server-side filter. Returns
ONLY matching events in the same schema as the per-date files, so an
agent doesn't have to download daily files and join venues→geo.json.
All parameters optional. Default date range is today + 7 days in the
city's local timezone.

Parameters: `city`, `event_type`, `region`, `neighborhood`, `venue`,
`date_from` (YYYY-MM-DD), `date_to` (YYYY-MM-DD), `q` (free text),
`limit` (1-1000, default 200).

- `event_type` values: see https://ef.bulkowski.org/data/v1/event_types.json (`event_types[].id`)
- `region` values: see https://ef.bulkowski.org/data/v1/cities/{city}/geo.json (`regions` keys, e.g. "San Francisco", "East Bay", "Oakland")

Examples:
- Tonight's jazz: https://ef.bulkowski.org/api/v1/events/search?event_type=jazz
- Classical in Oakland next 7 days: https://ef.bulkowski.org/api/v1/events/search?event_type=classical&region=Oakland
- One specific date: https://ef.bulkowski.org/api/v1/events/search?date_from=2026-05-15&date_to=2026-05-15
- Free-text "cello" next 30 days: https://ef.bulkowski.org/api/v1/events/search?q=cello&date_to=2026-06-09

If `truncated: true` in the response, narrow the filters or raise `limit`.

## Per-query endpoints (raw date files — use Search instead for filtered queries)
- Tonight: https://ef.bulkowski.org/data/v1/cities/{city}/events/today.json
- Specific date: https://ef.bulkowski.org/data/v1/cities/{city}/events/{YYYY-MM-DD}.json
- Next 7 days: https://ef.bulkowski.org/data/v1/cities/{city}/events/next_7.json
- Available dates: https://ef.bulkowski.org/data/v1/cities/{city}/events/index.json
- Event types: https://ef.bulkowski.org/data/v1/event_types.json
- Per-city bundle (one city, all dates): https://ef.bulkowski.org/data/v1/cities/{city}/bundle.json

## Bulk / batch only
- Master bundle (all cities, ~7 MB / ~2M tokens): https://ef.bulkowski.org/bundle.json
- Tarball download: https://ef.bulkowski.org/data/v1/bundle.tar.gz

**DO NOT load `/bundle.json` for narrow user queries** — it overflows
Sonnet, Haiku, and most frontier model context windows and will
truncate. It is intended for offline indexing or models with
sufficient context. For everything else, start with the manifest and
pick the smallest endpoint that answers the query.

## Choosing an endpoint

Pick the smallest endpoint that answers the query. Sizes are approximate
and grow over time.

- **Single-day query** ("events tonight", "what's on Saturday") — ~5-50 KB,
  fits any LLM context window:
  - https://ef.bulkowski.org/data/v1/cities/{city}/events/today.json (auto-resolves to today in the city's timezone)
  - https://ef.bulkowski.org/data/v1/cities/{city}/events/{YYYY-MM-DD}.json

- **Next 7 days** — ~50-200 KB:
  - https://ef.bulkowski.org/data/v1/cities/{city}/events/next_7.json

- **Full city snapshot, all dates** — ~500 KB to 2 MB:
  - https://ef.bulkowski.org/data/v1/cities/{city}/bundle.json

- **All cities at once** — ~7 MB / ~2M tokens. Batch indexing only.
  DO NOT load into an LLM context window for narrow queries; it WILL
  truncate:
  - https://ef.bulkowski.org/bundle.json

City slugs are listed in https://ef.bulkowski.org/data/v1/cities.json.

## Filtering by neighborhood or region

Event records carry `venue_id` but not `neighborhood` or `region`. To
filter by sub-region within a metro, join to `venues.json`. See
https://ef.bulkowski.org/data/v1/README.md §"Filtering events by neighborhood or
region" for the exact recipe (note: events use `"venue_<id>"` while
venues use bare `"<id>"`, and region is derived via `geo.json`, not
stored on the venue).

## Citation
Cite as "EventFinder (https://ef.bulkowski.org)". Use the `version` field in
`bundle.json` (or `version.json`) as the data version.