AllTrails Trail Search

Purpose

Given a location (URL, intent string, place name, bounding box, lat/lng+radius, or trail slug/ID) and any combination of the AllTrails filter panel dimensions (activity, difficulty, length, elevation gain, route type, dog/kid/wheelchair/stroller suitability, traffic, attributes, season, rating, sort), return matching trails as structured JSON — name, location, coordinates, length, elevation, difficulty, route type, average rating + review count, primary + thumbnail photo URLs, description, trail attributes, dog policy, kid policy, canonical AllTrails URL, plus region-wide totals ("16,544 trails in California"). Read-only — never saves a trail, follows a list, logs a completion, or posts a review.

When to Use

• "Easy hikes near Yosemite" / "dog-friendly trails in Marin" / "best waterfalls in Olympic National Park."
• Bulk catalog extraction for a state, park, region, or geographic bounding box.
• Single-trail metadata lookup by slug or AllTrails trail ID.
• Anywhere you'd otherwise scrape AllTrails HTML — the public Algolia search index that powers the AllTrails site is faster, cheaper, and structurally more reliable than the DataDome-protected web UI.

Workflow

The AllTrails web UI is a Next.js front-end over a public Algolia search index (alltrails_primary_en-US) and a small REST API at /api/alltrails/v2/*. The search index is the same one the site itself queries — credentials are bootstrapped into every page's hydration JSON. Lead with the Algolia path; only fall back to a stealth Browserbase browser session when you need the trail-detail page (description, recent conditions, GPX, full photo carousel), since those endpoints are DataDome-protected and the Algolia hit already contains ~80% of the fields the skill needs.

Credentials (public, hardcoded in the bundled site JS)

All three are public client-side keys (apiKey rather than adminApiKey). They are visible in unauthenticated page source today; re-extract from a fresh homepage fetch if a request starts 401-ing.

1. Resolve the input to a geo target

2. Build the Algolia search request

GET https://9IOACG5NHE-dsn.algolia.net/1/indexes/alltrails_primary_en-US
    ?x-algolia-application-id=9IOACG5NHE
    &x-algolia-api-key=a557051fc69f8a3e456db3084df4780e
    &query=<free-text or empty>
    &hitsPerPage=<1-100>
    &page=<0-based>
    &filters=<filter expression — see below>
    &numericFilters=<numeric range — see below>
    &aroundLatLng=<lat>,<lng>          (when scoping by point + radius)
    &aroundRadius=<meters | "all">     (default: 1500000m without "all")
    &insideBoundingBox=<bl_lat>,<bl_lng>,<tr_lat>,<tr_lng>   (when scoping by bbox)
    &attributesToRetrieve=<comma-list>  (slim down response — see "1MB cap" gotcha)

/1/indexes/{name} accepts the search params as GET query string (the /query sub-path is POST-only). Auth via URL params works — no headers, no auth cookie. Use --proxies with browse cloud fetch if your egress is from a sandbox/datacenter IP; Algolia itself doesn't bot-detect but a clean residential IP avoids any future tightening.

Filter expression mapping

Combine clauses with AND / OR and group with parens, URL-encoded. Example:

type:trail
AND state_id=5
AND (features:dogs OR features:dogs-leash)
AND features:kids
AND difficulty:easy

Sort

alltrails_primary_en-US has a single replica (_replica) with identical customRanking: [desc(popularity)] — meaning Algolia ranking is the same on both indexes and AllTrails handles sort variants through the query shape, not a separate sort-index per option:

(See gotcha: there is no dedicated _avg_rating_desc or _num_reviews_desc replica index. Don't search for one — both _alpha and _local are internal staging mirrors, not sort variants.)

Pagination

page=0 is the first page, hitsPerPage accepts 1-100 (defaults to 20). Returned nbHits is the true total even when capped; nbPages reflects what's paginable (Algolia caps page × hitsPerPage ≤ 1000 by default — beyond that you need bounding-box subdivision to reach trail 1001+).

3. Decode each hit

Algolia returns each trail as a flat JSON object. Map fields like this:

4. Build photo URLs

Each trail hit carries profile_photo_data formatted as {photo_id}-{photo_hash} plus featured_photo_ids[] for additional carousel photos. Get a redirect to the actual image via:

GET https://www.alltrails.com/api/alltrails/v2/trails/{trail_id}/photos/{index}
    ?key=3p0t5s6b5g4g0e8k3c1j3w7y5c3m4t8i
    &size=<sm|md|lg|xl|extra_large>

Response is a 302 to https://images.alltrails.com/<base64> where the base64 decodes to an imgix-style edits descriptor pointing at assets.alltrails.com/uploads/photo/image/{id}/{hash}.jpg. Only extra_large actually applies a resize (max 2048×2048 inside fit) — other sizes return the original. For the prompt's output shape:

• primary_photo_url → ?index=0&size=extra_large redirect target.
• thumbnail_url → ?index=0&size=md.
• Additional photo_urls[] → ?index=1...num_photos-1 (typically up to featured_photo_ids.length).

You can also skip the redirect hop and build the imgix URL yourself when bandwidth matters (the JSON edits payload is deterministic; the bucket is always assets.alltrails.com and the key is uploads/photo/image/{photo_id}/{photo_hash}.jpg).

5. Optional: region-wide totals

When the prompt mentions a state, country, or area scope, run a hitsPerPage=0 count-only query alongside the main search to populate the "X trails in California" headline number:

GET .../alltrails_primary_en-US?query=&hitsPerPage=0&filters=type:trail AND state_id=5&x-algolia-application-id=…&x-algolia-api-key=…
→ {"hits":[], "nbHits":16544, "nbPages":0, "page":0, ...}

nbHits is the answer (validated 2026-05-18: California = 16,544; Yosemite NP via associated_area_ids:10106838 = 32 easy + 130 surface-level matches).

6. Read-only enforcement

The Algolia search index is intrinsically read-only — there's no POST /book, POST /save, or POST /complete to call by accident. The /api/alltrails/v2/trails/{id}/photos/{idx} endpoint is GET-only. You cannot accidentally save a trail, follow a list, log a completion, or post a review through this surface. When falling back to the browser path (next section), do not click Save / Add-to-list / Mark-completed / Submit-review buttons.

Browser fallback (when the prompt asks for description, recent conditions, GPX, or full reviews)

The trail-detail page, the user-reviews list, the recent-conditions feed, and the GPX download are gated by DataDome on www.alltrails.com. The fetch API path returns 403 with X-Datadome: protected for every /trail/*, /explore*, /parks/*, /us/*, and /api/alltrails/v2/trails/{id} (non-photo) endpoint — confirmed 2026-05-18 across 8 paths. To reach those, you need a Browserbase stealth + residential proxy session that lets DataDome complete its JS challenge:

SID=$(browse cloud sessions create --keep-alive --verified --proxies | jq -r .id)
browse open "https://www.alltrails.com/trail/us/california/grant-lakes" --remote -s "$SID"
browse wait load --remote -s "$SID"
browse wait timeout 4000 --remote -s "$SID"   # DataDome JS challenge resolves async
browse get markdown body --remote -s "$SID"

The first navigation after a new session typically lands on a DataDome interstitial; the JS challenge solves within 2-4 s on a stealth+proxy session, after which subsequent same-session fetches return 200 (the datadome=<…> cookie persists for ~6 hours). Once on the trail-detail page, extract:

• Description — <section data-testid="trail-description"> text, cleaned of HTML.
• Recent conditions — <section data-testid="recent-conditions">; each row has a date, condition tags (Rocky, Muddy, Snowy, Icy, Overgrown, Fallen tree), and a reviewer handle. This is where rocky and muddy live — they are surfaced as condition tags on reviews, not as Algolia features: facets.
• Parking notes — <div data-testid="trail-parking">.
• GPX download — auth-gated (AllTrails Pro required). When the session is unauthed, the button is greyed; surface gpx_url: null, gpx_requires_auth: true, gpx_unlock: "alltrails-pro". When authed (Cookie containing a _at_session_id_v2 + Pro entitlement), the link is /trail/{slug}/gpx?key={web_api_key}.
• Pro heatmap — same: auth-gated; surface a heatmap_available flag.

Avoid browse snapshot on the explore/search-results pages — they're virtualized lists with 0 stable a11y refs; iterate via the Algolia path for the listings themselves and use the browser only for per-trail enrichment.

Site-Specific Gotchas

• DataDome, not Cloudflare. The prompt description ("Cloudflare + custom") is out of date — AllTrails moved to DataDome (X-Datadome: protected, datadome.alltrails.com script tag, X-Dd-B: 3 header). The mitigation is the same shape — stealth + residential proxy + a few seconds for the JS challenge — but the cookie name (datadome=…) and the captcha host (geo.captcha-delivery.com) differ from Cloudflare's cf_clearance, so don't reuse Cloudflare-specific tooling/fixtures.
• Homepage / is the only AllTrails web path that returns 200 without solving DataDome. Every other URL — /explore, /trail/*, /parks/*, /us/{state}, /api/alltrails/v2/trails/{id} (non-photo) — is 403 on a cold session. The homepage is your "extract bootstrapped credentials, then leave" target if the in-bundle Algolia/web keys need re-discovery.
• Lengths are meters; elevation_gain is meters; elevation_meters is something else. length and elevation_gain are stored in meters regardless of the units: "i" flag on each hit (the units flag is a display preference for the user, not a data unit). elevation_meters is the trailhead's absolute elevation above sea level, not the gain — don't confuse them. Convert length / 1609.344 for miles, elevation_gain / 0.3048 for feet.
• route_type is one letter, not a word. L / O / P → Loop / Out & Back / Point to Point. The filter facet uses the letter too (route_type:L).
• difficulty has FOUR values, not three. The AllTrails filter panel shows three (Easy/Moderate/Hard), but the index also contains strenuous. Treat strenuous as a stricter superset of hard when mapping back to the panel's three-button UI.
• visitor_usage has FOUR levels, not three. Panel shows Light / Moderate / Heavy (1/2/3) but the data has a fourth bucket (4) that's not exposed in the filter UI but appears in ~94% of popular-trail hits in our 1,000-trail sample. Treat 4 as "Extreme / very crowded" and either fold into Heavy or surface as a separate enum if your output schema allows.
• Algolia 1MB response cap via browse cloud fetch. The Browserbase Fetch API rejects responses > 1MB. With default attributes, ~250 hits per response is the practical ceiling. For larger pulls, use attributesToRetrieve=[…] to slim each hit to the fields your output needs (a 1,000-hit slim response with 6 attrs comes in at ~825 KB — verified 2026-05-18).
• page × hitsPerPage caps at 1,000. Algolia returns trail-1 through trail-1000 across pages; trail-1001+ silently disappear even though nbHits is the true total. To exhaustively enumerate a state, subdivide by insideBoundingBox quadrants (lat halves × lng halves recurse until each cell's nbHits ≤ 1000).
• State / country are state_id / country_id, not name strings. state_name is in searchableAttributes (text-search index) but NOT in attributesForFaceting, so filters=state_name:"California" returns 0. Always resolve a state-name input to state_id first via a type:area query, then filter on the numeric ID. (Observed: California = 5, country US = 313.)
• area_id vs associated_area_ids. A trail's "home" park is area_id; associated_area_ids[] includes overlapping designations (e.g. a trail inside Yosemite NP that also touches Stanislaus National Forest will list both). Always use associated_area_ids:<id> for park-scoped filters — area_id:<id> will miss legitimate hits.
• Trail features are kebab-case with non-obvious quirks. Canonical enum values (observed in a 1k-trail sample 2026-05-18):
  • Natural: views, wildlife, wild-flowers (not wildflowers), forest, river, waterfall, lake, beach, cave, hot-springs, historic-site
  • Dog policy: dogs (off-leash welcome), dogs-leash (not dogs-leashed), dogs-no (explicit "no dogs")
  • Suitability: kids (not kid-friendly), strollers, ada (the indexed value for wheelchair-accessible — NOT wheelchair)
  • Surface: paved, partially-paved
  • Special trail types: city-walk, rails-trails, pub-crawl
  • Missing from facets: rocky, muddy, snowy, icy, overgrown, fallen-tree — these are review-time condition tags (live on the trail detail page's Recent Conditions panel), not index facets. The AllTrails filter panel calls them "Trail conditions" and that filter is implemented client-side from the most-recent reviews, not from a server facet.
• Activities enum (kebab-case): hiking, walking, running (general), trail-running, mountain-biking, road-biking, bike-touring, backpacking, camping, birding (not bird-watching), fishing, horseback-riding, rock-climbing, snowshoeing, skiing, cross-country-skiing, paddle-sports, scenic-driving, off-road-driving, via-ferrata.
• Sort is mostly client-side after the fetch. Algolia ranking on alltrails_primary_en-US is [typo, geo, words, filters, proximity, attribute, exact, custom] with customRanking: [desc(popularity)]. There is no *_avg_rating_desc or *_num_reviews_desc replica — the only replica is alltrails_primary_en-US_replica with the same ranking. For "Highest rated" / "Most reviewed" sort, fetch the top-N by popularity (or by aroundLatLng for distance) then sort the returned hits client-side. Don't waste a request hunting for a non-existent sort replica.
• type:trail filter is mandatory. Without it, your search results will be polluted with type:area, type:city, type:park, type:poi, and type:user hits. Always include type:trail for trail-listing tasks; use type:area only when resolving a place-name input to an ID.
• profile_photo_data looks like a single string but is {photo_id}-{photo_hash}. The hyphen is the field separator. profile_photo_data: "50889290-02bd9fbfaf51cdd737bb00f0198e0fe4" → photo_id = 50889290, photo_hash = 02bd9fbfaf51cdd737bb00f0198e0fe4. featured_photo_ids[] is a parallel array of additional photo IDs for the carousel.
• /api/alltrails/v2/trails/{id}/photos/{idx} is the one DataDome-allowlisted AllTrails-owned endpoint — it 302s straight through (verified 2026-05-18). All other /api/alltrails/v2/* paths are 403'd by DataDome from the same cold session. Don't waste time probing other /api/alltrails/ paths from a non-stealth fetch; they require the same browser-session unblocking as the page routes.
• The _alpha and _local Algolia indexes are internal mirrors, not regional variants. alltrails_primary_en-US_alpha is a staging index with ~83% the row count of production; alltrails_primary_en-US_local has 1,902 entries (test fixtures). Always use `al