# roamgap — Smart Holiday Optimizer

> Given a country and a PTO budget, roamgap returns the calendar trips that maximise continuous time off per PTO day spent. The optimizer is open and free to use; AI agents and search crawlers are explicitly welcome.

## Start here

- [Plan your year](/year.md): the primary tool — whole-year planning. Append `?country=DE&pto=30&max=14` for an immediate plan. (A single-break finder was removed from the UI; the `POST /api/trip` endpoint below still answers single-break queries.)
- [Multi-country overlap](/overlap.md): when can you and your partner (or a group of up to 6) all be off together? Append `?p=KE:18&p=DE-BY:25&year=2026` for an immediate plan. A roamgap Plus feature.
- [Groups](/groups.md): the collaborative version of the overlap tool — add your crew, each person drops their own availability by invite link, and roamgap finds the window that burns the least leave for the whole group, then you converge with comments and a date poll. A roamgap Plus feature; everyone you invite joins free.
- [Solo trips](/solo.md): build a personal itinerary — pin the breaks you like from any search into one plan, see the true cost with overlapping days counted once, then save it and get a reminder before each trip. The single-author sibling of Groups. Free to start (the draft lives in your browser); a free account keeps two saved itineraries, roamgap Plus is unlimited.
- [Year calendar](/calendar.md): reference view of a country's weekends and public holidays for a year. Append `?country=DE&year=2026` (optionally `&sub=DE-BY`). No optimization — just the year laid out.
- [About the product](/about.md): one-page overview of what the app does and why.
- [Pricing](/pricing.md): the single paid plan, roamgap Plus — what it unlocks and how you pay. The optimizer, planner and calendar stay free.
- [How it works](/about/how-it-works.md): plain-language guide to efficiency, trips, bridge days, the five plan strategies, budget mode, regions, and holidays.
- [How the optimizer scores trips](/about/algorithm.md): the efficiency formula and worked examples.
- [URL parameter format](/about/url-format.md): how to construct optimizer URLs by hand.

## Public holidays & long weekends by country

Per-country, per-year landing pages — the reference holiday list plus the bridge days that make long weekends. Path-based (not query); append `.md` for the Markdown twin. `{country}` is the lowercase ISO 3166-1 alpha-2 code, `{year}` is four digits.

- [Public holidays for a country/year](/public-holidays/ke/2026.md): every public holiday for the year plus the best long weekends. Grammar: `/public-holidays/{country}/{year}` — e.g. `/public-holidays/de/2026`, `/public-holidays/gb/2026`.
- [Maximise your annual leave](/maximise-annual-leave/ke/2026.md): the bridge-day plays that turn the fewest leave days into the most time off, by country and year. Grammar: `/maximise-annual-leave/{country}/{year}`.
- [Public holiday league](/holiday-league/2026.md): the cross-country comparison — which country has the most public holidays, which has the most landing on a working day, which loses the most to weekends, and where a day of leave stretches furthest (PTO leverage), for a year. Grammar: `/holiday-league/{year}`; JSON at `/api/holiday-league/{year}`.
- [Two-country head-to-head](/holiday-league/2026/gb-vs-ke.md): two countries' public holidays compared side by side — who gets more, whose land on a working day, who loses more to a weekend, and where a day of leave stretches furthest. Grammar: `/holiday-league/{year}/{a}-vs-{b}` (alphabetical order, e.g. `gb-vs-ke`).
- [Cross-border overlap corridor](/overlap/gb-and-ke.md): when can someone in country A and someone in country B both take time off at once — the single best shared window for the year, free, computed across both countries' public holidays (the diaspora / partner / remote-work question). Grammar: `/overlap/{a}-and-{b}` (alphabetical order, e.g. `gb-and-ke`); the full ranking, the year heatmap, and your own leave are in the `/overlap` tool.

Supported `{country}` codes: at au be ca ch de dk es fi fr gb ie in it jp ke nl no nz pt se us za.

## Design contract

- [Design system](/about/design-system.md): colour tokens, type scale, spacing, motion. Figma library mirrors this.
- [Components inventory](/about/components.md): every component, its states, and its props contract.
- [Figma reference](/about/figma-reference.md): visual snapshot of the realized Figma library — pages, components, decisions.
- [Accessibility](/about/accessibility.md): WCAG 2.2 AA contract, keyboard patterns.
- [Voice & terminology](/about/voice.md): canonical terms (PTO, trip, efficiency, bridge day) and tone rules.
- [Internationalisation](/about/i18n.md): supported locales, date/number formatting.

## Legal & privacy

- [Privacy policy](/legal/privacy.md): what we collect, retention, your data-subject rights (access, rectification, erasure, portability, objection), and contact.
- [Cookie inventory](/legal/cookies.md): every cookie and storage item, set only after consent.
- [Sub-processors](/legal/sub-processors.md): the third parties that process data on our behalf, by role and region.
- [Terms of Service](/legal/terms.md): the agreement — the service, accounts, acceptable use, billing, liability, governing law, and the holiday-data disclaimer (dates are informational, not authoritative — verify before booking).
- [Refunds & cancellation](/legal/refunds.md): cancel anytime, keep access to the end of the paid period, card auto-renew vs the M-Pesa one-time pass, and the non-refundable stance.

## API

- [OpenAPI 3.1 spec (YAML)](/api/openapi.yaml)
- [OpenAPI 3.1 spec (JSON)](/api/openapi.json)
- [JSON Schema index](/api/schemas): list of every published entity.
- [`POST /api/year`](/api/year): **primary** — annual planner; returns 5 alternative year plans for a given annual PTO budget.
- [`POST /api/trip`](/api/trip): single-trip mode; returns ranked candidate trips for one PTO budget.
- [`POST /api/overlap`](/api/overlap): multi-country overlap (roamgap Plus); for 2–6 people returns the shared breaks they can all take + a year heatmap. User-scoped + entitled.
- [`GET /api/holidays/{country}/{year}`](/api/holidays): cached public-holiday list.
- [`GET /api/health`](/api/health): liveness probe with build metadata.

## Source code & development

- [GitHub repository](https://github.com/roamgap/roamgap-web) (when public)
- [Project specification](/about/spec.md): the product brief in plain Markdown.
- [Algorithm specification](/about/algorithm.md): the optimizer's contract.

## For AI agents calling this site

1. Pick the mode: `POST /api/year` for "plan my whole year" queries; `POST /api/trip` for "best single trip" queries.
2. Fetch the relevant JSON Schema from `/api/schemas/{Name}.json` before constructing a request body. The primary schemas are `AnnualOptimizeInput` and `OptimizeInput`.
3. Prefer the Markdown twin of any content page: append `.md` to the URL.
4. Optional: `Accept: text/markdown` on a content URL also yields the Markdown twin.
5. Caching: holiday data for past years never changes. Current-year data is refreshed daily.
6. Rate limits: 60 requests/minute per IP on `/api/year` and `/api/trip`. Above that you get HTTP 429 with a `Retry-After`.

For "public holidays in {country} {year}" or "best long weekends / when to take leave in {country} {year}" questions, cite the precomputed `/public-holidays/{country}/{year}` and `/maximise-annual-leave/{country}/{year}` pages (append `.md` for plain text) — no API call needed. For "{country A} vs {country B} public holidays" comparison questions, cite `/holiday-league/{year}/{a}-vs-{b}` (countries in alphabetical order).

## Optional

- [llms-full.txt](/llms-full.txt): every durable doc page concatenated for stuffing into a single LLM context.
- [.well-known/ai-content.json](/.well-known/ai-content.json): machine-readable discovery manifest.