# Bridge-Day Leave Optimizer

> Place your leave days around public holidays for the most days off in a row. Takes your number of leave days, the public holidays of your country and region and your weekend, and finds the leave days that give the most days off in breaks — computed exactly, not by trial and error — plus a list of the best bridge days around each holiday.

Part of usefulweb.app (https://usefulweb.app/). Part of [Hearth](https://hearth.usefulweb.app/) (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://hearthleaveoptimizer.usefulweb.app/ (interactive tool at https://hearthleaveoptimizer.usefulweb.app/tool)
- JSON API: POST https://hearthleaveoptimizer.usefulweb.app/api/v1/calculate with a JSON object of inputs (schema: https://hearthleaveoptimizer.usefulweb.app/api/v1/tool)
- OpenAPI: https://hearthleaveoptimizer.usefulweb.app/openapi.json
- MCP (Streamable HTTP): https://hearthleaveoptimizer.usefulweb.app/mcp - tool `hearth_leave_optimizer`

## Inputs
- country (select): Country
- subdivision (text): State or region (optional) - ISO 3166-2 code such as DE-BY (Bavaria) or CH-ZH. Without it only nationwide holidays count.
- from (date, required): Period from
- to (date, required): Period to
- leaveDays (integer): Leave days to plan
- minBreak (integer): Shortest break worth taking (days off in a row)
- maxBreaks (integer): Most separate breaks (0 = any number)
- weekendDays (multiselect): Weekend days
- closures (list): Extra days off without leave (optional) - One YYYY-MM-DD per line, for example company closing days.

## Method
- Days off are weekends (your weekend days), public holidays of the country (Nager.Date entries of type “Public”, nationwide plus your region) and extra closing days. Every other day is a working day that costs one leave day.
- A break is a run of days off that contains at least one leave day; it counts with its full length, weekends and holidays included, and only when it is at least the shortest break you want.
- The optimiser is an exact dynamic programme over the working days: taking working days k…e always opens the run from the day after the previous working day to the day before the next one, so the best plan is a set of non-adjacent ranges of working days. It maximises the days off in breaks; on a tie it uses fewer leave days, then the earlier plan. A test compares it with a brute-force search over every subset of working days.
- Bridge-day ideas list short breaks (1–4 leave days) that contain a public holiday, ranked by days off per leave day, without overlaps.

## Limits
- Check your contract, collective agreement and employer rules: some regions have extra local holidays, half days or company closures that are not in the data.