Day outings near a point

# Without a key, leave out the Authorization line (500 credits a day per address).
curl --fail-with-body 'https://api.trailsplits.com/v1/outings' \
  -H "Authorization: Bearer $TRAILSPLITS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"lat":46.6863,"lon":7.8632,"radius_km":20,"max_hours":4,"max_grade":"T2","car_free":true}'

{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "outings/1"
      ]
    },
    "engine": {
      "type": "object"
    },
    "request": {
      "type": "object"
    },
    "settings_defaulted": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "ordered_by": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "outings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rank": {
            "type": "integer"
          },
          "id": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "curated",
              "generated"
            ]
          },
          "kind": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "url": {
            "type": "string",
            "nullable": true
          },
          "shape": {
            "type": "string",
            "enum": [
              "loop",
              "a_to_b"
            ]
          },
          "start": {
            "type": "object",
            "additionalProperties": true
          },
          "finish": {
            "type": "object",
            "additionalProperties": true
          },
          "length_m": {
            "type": "number"
          },
          "ascent_m": {
            "type": "number",
            "nullable": true,
            "description": "null when not known, never 0."
          },
          "moving_minutes": {
            "type": "number",
            "nullable": true
          },
          "time_basis": {
            "type": "string",
            "nullable": true
          },
          "hardest_grade": {
            "type": "string",
            "nullable": true
          },
          "window": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true
          },
          "notices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "code",
                "message"
              ],
              "additionalProperties": true
            }
          },
          "why": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "line": {
            "type": "string",
            "description": "Encoded polyline (precision 6), at most 160 points: send it as geometry to the route brief or route card."
          }
        },
        "required": [
          "rank",
          "id",
          "source",
          "shape",
          "length_m",
          "why",
          "line"
        ]
      }
    },
    "matched": {
      "type": "integer"
    },
    "left_out": {
      "type": "object",
      "description": "Per rule, how many outings it left out (farther, shape, longer, slower, time_unknown, more_climb, harder, grade_unknown, no_stop_at_start, water_gap, water_unknown)."
    },
    "generated": {
      "type": "object",
      "nullable": true
    },
    "index": {
      "type": "object"
    },
    "note": {
      "type": "string"
    },
    "unknowns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ]
      }
    }
  },
  "required": [
    "schema",
    "engine",
    "request",
    "outings",
    "matched",
    "left_out",
    "unknowns"
  ]
}

Day outings near a point, for a question like "where can I walk near Interlaken on Monday, at most four hours, T2 at most, from a bus stop?". It is made for agents first: one flat request, and an ordered list where each outing carries its facts and says why it is on the list.

Where the outings come from:

• Curated outings: TrailSplits' published trail pages and its reviewed Swiss day hikes (213 so far). Each has a page at trailsplits.com/trails/….
  • Their facts were read once with route analysis and places along the route, and are rebuilt with the weekly map.
  • The climb and the signpost time are the ones the page shows.
  • They cover Switzerland and its borders so far.
• Generated round trips: loops from your point, built as /v1/roundtrips builds them. They only fill the list when the curated outings do not, and are never built for shape: a_to_b. They work anywhere the routing map covers.
• Not yet: public community routes.

What it is, and what it is not.

• Facts, not a rating. A mapped path or stop is not a promise that it is open or safe. The time is moving time without breaks, and the forecast is model output. Closures, snow on the ground and fires are not assessed: ask the route brief for an outing's line.
• Unknown never passes as easy. Each rule you set leaves out the outings it cannot judge, and left_out counts them by reason:
  • max_grade leaves out a line whose paths are more than 30 % untagged, or that runs 10 % or more off mapped paths: these are the thresholds at which an outing says difficulty_untagged or off_mapped_paths. A line only on roads and tracks has nothing to grade, and passes. This holds even at T6, because an untagged path's grade is unknown, not easy;
  • water leaves out a line whose water was not assessed;
  • max_hours leaves out a line with no time.
• One route, one climb. A curated outing states its page's climb.
• Times.
  • A hike's time is the TrailSplits hike time model (trailsplits-hike/2) on the matched line, at your pace_factor.
  • Without the model's time, it is the DIN 33466 signpost rule (din33466).
  • A run's time is your min_per_km on the flat (your_pace_flat).
• With a date, each outing gets its go window for that day and start time: the route windows facts, read at the hour you reach each point.
  • One time per outing: the window is read at the pace that makes its finish the outing's moving_minutes.
  • A walk past midnight is measured against the dusk of the evening it starts.
• Stops are as mapped. A station, halt or lift within 300 m of an end is preferred to a bus stop, and a named stop to an unnamed one. Timetables, last departures and seasonal mountain railways and lifts are not checked (timetables_not_checked).

Request

A flat object: only lat and lon are required.

{ "lat": 46.6863, "lon": 7.8632, "radius_km": 20, "date": "2026-10-05", "max_hours": 4, "max_grade": "T2", "car_free": true }

Response

200, JSON, x-trailsplits-product: outings/1.

• no_thunder: points with a thunderstorm signal;
• dry: wet points first, then the highest chance of precipitation in bands of 20 %, so 19 % ranks before 24 %;
• daylight: any minute in the dark, in 15-minute steps. |

• At most 3 round trips are built: the best loop and two alternatives from other directions.
• A loop that fails your rules is counted in left_out and not kept. When none is kept, generated_left_out says why. |

One outing:

Errors

Every refusal also carries docs (this page's code on /api/errors), and field, limit and got, hint, retry_after or request_id where they apply, as the error standard describes (api-errors-v1, since 6 Oct 2026).

JSON, { "error": { "code", "message" } }.

How it works

• The curated outings are filtered in memory, nearest first. With a date, the nearest 2 × limit that match get their go window: one terrain sample and one forecast fetch each, four at a time. Then the list is ordered.
• A generated round trip is asked only when fewer than limit curated outings match. Its target length is under your caps: 90 % of max_km, or about 3.2 km per hour of max_hours for a hike, or 12 km. Your max_grade caps the paths it may use (T3 when unset). Its water and start stop come from the places index.
• The job is light without a generated loop, and heavy, like round trips, with one.

Versioning

New fields, notices, left_out reasons and sources may appear in outings/1. A change of a rule's meaning or of the order is outings/2.