Thrussell Outings

Family activity picker for outings within ~1 hour 45 minutes of Catton (YO7 4SQ).

Kids browse big picture cards (fun bits, terrain, drive time). Grown-ups open the same outing on a phone for Google Maps, Tesla postcode/coords, parking, cost, weather, and a link back to the original source.

Agent / Hermes access

Prefer JSON over the HTML UI. Discovery:

URL	Purpose
/llms.txt	Agent instructions
/api	Live catalogue + endpoint docs
/api/openapi.json	OpenAPI 3.1
/api/suggest?q=...	Natural-language ask / suggest
/api/activities	Structured list + filters
/api/activities/[id]	Detail + maps + Tesla + weather

Typical Hermes flow — one call:

curl -sS 'http://localhost:3000/api/suggest?q=stepping%20stones%20under%2045%20minutes&limit=5'

Response includes ranked suggestions[] with why, logistics fields, Maps links, and Tesla destination. Use /api/activities/{id} only when you need live weather or a refined what3words pin.

Structured filters on /api/activities: q, feature, features, source, sources, terrain, terrains, maxDrive, minDrive, maxDistanceMiles, free, ids, sort, limit, offset, view=card|full.

Sources (polled, stored locally)

• The Reluctant Explorers — Google My Maps KML + walk page enrichment
• Yorkshire Tots to Teens — family walk posts from Yorkshire walks hubs
• Teesside Family Life — North Yorkshire outdoor guides via WordPress API
• Muddy Boots Mummy — Yorkshire family walks roundup
• Little Vikings — York & Yorkshire family walks guide
• AllTrails — North Yorkshire child-friendly trails
• Walkiees — community dog walks (Yorkshire / Cleveland / Durham)
• The Outdoor Guide — Yorkshire & Durham walk database
• DogFriendly.co.uk — dog-friendly days out near home
• Where2walk — Yorkshire Dales / North York Moors / Wolds walks
• National Trust / English Heritage — places near home
• OpenStreetMap — zoos, attractions, museums, nature reserves near home (fills gaps walk blogs miss, e.g. Thirsk Birds of Prey Centre)

Cross-source (and within-source) duplicates are clustered by start coordinates (~450m) plus shared name tokens, then merged into one card per place. National Trust / OSM / English Heritage win the place identity and pin; the richest walk write-up keeps the route notes. Every origin stays on sources[] with its original URL. Sibling photos are reused before the image pipeline scrapes og:image / Wikidata.

Results are filtered by real OSRM drive time from the live geocode of YO7 4SQ (via postcodes.io). Activity cache: data/activities.json. Cloudflare-prone pages also keep a last-good HTML snapshot under data/source-cache/ (npm run sync:refresh-cache).

Photos are looked up from source pages / Wikipedia / Wikimedia when missing, then resized with sharp into local webp files under public/media/ (card ~720px + detail ~1200px) so the browse grid stays fast.

When data refreshes

1. Daily cron — Vercel hits GET /api/sync at 06:00 UTC (vercel.json)
2. Manual — npm run sync locally, or GET|POST /api/sync
3. The UI footer shows the last successful syncedAt timestamp

Sync re-polls every source, re-geocodes as needed (with data/geocode-cache.json), re-filters by drive time, refreshes image cache, and rewrites data/activities.json.

Develop

npm install
npm run sync          # poll sources → data/activities.json + public/media
npm run dev

Open http://localhost:3000.

Other endpoints

• GET|POST /api/sync — refresh from sources (also on a daily Vercel cron)
• GET /api/weather?activityId= or lat/lng — weather only
• npm run merge:places — re-cluster the stored catalogue and backfill missing photos

Directions

Destination pins use source coordinates. When a Reluctant Explorers walk includes a what3words parking address, we resolve it with the same public-page approach as what3words-convert for a more precise Maps pin. Tesla gets the postcode when known, otherwise lat/lng.

Verify

npm run build && npm run start
npm run verify