How to Use the FindLocal Events API

September 4, 2026

Reference: the up-to-date endpoint, parameter and field tables now live at /docs. This post is the walkthrough.

Update: the JSON API now requires an API key — send it as an Authorization: Bearer <key> header. There’s a free tier; get a key at /pricing. The embeddable widgets and the map endpoint stay free and keyless.

Every listing page on Find Local has a JSON twin. The same filters you click on the site — city, date, category, price, time of day, neighborhood, performer, search — work as query parameters against https://findlocal.community/api/events, and the response is the same data the page renders. It requires an API key (there’s a free tier, no card — plans and quotas at /pricing), sent as an Authorization: Bearer <key> header, and CORS is open, so you can call it from a browser, a script, a spreadsheet, or a cron job.

If you’d rather have an AI assistant do the querying, see the companion guide on connecting FindLocal to Claude, Cursor, and other assistants over MCP.

Endpoints

Base URL: https://findlocal.community. Only GET (and OPTIONS) are supported.

Quick start

# Live music in Boston this week
curl 'https://findlocal.community/api/events?city=boston&cat=music&when=week&limit=5'

# Free things to do in Brooklyn this weekend, evenings only
curl 'https://findlocal.community/api/events?city=new-york&region=Brooklyn&when=weekend&free=1&tod=evening'

# Every active venue in Chicago
curl 'https://findlocal.community/api/venues?city=chicago'

Filtering /api/events

The parameters mirror the site’s URLs exactly: /city/boston?cat=music&when=weekend on the site is /api/events?city=boston&cat=music&when=weekend on the API.

Unknown values are ignored rather than rejected, so cat=jazz quietly matches nothing extra — check the response meta.total if a filter seems to have no effect.

Response shape

{
  "data": [ /* EventRow[] */ ],
  "meta": { "city": "Boston", "currency": "USD", "count": 5, "total": 82, "page": 1, "page_size": 5, "sort": "date" }
}

total is the full match count for the filters; count is how many rows are in this page; currency is the ISO code every price_amount in the page is in (GBP for London). /api/events?ids=… returns meta: { count } only, and /api/events/<uuid> returns { "data": {…} } or a 404 with { "error": "not found" }.

An event row looks like this (trimmed from a real response):

{
  "id": "8f9b9068-4e11-466b-a1cc-d36230d28fdd",
  "title": "Hooley Hour",
  "description": "donate to artists 5-7pm all ages",
  "event_date": "2026-09-04",
  "start_time": "17:00:00",
  "end_time": null,
  "city": "Boston",
  "region": "Cambridge",
  "category": "music",
  "event_type": ["Theater", "Music"],
  "performers": [{ "name": "The Hooley Band", "role": "headliner" }],
  "price": null,
  "price_amount": null,
  "detail_page_url": "https://www.lilypadinman.com/home/2026/hooley-hour-bs5y2-pl4db9",
  "ticket_page_url": null,
  "image_url": "https://images.squarespace-cdn.com/…/1000016764.jpg",
  "is_deleted": 0,
  "venue_id": "b7716a13-e708-4573-8445-ea786a47233e",
  "venue_name": "The Lilypad",
  "venue_address": "1353 Cambridge St, Cambridge, MA 02139",
  "venue_lat": 42.3738079,
  "venue_lng": -71.100088,
  "venue_url": "https://www.lilypadinman.com/",
  "venue_type": "Music Venue",
  "venue_region": "Cambridge",
  "series_count": 4,
  "series_image": "https://images.squarespace-cdn.com/…/1000016764.jpg",
  "source": "scraper_local",
  "first_seen_at": "2026-07-03T06:20:36.366Z",
  "last_seen_at": "2026-08-07T07:23:34.117Z",
  "updated_at": "2026-09-04T23:17:55.599Z"
}

Things worth knowing about the fields:

• event_date is a plain calendar day in the venue’s local time zone. Don’t new Date() it — that would shift it by your UTC offset. Combine it with start_time (24-hour HH:MM:SS, may be null) if you need a timestamp.
• price is the raw label from the venue (“$15 adv / $20 door”, “Free”, “Donation”); price_amount is our best parsed number in the city’s local currency (USD in the US, GBP in London), or null when we couldn’t parse one. free=1 uses both.
• category is one of the slugs above; event_type is the venue’s own genre tags.
• performers lists who the event is by — the bill, authors, instructors, speakers — each with a role (headliner, support, author, speaker, dj…). It’s empty when the venue doesn’t say. Search it with performer=.
• Single-event responses (/api/events/<uuid>) also carry books and authors for literary events: titles, ISBNs, covers, author bios and photos.
• series_count > 1 means the same title has that many upcoming dates at this venue (a weekly trivia night, a theater run). series_image is the first image found in that series. series_id is the stable id of that series; pass it as series_id= to list every date of that series. A title that repeats on several weekdays can carry one series_id per weekday, so series_count can be larger than one series_id= call returns.
• collapsed: 1 marks a dense (daily or near-daily) series listed once, with series_first / series_last. Pass collapse=0 for one row per date.
• end_date is set on a multi-day run stored as one event (an exhibition, festival or trade show): event_date is the first day, end_date the last. A run that opened before today stays in /api/events until its end_date. Runs listed performance by performance are separate events sharing a series_id instead.
• organizer names who puts the event on when that isn’t the venue (a talk series, promoter, festival or council programme). The venue_* fields always describe where it happens.
• duplicate_of: when the same show is listed under two venues we keep one. The other is never in lists; by id or in an updated_since sync it comes back with is_deleted: 1 and duplicate_of set to the event we kept.
• is_deleted: 1 means the venue stopped listing the event (or it is a cross-venue duplicate, see duplicate_of). /api/events never returns these; /api/events/<uuid> and ids= do, so you can render an honest “no longer listed” state.
• Booleans are 0/1, straight from the database.
• The public page for any event is https://findlocal.community/event/<id>, and an iCalendar file is at https://findlocal.community/event/<id>/calendar.ics.

