Measured, or modelled
Every reading that feeds a score carries a source_type. It tells you, at the point of decision, whether a value was measured or modelled. A model is never dressed up as an observation.
in_situ_observationA physical instrument measuring where it stands: a moored buoy reporting wave height and sea temperature, a coastal tide gauge, an airport weather station (METAR), a lightning-detection network. The closest thing to ground truth when one is near your spot and reporting recently.
satellite_observationEarth-observation products such as the Copernicus Marine sea-surface temperature and wave fields. Real measurements, but gridded and typically daily rather than a single instrument at your exact point.
forecast_modelA physics model projecting conditions forward: the wind, wave and weather forecast that anchors most scores, and the GloFAS river-discharge forecast. A prediction, not a reading, so we label it as one.
reanalysisA consistent model rebuild of what already happened, such as ERA5-Land snow (global). A background layer for where a live observation does not reach. A model, never presented as an observation.
How a reading becomes part of a verdict
An observation does not just get averaged in. It runs a gauntlet, and each stage is visible in the response.
Observe
Take the nearest reading from every wired source near the spot: buoys, gauges, stations, satellite, model.
Check freshness
Timestamp each reading and drop anything past its source-specific staleness window. Old data does not speak for now.
Weigh representativeness
Score how well the source stands in for the spot: exposure, depth, regime, not just distance in kilometres.
Correct or validate
A representative divergence can override the forecast; otherwise it only annotates it. Never silently.
Report confidence
Fold source quality, freshness and coverage into a confidence value, and say what limited it.
You can see it, per number
A slice of a real score response. The wave height came from a buoy standing in the water and was fresh enough to correct the forecast; the sea temperature is satellite; the river figure is a model forecast, labelled as one. Nothing hides.
overridden: truethe buoy was representative, so it corrected the forecaststale_minuteshow old the reading was, so you can apply your own tolerancemodeled_ vs observed_the field name itself tells you measured from modelled
When an observation corrects, and when it only validates
An observation near your spot does one of two things, and the response always says which.
The observed value is annotated alongside the forecast and the gap is reported, but the score does not change. Tide-gauge level, river discharge and snow sit here: ground-truth context without overriding the physics.
When a nearby, fresh observation diverges materially from the forecast it can override that value (a moored buoy correcting wave height), threshold-gated per variable. Only when it genuinely represents the spot: same exposure, depth and regime, not merely close.
Coverage varies, and we say where
Not every variable has an observation near every spot. Where a source is not close by, its block is left out of the response rather than filled with a guess. Two consequences worth stating plainly:
/v1/scoreWorks at any coordinate worldwide on forecast physics. Observation corrections appear where representative data exists nearby.
/v1/recommend-spotRanks catalogued sub-spots, so it is available in covered regions. Coverage differs by variable and region, and it is expanding.
A verdict supports a decision. It does not replace your judgment.
Goable turns conditions into an explainable verdict and can hard-limit a score through safety gates: lightning, wind hazard, air quality. It does not replace an operator's judgment or a sport's safety protocols. The final call to run a session stays with the human running it.