SceniqDevelopers

list_routes

Routes (hikes, approaches) with their spot and facility links.

GET/v1/guides/{productId}/routes
MCP tool list_routesScope: readStableSince 2026-09-17
Markdown

Every route with stats, transit notes, equipment, sources and the ordered spot and facility links.

curl "https://sceniq.earth/api/v1/guides/j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2/routes" \
  -H "Authorization: Bearer $SCENIQ_API_KEY"

Path parameters

Returns

200 OK with this object.

  • productIdstring · guide idrequired

    The guide's id.

  • routesarray of Routerequired

    Every route, by name.

    Show 36 fieldsof Route
    • routeIdstring · route idrequired

      The route's id.

    • namestring or nullrequired

      The route's name.

    • activitystring or nullrequired

      hike, walk, bike, drive, ski or paddle; null means hike.

    • sacGradestring or nullrequired

      The grade as written in gradeScale.

    • gradeScalestring or nullrequired

      sac, via_ferrata, cai, yds, mtb, whitewater or other; null means sac.

    • effortLabelstring or nullrequired

      Easy, Moderate, Hard (free text).

    • durationMinnumber or nullrequired

      Duration in minutes (see durationBasis).

    • gainMnumber or nullrequired

      Elevation gain in meters.

    • descentMnumber or nullrequired

      Descent in meters.

    • distanceKmnumber or nullrequired

      Distance in kilometers.

    • startstring or nullrequired

      The trailhead in words.

    • startMapsUrlstring or nullrequired

      Map link to the trailhead.

    • transitarray of TransitNoterequired

      Transit notes per mode.

      Show 2 fieldsof TransitNote
      • modestringrequired

        train, bus, cable_car, car, boat, ferry or plane (shown as Flight).

        trainbuscable_carcarboatferryplane
      • notestringrequired

        The note in words: the connection, where to change, the last departure.

    • descriptionstring or nullrequired

      The route in the creator's words.

    • equipmentarray of strings or nullrequired

      Gear; [] means explicitly none, null means unknown.

    • sourcesarray of stringsrequired

      Where the facts come from.

    • extraPropsarray of ExtraProprequired

      Free label and value rows.

      Show 2 fieldsof ExtraProp
      • labelstringrequired

        The row's label, at most 60 characters.

      • valuestringrequired

        The row's value, at most 500 characters.

    • trackRouteTrack or nullrequired

      The route line.

      Show 3 fieldsof RouteTrack
      • coordinatesarray of array of numbersrequired

        Positions as [lon, lat] or [lon, lat, ele] (ele in meters), 2 to 1,000. Stored rounded to 6 decimals and whole meters.

      • sourcestringoptional

        The file type the line came from: gpx or kml. Other values are dropped.

      • fileNamestringoptional

        The imported file's name, cut to 200 characters.

    • statusStatusNotice or nullrequired

      A closure notice.

      Show 6 fieldsof StatusNotice
      • statestringrequired

        open, partly_closed, closed or reopening. reopening with until means it reopens on that day.

        openpartly_closedclosedreopening
      • notestringoptional

        What is closed or changed, in the creator's words, at most 500 characters.

      • sincestringoptional

        The day the state began (YYYY-MM-DD).

      • untilstringoptional

        The day the state is expected to end (YYYY-MM-DD). Must not be before since.

      • sourceUrlstringoptional

        The page that announced it (http or https).

      • checkedOnstringoptional

        The day the value was last checked against its source (YYYY-MM-DD).

    • seasonRouteSeason or nullrequired

      When the route can be walked.

      Show 3 fieldsof RouteSeason
      • monthsarray of numbersoptional

        The months it can be walked (1 to 12). Absent means all year.

      • closureNotestringoptional

        What closes and when, at most 500 characters (stairs chained November to April).

      • statusUrlstringoptional

        The page with the current conditions (http or https), linked from the season notice.

    • variantsarray of RouteVariantrequired

      Alternatives.

      Show 5 fieldsof RouteVariant
      • namestringrequired

        The variant's name, at most 80 characters. Required.

      • startstringoptional

        Where it starts when that differs, at most 200 characters.

      • extraKmnumberoptional

        Kilometers it adds, negative when shorter (-1,000 to 1,000).

      • extraMinnumberoptional

        Minutes it adds, negative when faster (-10,000 to 10,000).

      • purposestringoptional

        Why take it, at most 300 characters.

    • stagesarray of RouteStagerequired

      Days or legs of a trek.

      Show 5 fieldsof RouteStage
      • namestringrequired

        The stage's name, at most 120 characters (Day 1: Refugio Grey to Paine Grande). Required.

      • kmnumberoptional

        Distance in kilometers (0 to 1,000).

      • minnumberoptional

        Duration in minutes (0 to 10,000).

      • gainMnumberoptional

        Elevation gain in meters (0 to 10,000).

      • notestringoptional

        One line for the stage, at most 300 characters.

    • segmentsarray of RouteSegmentrequired

      Sections with their own access.

      Show 3 fieldsof RouteSegment
      • namestringrequired

        The section's name, at most 120 characters. Required.

      • kmnumberoptional

        Its length in kilometers (0 to 1,000).

      • accessNotestringoptional

        What access it needs, at most 300 characters (permit by lottery).

    • shapestring or nullrequired

      loop, out_and_back or one_way.

      loopout_and_backone_way
    • durationBasisstring or nullrequired

      What durationMin counts: round_trip, one_way or ascent.

      round_tripone_wayascent
    • ascentMinnumber or nullrequired

      Minutes up.

    • descentMinnumber or nullrequired

      Minutes down.

    • sourceGradestring or nullrequired

      The source's own grade.

    • figureSourcesarray of FigureSourcerequired

      Where each number comes from.

      Show 4 fieldsof FigureSource
      • fieldstringrequired

        The number it backs: durationMin, distanceKm, gainM, descentM or sacGrade.

        durationMindistanceKmgainMdescentMsacGrade
      • kindstringrequired

        sourced (taken from a source) or computed (worked out, for example from the GPX track).

        sourcedcomputed
      • urlstringoptional

        The source page (http or https).

      • notestringoptional

        How the number was found or worked out, at most 300 characters.

    • reviewNotesstring or nullrequired

      Notes for the creator's review, never shown to buyers.

    • factsCheckedOnstring or nullrequired

      The day the facts were last checked (YYYY-MM-DD).

    • reviewBystring or nullrequired

      The day the facts need a new check (YYYY-MM-DD).

    • createdAtnumberrequired

      When the row was created (Unix time in milliseconds).

    • updatedAtnumberrequired

      When the row last changed (Unix time in milliseconds).

    • spotsarray of objectsrequired

      The spots the route passes, in order.

      Show 4 fields
      • spotKeystringrequired

        The spot's key.

      • ordernumberrequired

        Position on the route.

      • quickestbooleanrequired

        true when this is the fastest approach to the spot.

      • rolestringrequired

        required: the way in. optional: a walk from the spot that never sets its Accessibility.

        requiredoptional
    • facilitiesarray of objectsrequired

      The places the route uses, in order.

      Show 2 fields
      • facilityIdstring · place idrequired

        The place's id.

      • ordernumberrequired

        Position on the route.