A venue row from /api/venues:

{
  "id": "d21997e7-3a40-4863-8ef7-ad0227d80093",
  "name": "Agganis Arena",
  "city": "Boston",
  "region": "Boston",
  "address": "925 Commonwealth Ave, Boston, MA 02215",
  "url": "https://www.agganisarena.com/",
  "description": "Agganis Arena is a versatile venue hosting sports, concerts, and events.",
  "image": "https://img.findlocal.community/venues/d21997e7-3a40-4863-8ef7-ad0227d80093.jpg",
  "image_attribution": "\"Agganis Arena Exterior\" by …, CC BY-SA 4.0 (https://commons.wikimedia.org/…)",
  "image_source": "openverse",
  "type": "Arena & Stadium",
  "venue_size": "Large",
  "capacity": 7200,
  "categories": ["music"],
  "latitude": 42.3514544,
  "longitude": -71.1176226,
  "is_active": 1,
  "upcoming": 7
}

/api/venues accepts city and optional region, type, q (name search) and sort (name or upcoming). About the venue fields:

• type is one of a fixed list: 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.
• capacity is the maximum number of people when a source states one (Wikidata, the venue’s own site, a venue directory), else null. venue_size is Small (under 100), Medium (100-499) or Large (500+); it comes from capacity when known and is an estimate otherwise.
• image_attribution, when present, is the credit line the image’s Creative Commons license requires. Show it next to the image.

The public venue page is https://findlocal.community/venue/<id>.

Examples

JavaScript (browser or Node)

const params = new URLSearchParams({ city: 'seattle', when: 'weekend', cat: 'comedy,music', limit: '50' });
const res = await fetch(`https://findlocal.community/api/events?${params}`);
const { data, meta } = await res.json();

console.log(`${meta.total} events this weekend`);
for (const e of data) {
  console.log(`${e.event_date} ${e.start_time ?? ''} · ${e.title} @ ${e.venue_name}`);
}

Python

import requests

r = requests.get(
    "https://findlocal.community/api/events",
    params={"city": "denver", "when": "today", "free": "1"},
    timeout=15,
)
r.raise_for_status()
body = r.json()
for e in body["data"]:
    print(e["event_date"], e["start_time"], e["title"], "—", e["venue_name"])
print(body["meta"])

Paging through everything

# Page size is 100 by default; walk `page` until data comes back empty
curl 'https://findlocal.community/api/events?city=austin&page=1'
curl 'https://findlocal.community/api/events?city=austin&page=2'

Caching, freshness, and fair use

• Responses are cached at the edge for 5 minutes and in your browser for 1 minute (Cache-Control: public, max-age=60, s-maxage=300). Polling faster than that just returns the cached copy.
• Listings update as venues are re-scraped, typically daily. last_seen_at tells you the last time we saw an event on its source page.
• Coverage is 80+ metros across the US and the UK (London). The full list is in llms.txt and on the city pages.
• Every listing page also advertises its JSON twin with <link rel="alternate" type="application/json">, so you can discover the API URL for any filtered view from the page itself.
• The API needs an API key — send it as Authorization: Bearer <key> (the x-api-key header works too). A missing or invalid key returns 401; going over your rate limit or monthly quota returns 429 with a Retry-After header. There’s a free tier plus Indie and Business plans, and one key works for both this API and the MCP server. Please cache on your side, keep request rates reasonable, and link back to the event’s Find Local page or the venue’s own site.
• Field names are stable but the API is not formally versioned. New fields may appear; existing ones won’t be renamed without notice on this blog.

What’s next

• Connect FindLocal to Claude, Cursor, and other AI assistants (MCP) — the same data as tools an assistant can call; reference on the events MCP server page.
• Free events calendar widget — the same data on any web page, no key or code beyond one script tag.
• How Find Local finds events the big platforms miss — where the data comes from.
• The FindLocal platform page — the overview for teams building on the data.

← All posts