Round trips from a start point

# Without a key, leave out the Authorization line (500 credits a day per address).
curl --fail-with-body 'https://api.trailsplits.com/v1/roundtrips' \
  -H "Authorization: Bearer $TRAILSPLITS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"start":[7.7491,46.0207],"distance_km":12,"profile":"hike"}'

{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "roundtrips/1"
      ]
    },
    "engine": {
      "type": "object"
    },
    "status": {
      "type": "string",
      "enum": [
        "complete",
        "rough"
      ]
    },
    "reason": {
      "type": "string",
      "nullable": true
    },
    "request": {
      "type": "object"
    },
    "loops": {
      "type": "array",
      "minItems": 1,
      "maxItems": 4,
      "items": {
        "type": "object",
        "properties": {
          "rank": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "complete",
              "rough"
            ]
          },
          "distance_m": {
            "type": "number"
          },
          "target_m": {
            "type": "number"
          },
          "target_error_pct": {
            "type": "number"
          },
          "repeated_m": {
            "type": "number"
          },
          "repeated_share": {
            "type": "number"
          },
          "shape": {
            "type": "string",
            "description": "Polyline6."
          },
          "ascent_m": {
            "type": "number",
            "nullable": true
          },
          "time": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true
          }
        },
        "required": [
          "rank",
          "status",
          "distance_m",
          "target_m",
          "target_error_pct",
          "repeated_share",
          "shape"
        ]
      }
    }
  },
  "required": [
    "schema",
    "engine",
    "status",
    "loops"
  ]
}

Give a start and a length; get back loops that start and end there, as the TrailSplits Planner builds them, each with the facts route analysis gives: surfaces, ways, tagged grades, climb, the hike time with its scope, and what is not known. When no good loop exists, the answer says so.

Request

{ "start": [7.7491, 46.0207], "distance_km": 12, "profile": "hike", "alternatives": 2 }

Defaults are listed in request.settings_defaulted. Unknown fields and fields that do not apply (max_sac on a bike) are refused, not ignored.

Response

Each loop:

Errors

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

A loop the work budget cut short is still answered when one was found (search.stopped says so); with none, the reason names the limit, never "no loop exists".

Every request is one heavy job: admission, the shared 25 s and 12 M-node budget, receipts with op: roundtrips, a hard kill 10 s past the deadline.

Hence 40 km on foot and 60 km by bike: inside about half the budget everywhere measured, and inside the 64-tile corridor up to about 60° north (a 60 km loop from Tromsø would still be refused as corridor_too_large).

Consumers

• The parity script (here) and npm run test:roundtrip.

Versioning

Additive fields may appear in roundtrips/1. A change of meaning, a removed field or a new default is roundtrips/2.

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://trailsplits.com/schemas/roundtrips-1.request.json",
  "type": "object",
  "additionalProperties": false,
  "required": ["start"],
  "properties": {
    "start": { "type": "array", "items": { "type": "number" } },
    "distance_km": { "type": "number" },
    "distance_m": { "type": "number" },
    "profile": { "enum": ["hike", "run", "bike"] },
    "direction": { "type": ["number", "null"] },
    "alternatives": { "enum": [0, 1, 2, 3] },
    "max_sac": { "enum": [1, 2, 3, 4, 5, 6] },
    "avoid_paved": { "type": "boolean" },
    "hills": { "type": "number" },
    "bicycle_type": { "enum": ["road", "hybrid", "mountain"] },
    "caller": { "type": "string" }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://trailsplits.com/schemas/roundtrips-1.response.json",
  "type": "object",
  "required": ["schema", "engine", "status", "reason", "request", "loops", "search", "timing"],
  "properties": {
    "schema": { "const": "roundtrips/1" },
    "status": { "enum": ["complete", "rough", "none"] },
    "reason": { "type": ["string", "null"] },
    "request": { "type": "object", "required": ["start", "target_m", "profile", "direction", "alternatives", "settings", "settings_defaulted"] },
    "loops": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["rank", "status", "distance_m", "target_m", "target_error_pct", "repeated_m", "repeated_share", "stem_m", "spur_m", "turn_points", "bearing_deg", "quality", "shape", "ascent_m", "descent_m", "ascent_method", "time", "surfaces", "hazards", "ways", "difficulty", "warnings", "unknowns"],
        "properties": {
          "status": { "enum": ["complete", "rough"] },
          "shape": { "type": "string" },
          "time": { "type": ["object", "null"], "required": ["model", "minutes", "moving_only", "applies", "calibration", "outside_calibration", "reasons", "models"] },
          "surfaces": { "type": "object", "required": ["paved_m", "gravel_m", "trail_m", "unknown_m", "mapped_m", "class_default_m", "stretches"] },
          "ways": { "type": "object", "required": ["by_type_m", "marked_m", "max_sac", "ford_m", "aid_m", "informal_m", "steps_m"] },
          "difficulty": { "type": ["object", "null"], "required": ["scale", "graded_m", "untagged_path_m", "road_m", "hardest"] },
          "warnings": { "type": "array", "items": { "type": "object", "required": ["code", "message"] } },
          "unknowns": { "type": "array", "items": { "type": "object", "required": ["code", "message"] } }
        }
      }
    },
    "search": { "type": "object", "required": ["version", "tree_nodes", "candidates", "pairs_routed"] },
    "timing": { "type": "object" }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://trailsplits.com/schemas/roundtrips-1.error.json",
  "type": "object",
  "required": ["error"],
  "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }
}