Response 200
{
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "routes": [
    {
      "routeId": "kx7f2h8j4k0k6z2x8c4v0b6n2m8q4w0e",
      "name": "Fairy Falls trail to the Grand Prismatic overlook",
      "activity": "hike",
      "sacGrade": "Class 1",
      "gradeScale": "yds",
      "effortLabel": "Easy",
      "durationMin": 45,
      "gainM": 35,
      "descentM": 35,
      "distanceKm": 2,
      "start": "Fairy Falls trailhead on the Grand Loop Road, 1.6 km south of Midway Geyser Basin",
      "startMapsUrl": "https://maps.apple.com/?ll=44.5156,-110.8326&q=Fairy%20Falls%20Trailhead",
      "transit": [
        {
          "mode": "car",
          "note": "Park at the Fairy Falls trailhead lot, which fills by 09:30 in July and August. No public transport runs in the park."
        },
        {
          "mode": "plane",
          "note": "Yellowstone Airport (WYS) in West Yellowstone, 45 km by road, has flights from June to September."
        }
      ],
      "description": "A flat kilometer on the old Fountain Freight Road, then a short climb to a platform above Grand Prismatic Spring. Go mid morning on a warm day, once the steam has lifted.",
      "equipment": [
        "Bear spray",
        "A warm layer for the morning"
      ],
      "sources": [
        "https://www.nps.gov/places/000/grand-prismatic-spring.htm",
        "GPX recorded by Mara Lindgren on 2026-09-14"
      ],
      "extraProps": [
        {
          "label": "Dogs",
          "value": "Not allowed on park trails"
        }
      ],
      "track": {
        "coordinates": [
          [
            -110.8326,
            44.5156,
            2181
          ],
          [
            -110.8349,
            44.517,
            2182
          ],
          [
            -110.8372,
            44.5183,
            2183
          ],
          [
            -110.8391,
            44.519,
            2186
          ],
          [
            -110.8402,
            44.5196,
            2201
          ],
          [
            -110.8406,
            44.5199,
            2214
          ]
        ],
        "source": "gpx",
        "fileName": "fairy-falls-overlook-2026-09-14.gpx"
      },
      "status": null,
      "season": {
        "months": [
          4,
          5,
          6,
          7,
          8,
          9,
          10
        ],
        "closureNote": "Park roads close to cars from early November to mid April; the trailhead is then reached by snowcoach only.",
        "statusUrl": "https://www.nps.gov/yell/planyourvisit/conditions.htm"
      },
      "variants": [
        {
          "name": "On to Fairy Falls",
          "extraKm": 6.8,
          "extraMin": 120,
          "purpose": "A 60 m waterfall 3.4 km further along the same trail, quiet before 09:00."
        }
      ],
      "stages": [],
      "segments": [
        {
          "name": "Fountain Freight Road",
          "km": 1.1,
          "accessNote": "Flat gravel road over the Firehole River, closed to cars. Bikes allowed."
        },
        {
          "name": "Overlook spur",
          "km": 0.3,
          "accessNote": "Hikers only. The one climb of the route."
        }
      ],
      "shape": "out_and_back",
      "durationBasis": "round_trip",
      "ascentMin": null,
      "descentMin": null,
      "sourceGrade": "Easy",
      "figureSources": [
        {
          "field": "distanceKm",
          "kind": "sourced",
          "url": "https://www.nps.gov/places/000/grand-prismatic-spring.htm"
        },
        {
          "field": "gainM",
          "kind": "computed",
          "note": "From the GPX, smoothed"
        },
        {
          "field": "durationMin",
          "kind": "computed",
          "note": "Walking time without the stop on the platform"
        }
      ],
      "reviewNotes": "The NPS page gives no elevation gain; the figure comes from the GPX.",
      "factsCheckedOn": "2026-09-20",
      "reviewBy": "2027-04-01",
      "createdAt": 1789895640000,
      "updatedAt": 1790586840000,
      "spots": [
        {
          "spotKey": "01M2Z1G0Y0QG7M2V6N9R3T5W8Y",
          "order": 1024,
          "quickest": false,
          "role": "required"
        }
      ],
      "facilities": [
        {
          "facilityId": "km7d4f6g8h0j2k4k6z8x0c2v4b6n8m0q",
          "order": 1024
        }
      ]
    },
    {
      "routeId": "kx7r4t6y8v0j2p4p6a8s0d2f4g6h8j0k",
      "name": "Inspiration Point from Tunnel View",
      "activity": "hike",
      "sacGrade": "Class 1",
      "gradeScale": "yds",
      "effortLabel": "Moderate",
      "durationMin": 120,
      "gainM": 305,
      "descentM": 305,
      "distanceKm": 4.2,
      "start": "Pohono Trail sign at the Tunnel View parking",
      "startMapsUrl": "https://www.google.com/maps/search/?api=1&query=37.7156,-119.677",
      "transit": [],
      "description": "Steep switchbacks up the Pohono Trail to a quieter, higher version of the Tunnel View frame. Most of the climb is in full sun.",
      "equipment": [
        "Two liters of water per person"
      ],
      "sources": [
        "GPX recorded by Mara Lindgren on 2026-06-11"
      ],
      "extraProps": [],
      "track": null,
      "status": null,
      "season": null,
      "variants": [],
      "stages": [],
      "segments": [],
      "shape": "out_and_back",
      "durationBasis": "round_trip",
      "ascentMin": null,
      "descentMin": null,
      "sourceGrade": null,
      "figureSources": [],
      "reviewNotes": null,
      "factsCheckedOn": null,
      "reviewBy": null,
      "createdAt": 1789895640000,
      "updatedAt": 1790586840000,
      "spots": [
        {
          "spotKey": "01M2Z1G0Y0R2K5P8S1V4X7Z0C3",
          "order": 1024,
          "quickest": false,
          "role": "optional"
        }
      ],
      "facilities": []
    }
  ]
}

Errors

Every error is { error: { code, message } }. Act on the code.

  • 400invalid_argumentA required field is missing, a field is unknown, or a value does not match its type (the Convex validator's path and value are in the message).
  • 401unauthenticatedThe request carries no key. Send it as Authorization: Bearer sk_sceniq_... (or X-Api-Key).
  • 401invalid_api_keyThe key is unknown, revoked or expired.
  • 403forbiddenThe key belongs to a creator account that is no longer active.
  • 404not_foundThe id does not exist or belongs to another creator. The two answers are identical on purpose, so ids never reveal what exists.
  • 429rate_limitedOver a limit: requests per key per minute, per creator per hour, uploads per key per minute, or check_links per guide per hour.
  • 500internal_errorAn unexpected failure. The message is hidden on purpose.