# Washington Larch Trails: agent guide

Page: https://duncancampbell.dev/larch-map/

An interactive map of the 298 named Washington trails that cross subalpine
larch range, on shaded terrain, with a live weather overlay. This file is for
agents and scripts. Everything on the page is also available as static data
or through a JavaScript API on the page.

## Static data (no JavaScript needed)

All files are JSON and can be fetched directly.

| URL | Contents |
| --- | --- |
| `/larch-map/data/trails.json` | All trails with attributes and links |
| `/larch-map/data/trails.geojson` | The same trails with geometry (WGS84 MultiLineString) |
| `/larch-map/data/places.json` | 389 peaks over about 6,900 ft, 172 passes and 36 towns, with elevations |

Each trail has these fields:

| Field | Meaning |
| --- | --- |
| `id` | Stable slug, for example `maple-pass-470` or `cutthroat-pass-483` |
| `name`, `trail_number` | Trail name and agency trail number (number may be null) |
| `length_mi` | Length of the whole trail, not only the part inside larch range |
| `high_point_ft`, `low_point_ft` | From a roughly 50 m elevation model, sampled every 40 m along the trail |
| `reaches_larch_band` | True when the high point is at least 5,900 ft. Subalpine larch usually grows from about 5,900 to 7,900 ft. |
| `areas`, `counties`, `trail_system` | Managing area (wilderness, park, forest), county, and trail system |
| `sample_point` | A point on the trail (`lat`, `lon`). It is not the trailhead. |
| `links` | Map deep link, WTA search, OpenTopoMap and CalTopo |

Sources:

- Trails and larch ranges: [LarchHikes](https://github.com/tarynblack/LarchHikes), which uses WA RCO trail data and USGS larch range data
- Elevations: AWS Terrain Tiles
- Place names: USGS GNIS

## Weather for a trail

The page uses [Open-Meteo](https://open-meteo.com/) (CC BY 4.0, no API key).
To get the same 4-day forecast at a trail's high point without the page, use
the trail's `sample_point` and `high_point_ft` (converted to metres):

```
https://api.open-meteo.com/v1/forecast?latitude={lat}&longitude={lon}&elevation={high_point_m}
  &daily=temperature_2m_max,temperature_2m_min,precipitation_sum,snowfall_sum,precipitation_probability_max,wind_gusts_10m_max
  &temperature_unit=fahrenheit&precipitation_unit=inch&wind_speed_unit=mph&timezone=America%2FLos_Angeles&forecast_days=4
```

The map's weather overlay comes from an hourly forecast on a 0.25° grid (11
by 8 points, from -122.0 to -119.5 longitude and 47.25 to 49.0 latitude).
Temperatures are adjusted to the terrain elevation at 6.5 °C per km.

## Deep links

The map reads its state from the URL fragment, and updates the fragment as the
view changes.

| Parameter | Effect |
| --- | --- |
| `trail` | Selects a trail by id, for example `#trail=maple-pass-470` |
| `wx` | Turns on a weather overlay: `temp`, `precip`, `snow`, `gust` or `cloud` |
| `frz=1` | Shades terrain above the forecast freezing level |
| `color` | Sets trail coloring: `plain`, `high` or `miles` |

For example, `https://duncancampbell.dev/larch-map/#trail=cutthroat-pass-483&wx=temp`
opens Cutthroat Pass with the temperature overlay.

## JavaScript API (`window.larchMap`)

For browser agents. Wait for `document.documentElement.dataset.larchMapReady === "true"`,
or for the `larchmap:ready` event. Calling `larchMap.help()` returns a summary
of the methods below.

Methods that take a trail `id` also accept the trail name or trail number.

```js
larchMap.listTrails({ query, area, minHighFt, maxHighFt, minMiles, maxMiles,
                      reachesLarchBand, sort: 'name' | 'high' | 'miles', limit })
larchMap.getTrail(id)                     // trail or null
larchMap.selectTrail(id, { zoom: true })  // highlights the trail and opens its details and forecast
await larchMap.getForecast(id)            // { days: [{ date, high_f, low_f, precipitation_in,
                                          //   precipitation_probability_pct, snowfall_in, wind_gusts_mph }] }
await larchMap.setWeather('temp' | 'precip' | 'snow' | 'gust' | 'cloud' | 'none',
                          { time: hourIndex | 'YYYY-MM-DDTHH:00' })  // time is Pacific
larchMap.setLayers({ hillshade, larchBand, subalpineRange, westernRange, trails, westernTrails,
                     peaks, passes, towns, water, roads, parks, aboveFreezingLevel })
larchMap.setTrailColor('plain' | 'high' | 'miles')
larchMap.flyTo(lon, lat, zoom)
larchMap.resetView()
larchMap.clearSelection()
larchMap.elevationAt(lon, lat)            // approximate ft from the page's ~350 m grid; use trail high points for trails
larchMap.places({ kind: 'peak' | 'pass' | 'town', limit })
larchMap.getState()                       // selected trail, layers, weather, view and URL
```

Errors are thrown with a message that says what valid input looks like.

## WebMCP tools

In browsers that support the experimental WebMCP API
(`navigator.modelContext`), the page registers these tools:

- `larch_list_trails`
- `larch_select_trail`
- `larch_get_forecast`
- `larch_set_weather`
- `larch_set_layers`
- `larch_get_state`

## Notes for planning

- Larches turn gold from late September to mid-October.
- `reaches_larch_band` is a filter based on elevation only. The larch range
  polygons are coarse, so check trip reports before relying on it.
- Some entries are connectors or long through-trails, such as the Pacific
  Crest Trail section at 152.6 mi. Sort or filter by `length_mi` to skip them.