# Free Event Calendar Finder

> Find explicitly free events in your imported or linked public calendars. Combine your own ICS files or public feed URLs, process IANA time zones and bounded daily, weekly, monthly and yearly recurrence, and export sourced event occurrences.

Part of usefulweb.site (https://usefulweb.site/). Part of [Hearth](https://hearth.usefulweb.site/) (ownerApp: hearth). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://hearthfreeevents.usefulweb.site/ (interactive tool at https://hearthfreeevents.usefulweb.site/tool)
- JSON API: POST https://hearthfreeevents.usefulweb.site/api/v1/calculate with a JSON object of inputs (schema: https://hearthfreeevents.usefulweb.site/api/v1/tool)
- OpenAPI: https://hearthfreeevents.usefulweb.site/openapi.json
- MCP (Streamable HTTP): https://hearthfreeevents.usefulweb.site/mcp - tool `hearth_free_events`

## Inputs
- calendar (textarea): Calendar (.ics text)
- calendarUrl (url): Public .ics feed URL (optional)
- feeds (textarea): Additional public .ics URLs (one per line)
- from (date): From
- to (date): To
- timeZone (text): Display / floating-time zone
- query (textarea): Words in title or description
- freeOnly (boolean): Only explicitly free events

## Method
- UTC, all-day and supported IANA TZID/floating times. Local-time recurrence preserves the selected zone across daylight saving. Ambiguous fall-back times choose the first occurrence; nonexistent times are skipped.
- Daily, weekly, monthly and yearly recurrence supports INTERVAL, COUNT, UNTIL, BYMONTH, positive/negative BYMONTHDAY, ordinal BYDAY, WKST and BYSETPOS, plus RDATE, EXDATE and detached overrides/cancellations. Unsupported rules and malformed entries are counted with diagnostics; no invented occurrences.
- At most one year per search, 2,000 source entries per feed, five remote feeds and 2,000 displayed occurrences. Returned event text is capped at four million characters across the selected sources. Missing or failed sources do not prove that no event exists.
- Free status uses X-COST (0 = free) or X-FREE flags first. Otherwise the title and description must say the event itself is free: “free” before an event word (Free yoga, free guided tour), a title starting with “Free”, admission phrases (admission free, free to attend, no charge, Eintritt frei, entrada libre, entrée libre) or kostenlos/gratis/gratuit not tied to an extra. Explicit “not free”/kostenpflichtig wins.
- Free parking, drinks or Wi-Fi, compounds such as gluten-free or sugar-free and idioms such as free jazz do not count. This is source-based calendar search, not a regional discovery database.