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
# 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" Parameters
| Name | In | Description |
|---|---|---|
pointsrequired | query | lat,lon pairs separated by |, at most 512. |
evidence | query | Add the route-snow-evidence/1 block. |
revision | query | Your geometry version, echoed back (1–64 letters, digits or ._:-). |
segments | query | Start indices of disconnected segments. |
Response
| Field | Type | Description |
|---|---|---|
evidence | object | |
forecast_24h | object | |
forecast_48h | object |
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)
| Field | Meaning |
|---|---|
schema | route-snow-evidence/1. A breaking change gets a new schema string; additions keep this one. |
revision | The revision you sent, or null. Drop an answer whose revision is not the one you show (a late answer after an edit). |
valid_for | now. 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. |
sampling | points, 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. |
summary | percent_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: observedis the current optical observation.mosaic_14dis 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_tilemeans no observation product covers the point (outside the snow regions, or not produced). -
obscuredmeans 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: observedpoint 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_utcin the generation's metadata. - The day is given only when every product that can answer the point states the same day.
-
It is
nullformosaic_14dand unknown points, for a product without a stated day, and where products disagree. Consumers must handlenull. - The tiles carry no per-pixel date beyond this, and a request time would be a fabrication.
-
A
- Unknown is never counted as clear.
-
coverage: nonemeans there is no percentage to show.
Failure states (unchanged endpoint behaviour)
| Situation | Answer |
|---|---|
| Snow inputs unreadable (corrupt generation metadata) | 503 snow evidence unavailable |
| Inputs changed during sampling | 503 Retry-After: 1 (retry once) |
| More than 512 points, bad coordinate, bad revision/segments | 400 |
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",
| Field | Meaning |
|---|---|
identity | 64 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_epoch | 64 hex: the optical, terrain, settings and code part of the identity, without the weather |
serving_epoch | The atomic serving snapshot's epoch (snow-serving-v2), or null where the snapshot is not used |
code_version, model_version | Hashes of the serving code, and of the code with the SNOW_* settings |
checked_at_utc | When this was read (the origin's clock) |
valid_until_utc | Trust 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.identityequals the currentidentity, and the current one is before itsvalid_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 answersCache-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:
| Status | When |
|---|---|
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.