Embeddable widgets
One script tag drops a live list, calendar and map of upcoming events onto any page — a bookstore's site, a library newsletter, a neighborhood blog. It sizes itself, follows your visitor's light/dark setting, and every event links back to FindLocal with a "Powered by FindLocal" credit.
Quick start
Paste this where the calendar should appear:
<script src="https://findlocal.community/widget.js" data-widget="literary-new-england"></script>That's the Literary New England preset: author talks, readings, book clubs and poetry across the region's independent bookstores, libraries and literary organizations, in 18 metros from Stamford to Bangor.
Build your own
<script src="https://findlocal.community/widget.js" data-widget="literary-new-england"></script>Live preview
Attributes
| Attribute | Values | Notes |
|---|---|---|
data-widget | literary-new-england · new-england | A preset: expands to a region + category. Explicit attributes override it. |
data-region | new-england | A region group (several metros). Wins over data-city. |
data-city | City slug or name, e.g. boston, portland-me | One metro. Defaults to Boston when neither region nor city is set. |
data-cat | Comma list of category slugs | Leave out for all categories. |
data-when | anytime · today · tomorrow · weekend · week · YYYY-MM-DD | Date window, resolved in the local time zone. Default anytime (everything upcoming). |
data-view | list · calendar · map | Initial view; visitors can switch. Default list. |
data-theme | auto · light · dark | auto follows the visitor's OS setting. Default auto. |
data-limit | 1–300 | Maximum events loaded. Default 100. Past the limit the widget links to FindLocal for the rest. |
data-height | Pixels | Initial iframe height before the widget reports its real height (default 320). |
data-partner | Short id, e.g. your site name | Added to outbound links as utm_content so you can see referrals in FindLocal's stats. |
Region groups
A region group bundles several metro partitions into one widget. The API and MCP tools are per-city; widgets are the one place a multi-metro area is a single thing.
| Slug | Name | Metros |
|---|---|---|
new-england | New England | Boston, Providence, Hartford, New Haven, Stamford, Worcester, Northampton, Pittsfield, Cape Cod, Portland ME, Rockland, Bangor, Manchester, Portsmouth, Brattleboro, Hanover, Rutland, Burlington |
Want another group (Bay Area, Texas Triangle, the Carolinas)? Ask — it's a one-line change on our side.
How it works
widget.js(about 2 KB, no dependencies) inserts an<iframe>pointing athttps://findlocal.community/embed/events?…right after the script tag, so styles never leak in either direction.- The frame reports its height with
postMessage({ type: "findlocal:resize", height }); the loader only trusts messages from its own frame and origin. Several widgets on one page work independently. - The embed page is server-rendered from the same database as the site and cached for 10 minutes at the edge. Listings update as venues are re-scraped, typically daily.
- Links open in a new tab and carry
utm_source=widget,utm_medium=embed,utm_campaign=<scope>and, if you setdata-partner,utm_content=<partner>. Because links open from inside the frame, the referrer FindLocal sees is its own domain — the UTM parameters are how we tell partners apart. - No cookies, no tracking scripts, no visitor data leaves the page. The frame requests
geolocation 'none'. - Content Security Policy: the embed pages send
frame-ancestors *; nothing else on findlocal.community is framable.
Terms
- Free for any site. Keep the "Powered by FindLocal" credit visible and don't obscure it.
- Event details come from venue calendars and ticketing pages — always confirm with the venue. See the terms of service.
- If your widget will see serious traffic, or you'd like a custom preset, a co-branded header or events limited to your own venue, email findlocalinternal@gmail.com.
Background: Put live local events on your site on the blog.