# FOMO Sun - Find Sun Fast

> FOMO Sun answers "where is there sun within reach?" for people in Switzerland: it ranks 387 day-trip destinations in Switzerland and nearby Germany, France, Italy, Austria and Liechtenstein by how much more sun they get than your city, against how long it takes to get there (car or train, up to 6.5 hours).

## What This Service Does

Given an origin and a day, FOMO Sun compares the sun hours at home with the sun hours at each reachable place (after the travel time), and returns the places that clearly beat staying home, grouped by travel time. On fog days it also reports the top of the Swiss Plateau fog sea (Nebelobergrenze) and which places are above it. From October to April it prefers a much warmer place when the sunniest one is near freezing.

The ranking is rule-based (documented in the repository's `docs/ALGORITHM.md`), on MeteoSwiss forecasts. It is not a language model.

## Pages

- `/` the app: pick a city and a day, steer the travel tuner, see the best place per travel time.
- `/from/{city}` sunny day trips from one of the 17 app cities today (`/from/zurich`), plus `/tomorrow` and `/weekend`: the best place per travel time, home's sun, the week. Index at `/from`.
- `/fog` the fog line today: how high the Swiss Plateau fog sea reaches today and the next four days, which cities are under it, and the nearest sunny places above it from Zurich, Basel and Bern.
- `/map` the sun map: every place as a pin, coloured by sun, with a day slider.
- `/destinations` and `/destinations/{id}`: one page per destination (region, altitude, plan, nearby places).
- `/blog`: build notes and how the app works.

German versions: `/de/nebel` (fog line) and `/de/von/{stadt}` (`/de/von/zuerich`, `/morgen`, `/wochenende`).

Longer version with every destination: `/llms-full.txt`.

## API

Main endpoint:

```
GET /api/v1/sunny-escapes?lat={lat}&lon={lon}&max_travel_h={hours}&mode={car|train|both}
```

### Parameters
- `lat`, `lon`: Origin coordinates (default: Basel, Switzerland)
- `origin_name`: Optional origin label (e.g. `Zurich`)
- `max_travel_h`: Maximum travel time in hours (0.5-6.5)
- `mode`: `car`, `train` or `both` (default: both)
- `ga`: Whether the user has a Swiss GA rail pass (true/false)
- `types`: Comma-separated filter: nature, viewpoint, town, lake, family, food, mountain, thermal
- `trip_span`: `daytrip` (today) or `plus1day` (a planned day)
- `plan_date`: `YYYY-MM-DD`, 1 to 9 days ahead, with `trip_span=plus1day`
- `plan_mode=weekend`: with `plan_date` set to a Saturday, scores Saturday and Sunday and keeps each place's better day
- `travel_min_h`, `travel_max_h`: Optional explicit travel bounds
- `view=bands`: Every travel band in one answer. Adds `band_view.stations` (every place that beats staying home: travel time, sun, net sun, gain, temperature, score, reasons) and full rows for the best few per 20 minutes of travel
- `limit`: Max results (1-20, default 5)

### Response
JSON with:
- `_meta`: request info, attribution, which weather feeds served the rows, data freshness
- `origin_conditions`: the origin's weather for the day
- `escapes[]`: ranked destinations with sun hours, gain over the origin, travel times, conditions, the day's max temperature and a short plan
- `band_view`: every qualifying place (with `view=bands`)
- `fog_outlook`: the Plateau fog top for today and the next four days (status fog / patchy / clear / overcast, height in m)
- `week_outlook`: per day for the next 7 days, the origin's sun and the best escape's sun

### MCP server (for AI assistants)

```
https://fomosun.com/api/mcp
```

Model Context Protocol, Streamable HTTP, no login, read-only. Add it as a custom connector (Claude: Settings, Connectors, Add custom connector). Tools:
- `find_sunny_escapes`: where there is more sun than at home, within a travel time (city or coordinates; today, tomorrow, weekend or a date; filter by kind of place and warmth), with sunny hours and train / car times
- `plan_trip`: one place on one day: sunny hours there, temperature, fog, train and car times, the next live trains and when to leave, what to do, the next days
- `best_day`: which day in the next week is worth a trip
- `home_sun`: how sunny a place is today (measured so far plus the forecast) or another day
- `fog_line`: the Plateau fog top for five days and the cities under it
- `get_destination`: details and a trip plan for one place

Every tool takes `language` ("de" for German verdicts and summaries). Ready-made prompts: `sunny_escape`, `escape_the_fog`, `sunny_weekend`, `best_day_this_week`. Limit: 120 tool calls a minute per IP. Setup for Claude, ChatGPT, Muse and other clients, with example questions: https://fomosun.com/connect

Other endpoints:

```
GET /api/v1/capabilities      service discovery (version, coverage, models)
GET /api/v1/openapi.json      OpenAPI 3.1 description of the public API
GET /api/v1/sbb-connections   live train connections (prefer from_ref / to_ref UIC refs)
GET /api/v1/disruptions       Swiss public transport disruptions (SIRI-SX)
```

Agent preference header supported on `sunny-escapes`:

```
X-FOMO-Agent-Preferences: {"travel_mode":"train","max_travel_h":3,"destination_types":["lake"],"avoid_types":["ski"],"temperature_preference":"warm"}
```

Preferences are used for that request only and never stored. No personal data is needed.

### Example questions an agent can answer with it
- "Where is it sunny near Zurich right now?"
- "Find me a sunny day trip from Basel within 2 hours by train."
- "Which day this weekend is better for getting above the fog from Bern?"
- "How high is the fog on the Swiss Plateau today?"
- "Where is it sunny near Bern this weekend?" (or read `/from/bern/weekend`)

## Coverage
- Switzerland and Liechtenstein (MeteoSwiss local forecasts)
- Germany, France, Italy and Austria near the border, plus a few rail anchors (Milan, Paris, Lyon)
- 17 origin cities in the app; any coordinates through the API

## Data Sources
- MeteoSwiss Open Government Data, local forecasts (hourly, ~5,600 points), for Swiss and Liechtenstein places and origins; the fog top is derived from them
- Open-Meteo (ICON-CH2, best match) for places abroad, calibrated each run onto the MeteoSwiss scale
- Open Journey Planner 2.0 (opentransportdata.swiss) for train connections, DB HAFAS for cross-border fallback, SIRI-SX for disruptions
- A precomputed train-time matrix for the catalog, with heuristics where no timetable answer exists

Please attribute forecasts to MeteoSwiss when quoting them.

## Contact
hello@fomosun.com