Use CHS published chart-datum offsets for Canadian stations instead of computed LLWLT

[bkeepers]

While validating #110, I benchmarked our datums against the CHS API for the 186 quality-accepted -can-meds stations. CHS metadata publishes each station's chart-datum offset, so we can compare their real chart datum against what we compute.

The result: computed LLWLT is a worse stand-in for CHS chart datum than LAT was.

	CHS CD above LAT	Our LLWLT above LAT	median error with CD=LAT	median error with CD=LLWLT
All (n=186)	0.09 m	0.27 m	0.13 m	0.19 m
Pacific (n=102)	0.11 m	0.38 m	0.13 m	0.23 m
Atlantic/Arctic (n=84)	0.04 m	0.13 m	0.12 m	0.12 m

The cause is not a bug in the LLWLT math. CHS chart datum is a frozen benchmark: it was established decades ago and is deliberately not recomputed, while our LLWLT is the textbook construct derived from today's constituents over the current epoch. Decades of relative sea-level change leave the operational datum much closer to modern LAT than a fresh LLWLT calculation, and occasionally below it. No constituent-derived datum can reproduce a fixed benchmark.

The saving grace of LLWLT is direction: our zero now sits about 0.17 m above CHS's, so predictions understate water depth, which is the safe error for navigation. The old LAT fallback overstated depth by about 0.09 m.

Proposal

For -can-meds stations, fetch the station's chart-datum offset from the CHS API (api-sine.dfo-mpo.gc.ca, the same metadata endpoint the neaps benchmark uses) during import and reference chart_datum to that published value instead of the computed LLWLT. That makes the error zero by construction, since we would be using the agency's own number.

Open questions:

• Where to store it. Probably overwrite the LLWLT value with the official offset (keeping the name), or add a separate datum entry so the computed value stays available.
• Terms of use for the CHS API data in a redistributed dataset need a check before we bake values into the repo.
• The same reasoning applies to any agency with a fixed benchmark. Japan (NLLW) and China (TLT) may have the same drift between the official surface and our computed one; worth checking if an equivalent API or table exists before trusting the computed values there.

Benchmark data and method are in the PR discussion for #110; the comparison used cached CHS metadata from neaps/benchmarks.

[bkeepers]

Verification for the frozen-benchmark claim, from an official CHS/DFO presentation, "Canadian Hydrographic Service: Chart Datum and the Continuous Vertical Datum (CVD)", October 10, 2025 (PDF):

"Once Chart Datum has been established in an area, it does not change again until it is updated by CHS."

The same deck says chart datum "is represented by benchmarks mounted at stations" that are "laser levelled to millimeter accuracy", and its CVD slides note that ideal surfaces are "corrected for sea level rise where possible", which acknowledges the drift between the adopted datum and present-day tides.

Two supporting points:

1. The deck includes a screenshot of a CHS station heights table where Lower Low Water Large Tide is listed at -0.01 m relative to chart datum and Lowest Astronomical Tide at -0.05 m. So even in CHS's own published tables, chart datum does not equal the current LLWLT computation, and their LLWLT-to-LAT gap (4 cm at that station) is far smaller than what we compute from constituents over the current epoch.
2. When the Great Lakes reference system changed from IGLD 1955 to IGLD 1985, CHS kept the datum plane: "Since the plane of chart datum wasn't changed, the depths and heights portrayed on the charts are the same for both reference systems" (tides.gc.ca). Same practice: the adopted plane persists across recomputations.

So "frozen" deserves one nuance: CHS can and occasionally does update chart datum, but it is an adopted, benchmark-maintained plane rather than something recomputed each epoch. The proposal stands: the offsets in the CHS API metadata are the authoritative values, and no constituent-derived computation should be expected to reproduce them.

[clarkbw]

Confirming the direction from the consumer side: I ran into this in signalk-tides, where neaps read consistently high against published CHS tide tables by about the per-station offset (#93 was the extreme case of it). Your benchmark puts a number on what I was seeing.

On the terms-of-use question — I looked at this closely last year and ended up designing around it, so here's what I found. The IWLS licence you accept by using the API is a bespoke Crown licence, not the Open Government Licence, and three clauses matter:

• Clause 3 — CHS copyrights "shall not be sold, licensed, leased, assigned or given to a third party."
• Clause 4 — prohibits derivative products "for commercial purposes, for sale or profit under any form whatsoever."
• Clause 10 — permits non-profit derivative products, provided you carry a prominent notice naming yourself, acknowledging CHS intellectual property and retained Crown copyright, stating it is not for navigation, and that CHS does not endorse it.

My read is that clause 10 lets an individual derive CHS values for their own non-commercial use, and clause 3 stops anyone from handing them a finished bundle. Baking the offsets into a CC BY 4.0 dataset is the case clause 3 describes, and it would also put a commercial-use restriction on a dataset whose licence promises the opposite — the mismatch is the part I'd worry about most, because downstream users have no way to see it.

What worked for me was shipping the pipeline instead of the data: the user runs a fetch-and-derive step themselves, the output lands on their machine, and the repo contains no CHS-derived values. It's more friction, but the friction is the licence. Code is at sailingnaturali/chs-constituents if the shape is useful — it does this for current constituents, but the fetch-cache-derive structure transfers directly to datum offsets, and an import step that populates a local copy would keep the repo clean.

One thing I'd raise separately: DFO publishes plenty under the OGL, and the IWLS licence being bespoke may be more historical than deliberate. Asking them to relicense the metadata would solve this for everyone downstream rather than each of us routing around it, and it costs an email.

On Japan and China — I'd treat each agency's licence as a separate question rather than assuming. NOAA being public domain is the exception, not the pattern.