Skip to content

Snow along a route

GET https://api.trailsplits.com/tiles/v1/snow/route-forecast

Checked by a live probe Key optional · 500 credits a day without one 1 credit per call (per point)

Observed and recent snow cover at up to 512 sampled points, with 24 h and 48 h forecasts kept apart. With evidence=1 the answer carries route-snow-evidence/1: per-point class (snow, clear, unknown) and source, coverage, and a short validity. Unknown is never clear; narrow crossings between samples are not assessed. Points are lat,lon.

Example

Snow along a route (curl)
# Without a key, leave out the Authorization line (500 credits a day per address).
curl --fail-with-body 'https://api.trailsplits.com/tiles/v1/snow/route-forecast?points=46.0207,7.7491%7C46,7.7&evidence=1&revision=example1' \
  -H "Authorization: Bearer $TRAILSPLITS_API_KEY"

Sends a real request, with your key or the keyless allowance.

Parameters

NameInDescription
pointsrequiredquerylat,lon pairs separated by |, at most 512.
evidencequeryAdd the route-snow-evidence/1 block.
revisionqueryYour geometry version, echoed back (1–64 letters, digits or ._:-).
segmentsqueryStart indices of disconnected segments.

Response

FieldTypeDescription
evidenceobject
forecast_24hobject
forecast_48hobject
Full response schema (JSON Schema)
{
  "type": "object",
  "properties": {
    "evidence": {
      "type": "object",
      "properties": {
        "schema": {
          "type": "string",
          "enum": [
            "route-snow-evidence/1"
          ]
        },
        "revision": {
          "type": "string"
        },
        "valid_for": {
          "type": "string"
        },
        "sampling": {
          "type": "object",
          "properties": {
            "points": {
              "type": "integer"
            }
          },
          "required": [
            "points"
          ]
        },
        "summary": {
          "type": "object",
          "properties": {
            "percent_snow": {
              "type": "number"
            },
            "percent_clear": {
              "type": "number"
            },
            "percent_unknown": {
              "type": "number"
            },
            "coverage": {
              "type": "string",
              "enum": [
                "full",
                "partial",
                "none"
              ]
            }
          },
          "required": [
            "percent_snow",
            "percent_clear",
            "percent_unknown",
            "coverage"
          ]
        },
        "points": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "required": [
        "schema",
        "revision",
        "sampling",
        "summary",
        "points"
      ]
    },
    "forecast_24h": {
      "type": "object"
    },
    "forecast_48h": {
      "type": "object"
    }
  },
  "required": [
    "evidence"
  ]
}

Errors

400, 503, plus the gateway's 401, 429 and 503 (every error code). A refused request costs no credits.

Contract

Request

The existing endpoint, unchanged for everyone who does not ask:

GET https://api.trailsplits.com/tiles/v1/snow/route-forecast
    &release=current&z=13
    &evidence=1                     (opt in to the block below)
    &revision=<1–64 of A–Z a–z 0–9 . _ : ->   (echoed back; your route/plan revision)
    &segments=0,<start>,…           (start index of each disconnected segment; default 0)

Response: evidence (only with evidence=1)

FieldMeaning
schemaroute-snow-evidence/1. A breaking change gets a new schema string; additions keep this one.
revisionThe revision you sent, or null. Drop an answer whose revision is not the one you show (a late answer after an edit).
valid_fornow. The evidence describes the snow at generation.checked_at_utc, never a later date. For a plan's future days, use the forecast fields or say it is not a reading for that day.
samplingpoints, max_points (512), segments[] {id, from, to, length_m}, median_spacing_m, max_spacing_m, between_points. Stated, not assumed: a narrow crossing can lie between two samples; say so from max_spacing_m.
summarypercent_snow/clear/unknown of the sampled points, counts, sources {observed, mosaic_14d}, unknown_reasons {no_tile, obscured}, coverage (full, partial, none).
sections[]Runs of consecutive snow or unknown points inside one segment: segment, class, from_i, to_i, from_m, to_m, points, min_ele_m, max_ele_m. Never across a gap. Distances are along that segment.
points[]One per sample: i, segment, along_m, ele_m, class (snow·clear·unknown), source (observed · mosaic_14d · null), unknown_reason (no_tile · obscured · null), observed_on.

What the product can and cannot say

  • source: observed is the current optical observation. mosaic_14d is the cloud-free mosaic of recent passes, used where the current pass saw nothing: show it as an older observation, not today's.
  • unknown_reason:
    • no_tile means no observation product covers the point (outside the snow regions, or not produced).
    • obscured means cloud, shadow, forest or no data. The served product does not separate these, so v1 does not pretend to.
  • observed_on (filled since 3 October 2026, additive):
    • A source: observed point carries the acquisition day (YYYY-MM-DD, UTC) of the optical product that answered it.
    • The served regional products use the "latest cloud-free day" model (sentinel2_scl_latest_day): every pixel comes from one day, chosen_day_utc in the generation's metadata.
    • The day is given only when every product that can answer the point states the same day.
    • It is null for mosaic_14d and unknown points, for a product without a stated day, and where products disagree. Consumers must handle null.
    • The tiles carry no per-pixel date beyond this, and a request time would be a fabrication.
  • Unknown is never counted as clear.
  • coverage: none means there is no percentage to show.

Failure states (unchanged endpoint behaviour)

SituationAnswer
Snow inputs unreadable (corrupt generation metadata)503 snow evidence unavailable
Inputs changed during sampling503 Retry-After: 1 (retry once)
More than 512 points, bad coordinate, bad revision/segments400

Compatibility

All existing fields (fused, route.samples, forecast.issued_at_utc, cache_evidence.valid_until_utc, …) are unchanged, and evidence appears only when asked. The deployed guide, race, Planner and /route consumers are untouched. Cache-Control: no-store as before.

The evidence state on its own: GET /tiles/v1/snow/evidence (snow-route-evidence-v1)

GET /tiles/v1/snow/evidence
→ 200 { "schema": "snow-route-evidence-v1", "code_version", "model_version", "identity", "evidence_epoch", "serving_epoch",
FieldMeaning
identity64 hex. It changes when anything a snow answer depends on changes: the served optical products (or the serving snapshot's epoch), the terrain files, the SNOW_* settings, the code, the weather snapshot and its pointer, the weather cycle and its error, and the UTC day (the optical age gates move at midnight even when no file does). Equal identity, equal answer for the same route and settings
evidence_epoch64 hex: the optical, terrain, settings and code part of the identity, without the weather
serving_epochThe atomic serving snapshot's epoch (snow-serving-v2), or null where the snapshot is not used
code_version, model_versionHashes of the serving code, and of the code with the SNOW_* settings
checked_at_utcWhen this was read (the origin's clock)
valid_until_utcTrust the identity until then. At most 5 minutes after checked_at_utc, never past the next UTC midnight, never past the weather issue's age limit

Rules for a cache:

  • A cached snow answer may be served only while its own cache_evidence.identity equals the current identity, and the current one is before its valid_until_utc.
  • Unknown freshness is a miss: no answer, an unreadable body or a past valid_until_utc.
  • Fetch it with cache: no-store. The origin answers Cache-Control: no-store.
  • The site checks it at most every 30 s and drops it after 60 s.

What it may and may not claim:

  • It says that the inputs are unchanged. It does not say there is snow, or none, anywhere. It is no observation date: the observation dates are in the route answer (generation, samples).

Errors:

StatusWhen
503 {"error": "snow evidence changing or unavailable"}An input disappeared while it was listed (an atomic replacement in progress) or cannot be read. Retry after a few seconds; a cache treats it as a miss

Freshness: the inputs change with each snow publication (optical products, several times a day) and each weather cycle (6-hourly). identity follows within one listing.