Search/discover Wikiloc trails by location, trail name, tags, and filters.
Supports batched search via `searches[]` (max 3; extra items are ignored).
# Core rules
- If the user asks for one trail, send exactly ONE item in `searches[]`, prioritize the best single match, and show it immediately with `wikiloc.show_trails` if found.
- If the user asks for multiple trails (with or without a specific count), send one search item per intended destination/variant, up to 3 total, then show all successful results with `wikiloc.show_trails`.
- Batch limit: process up to 3 searches/call. If more are needed, prioritize the best 3 and continue in later calls.
- Location searches MUST geocode first with `wikiloc.geocode`.
- For location intent, target likely outdoor destinations (not administrative areas like country/region/city), even if user names a region or nearby city.
- Large-area requests (country, large state/region, continent): choose geographically diverse outdoor destinations. Example for "beautiful hikes in Portugal": Peneda-Gerês (north), Serra da Estrela (central mountains), Algarve coast (south).
- Precise-location requests: one narrow search is fine.
# Search type selection (`searches[i]`)
Location-based discovery is default. Use `trailName` only for well-known canonical trails.
- `boundingbox`: broad area searches (parks, valleys, lakes, gorges, canyons; area-like targets).
- `startPoint`: trailhead / nearby / within-radius intent. Pick the smallest sensible radius: ~150 m for a specific POI/trailhead, city-scale for city-wide intent, driving-distance for "within X hours of [place]".
- `via`: must-visit destination points only (clear single-point POIs with specific lat/lon).
- `trailName`: canonical famous trail names only.
## Activity selection (`searches[i].activities`)
Priority:
1) Explicit user activity.
2) Else infer from current request.
3) If conflict: strong current cues > user history/preferences > weak current cues.
4) If still unclear: default to BOTH `hiking` + `walking`.
Cue strength:
- Strong = specific domain/terrain/season/accessibility cues (e.g., “MTB”, “enduro”, “winter trail”, “summit ascent”, “paved promenade”, “wheelchair/stroller”).
- Weak = generic/vague cues (e.g., “nice route”, “easy outing”, “good views”).
Inference rules:
- Named hiking routes => apply on-foot normalization.
- Named cycling routes => apply cycling normalization.
- Peaks/summits => `hiking` unless technical activity is explicitly requested.
- Infer non-foot activities only when clearly implied (e.g., winter trail => `snowshoe`; explicit water-route intent => matching water activity).
- Do not infer niche/technical activities without clear cues.
On-foot normalization:
- Generic “hike/walk” => BOTH `hiking` + `walking`, unless user excludes one.
- Urban/accessibility cues (promenade, flat, paved, stroller, wheelchair/reduced mobility) => `walking` ONLY.
- Clear trail terrain (mountain, ridge, canyon, wilderness, alpine, national/state park) => `hiking` ONLY, even if user says “walking”.
Easy/beginner/family-friendly:
- Treat family-friendly / kid-friendly / `apto para niños` as ease intent across activities.
- Prefer structured filters (`fitnessLevel`, distance/elevation) over changing activity.
- Add direct family tags plus requested supportive tags in `chatLang`.
- Add `walking` only for accessibility/urban/flat intent; keep `hiking` for hiking terrain.
Cycling normalization:
- Vague cycling => `road-bike`, `gravel-bike`, `bicycle-touring`.
- MTB cues => `mountain-bike`.
- Downhill/enduro/bike-park cues => `downhill-mtb`.
- Bikepacking cues => `bikepacking`.
- Touring cues => `bicycle-touring`.
- Add `ebike` ONLY if explicitly requested.
## `via` decision rules
- Use `via` only for destination-intent phrasing:
- EN: “go to”, “reach”, “ascend”, “pass by”, “must include”, “go through”, “stop at”
- CA: “anar a”, “arribar a”, “pujar a”, “passar per”, “que passi per”
- ES: “ir a”, “llegar a”, “subir a”, “pasar por”, “que pase por”
- If destination is area-like (lakes, parks, valleys, regions, cities), do NOT use `via`; use `boundingbox`.
- Use multiple `via` points only when user explicitly requests multiple must-pass POIs.
`via` examples:
- ✅ Use `via`: “rutes per anar al mirador de Figuerassa”; “ruta que passi pel mirador de la Figuerassa”; “hike to Mont Blanc summit”.
- ❌ Do not use `via`: “rutas cerca de Benasque”; “trails around Lago di Braies”; “best hikes in the Dolomites” (use `startPoint` or `boundingbox`).
# Tags (`searches[i].tags`)
- Include relevant tags in every search to improve quality and reinforce intent.
- Tags are keyword-like descriptors of desired features/experience (natural features, landmarks, experience qualities).
- Tags MUST match conversation language (`chatLang`); do not translate to English unless `chatLang` is `en`.
- Max 10 tags.
- Do not use generic activity/difficulty words as tags (use `activities` / `fitnessLevel` instead).
- Avoid negative keywords.
Examples (English only as examples; for other `chatLang`, use equivalent terms):
- ✅ Good: ["waterfall", "cascades", "viewpoint"]; ["coastal cliffs", "lighthouse", "cove"]; ["lake views", "alpine lake", "glacier"]; ["wildflowers", "meadow", "spring"]; ["sunset", "ridge", "panoramic views"]; ["forest", "river", "bridge"]; ["historic ruins", "castle", "monastery"]; ["family-friendly", "shade", "picnic spot"] (only if requested); ["Lago di Como"]; ["Gorges du Verdon"]; ["Sentiero degli Dei"] (as tag when request is descriptive, not clean canonical `trailName`).
- ❌ Bad: ["hike", "trail", "route"]; ["easy", "hard"] (use `fitnessLevel` / distance / elevation filters); ["Italy", "Spain"] (usually too broad; anchor with `boundingbox`, `startPoint`, or `via`); ["no crowds", "not busy", "avoid people"] (negative keywords); ["near me"] (belongs in location anchors, not tags).
# Named trail search
- Use `trailName` only for canonical well-known trail names.
- ✅ Good: "Camino de Santiago", "GR-20", "Appalachian Trail".
- ❌ Bad: "Barcelona", "hikes with great views near Dolomites", "trails with lake views".
# Filters (`searches[i]`)
- Common filters: `tags`, `fitnessLevel`, `trailType`, `activities`, `distanceMaxKm`, `elevationGainMaxMeters`, `season`, `excludedTrailIds`.
- Less-common filters: `distanceMinKm`, `elevationGainMinMeters`, `recordedDateFrom`, `recordedDateTo`.
- Put filter fields directly in each search item (do NOT nest under a `filters` object).
- Use `excludedTrailIds` to force alternatives to previously found trails; changing other params alone does not guarantee different results.
wikiloc.search_trails
View in the ChatGPT registry
