This one started with a snap judgment, and the snap judgment was wrong in the most useful way. I was looking at XTide, the reference-grade open-source tide and current predictor, and my first reaction was: this website looks like it was built in 1998, I wouldn’t trust something this poorly put together. That reaction is unfair — XTide’s data is impeccable, and the crustiness of a maintainer’s homepage tells you nothing about the quality of the harmonic constants underneath it. But being wrong about XTide’s site pushed me to the right question about XTide’s role: do I even need to harvest XTide’s data, or can I go straight to the source it ultimately derives from — NOAA? Chasing that question cost me two full days walking into walls that both looked like the end of the road. Neither was.

TL;DR — I wanted US tidal-current harmonic constituents for an offline engine. Wall 1: NOAA’s harcon.json returned an empty constituent list for current stations, so I concluded NOAA doesn’t publish current constituents. Wrong — it’s empty only at bin=0; query the station’s currbin and you get 26 real constituents (Deception Pass M2 = 5.418 kn @ 241.2° GMT). Empty ≠ absent. Wall 2: currents_predictions returned “not available from the requested station” for every station — including NOAA’s own documented example — so it looked like a dead product. Wrong again: browser User-Agent + a real prediction station + its currbin and it returns data. The service was never down; my request was. Outcome: XTide dropped entirely, 855 harmonic + ~1,700 subordinate stations straight from NOAA, validated to 9.7 min / 0.055 kn against NOAA’s own predictions. Jump to the validation.

Plan A, and why it wasn’t Plan A for long

The engine already predicted tides from NOAA harmonic constants, offline and validated to a few minutes against CO-OPS. Currents are the same math — a sum of cosines that happens to produce signed velocity instead of height — so the only new input was current constituents. The obvious source was XTide’s Harmbase2 (via libtcd): US current stations, public-domain-derived, exactly the constants I needed.

But routing through XTide means adopting XTide’s snapshot of the constants, its naming, its extraction toolchain, and its update cadence. If NOAA publishes the same constituents directly, I’d rather consume them at the source and skip the middleman entirely. So before committing to Harmbase2, I spent an hour poking at NOAA’s metadata API to see whether the current constituents were there.

They appeared not to be. That’s Wall 1.

Wall 1: “NOAA doesn’t publish current constituents”

NOAA’s CO-OPS metadata API (mdapi) serves harmonic constituents for a station at:

https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi/stations/<id>/harcon.json?units=english

For a tide station this returns the full constituent set. For a current station — Deception Pass, Rosario Strait, the passes I actually cared about — it returned a valid JSON envelope with an empty constituent array. Not a 404, not an error. Just: here is your station, and it has zero harmonic constituents.

The natural read is that current stations simply don’t carry published constituents — that NOAA serves current predictions as a finished product but keeps the underlying harmonics private, the way some hydrographic services do. I wrote that down as a finding and started building the XTide extractor for real.

That conclusion was wrong, and the tell was sitting in the station metadata the whole time. Current stations are three-dimensional in a way tide stations aren’t: a current is measured at a depth bin, and each station has a reference bin — the depth the published predictions are computed for. That field is currbin, and it’s right there in the station-list record:

https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi/stations.json?type=currentpredictions&units=english

Each record carries id, name, lat/lng, type (H = harmonic, S = subordinate, W = weak/rotary), and crucially currbin. The harcon.json endpoint takes a bin parameter, and it defaults to bin=0. Bin 0 is above the reference depth for these stations — there’s no harmonic solution published there, so the array is legitimately empty. Ask for the right bin and the data pours out:

harcon.json?units=english&bin=<currbin>

Deception Pass Narrows (PUG1701, currbin=18) returns 26 constituents, and they’re exactly what a current predictor needs — richer than the tide equivalent:

constituentName   "M2"
majorAmplitude    5.418      // knots, major-axis semi-amplitude
majorPhaseGMT     241.2      // Greenwich-referenced phase, degrees
majorMeanSpeed   -0.619      // mean flow along the axis (Z0), knots
azi               92.9       // major-axis azimuth, degrees true
minorAmplitude / minorPhase  // the rotary (cross-axis) component
binNbr / binDepth / constNum

That’s the whole model: majorAmplitude and majorPhaseGMT drive the sum, azi gives the flood axis (ebb is azi+180), and majorMeanSpeed is the Z₀ offset for a station whose flow doesn’t average to zero. The empty array wasn’t NOAA telling me the data didn’t exist. It was NOAA answering a question I hadn’t meant to ask — what are the constituents at the surface? — and me reading the answer as there are no constituents.

Empty is not absent. An empty result to a query with a defaulted parameter is a statement about your query, not about the data. That cost me the better part of a day and an entire wrong architecture.

Wall 2: “the predictions API is down”

With constituents in hand I needed an oracle — NOAA’s own predicted slack/max events — to validate the engine against. That lives on the older Data Retrieval API:

https://api.tidesandcurrents.noaa.gov/api/prod/datagetter
  ?product=currents_predictions&interval=max_slack&bin=<currbin>
  &station=<id>&begin_date=...&end_date=...&units=english&time_zone=gmt&format=json

Every station I tried came back with:

{ "error": { "message": "Currents predictions are not available from the requested station" } }

Every one. Including the station NOAA uses in its own API documentation as the worked example. When even the documented example fails, the honest inference is that the product is down — CO-OPS was mid cloud-migration that week, so a dead endpoint was entirely plausible. I nearly wrote it off and shipped with structural validation only.

It wasn’t down. There were three separate things wrong, stacked, each one enough on its own to produce a failure that looked like an outage:

(a) NOAA 404s the default User-Agent. Plain curl and Node’s fetch send a default UA (curl/8.x, node), and NOAA’s edge returns a bare 404 for it. The exact same request from a browser — same machine, same residential IP — returns data. Send a browser User-Agent header and this failure vanishes:

User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...

(b) Transient rate-limiting that looks like an IP block. My probing volume (I was hammering the endpoint trying to figure out why it failed) tripped NOAA’s throttle, which also returns bare 404s. I spent an embarrassing stretch convinced NOAA was blocking datacenter IPs — I’d seen mdapi 404 from cloud egresses before — until the same box that was 404ing from a script served the request fine in a browser. That’s not an IP block; an IP block would fail in the browser too. The variable that changed between the two was the User-Agent (and the request pacing), not the IP. Slow down and send a real UA and the 404s stop.

(c) Wrong stations at the wrong bin. Some of the stations I was hammering are observation / survey stations, not published-prediction stations — currents_predictions genuinely isn’t served for those, correctly. My actual target passes (PUG1701 Deception Pass, PUG1717 Turn Point) are survey stations NOAA doesn’t publish predictions for. But hundreds of other harmonic stations are served — PUG1741 (Bellingham Channel), PUG1612 (Clinton Ferry), SFB1222 — and only when queried at their currbin.

Fix all three — browser UA, polite pacing, a served station at its reference bin — and currents_predictions returns clean data. It was never down. Every failure I saw was my own request.

The turn: verify against a known-good client

What actually broke the logjam wasn’t a NOAA status page. It was reading someone else’s working code.

I found the Perigee-Tides MCP, a third-party client that talks to the same CO-OPS endpoints, and diffed its request construction (src/services/data-api.ts, metadata-api.ts) against mine. Byte for byte, the URL shape, the parameters, the field names — identical. My request format was correct. It had been correct the whole time.

That’s the pivot the whole debugging session turned on, and it generalizes:

When your request matches a known-good client and it still fails, the variable is the target, not the syntax. Stop editing the request and start changing what you point it at — the station, the bin, the headers, the rate.

Once the format was ruled out, the remaining differences could only be the station, the bin, the UA, and the request rate — which is exactly where the three real problems were. I’d spent hours suspecting my URL. The URL was fine.

Outcome: XTide dropped entirely

Both walls fell, and on the far side of them the original question answered itself: I don’t need XTide at all. Everything comes straight from NOAA CO-OPS, public domain:

  • Constituents — harcon.json at the station’s currbin.
  • Flood/ebb axis — azi (flood) and azi+180 (ebb).
  • Mean flow — majorMeanSpeed as the Z₀ offset.
  • Subordinate stations — currentpredictionoffsets.json, giving time and speed offsets against a reference harmonic station.

The build-time extractor sweeps NOAA’s station list and pulls each station’s harcon (at its currbin) and offsets, producing a bundled currents.json computed offline at runtime — 855 harmonic + ~1,700 subordinate stations, all of US waters, including the US Salish Sea passes I set out for: Deception Pass, Rosario, San Juan Channel, Turn Point. No XTide data, no tide binary, no libtcd, at build time or run time.

The receipt: vs NOAA’s own predictions

Once currents_predictions was serving, it became the oracle it was always meant to be — the independent authority check. Feed the engine a station’s published constituents, predict its slack/max events, and compare to NOAA’s own published events for the same station and days.

Harmonic station — PUG1741 (Bellingham Channel), a clean ~2.8 kn reversing station: max flood/ebb events match NOAA to 9.7 min / 0.055 kn across 11 events — on par with the tide engine’s Phase-0 (7.9 min / 3.5 cm). The fixture is captured offline so the check runs in CI without the network.

Subordinate reduction — PCT0236 (reference SFB1201): 6.1 min / 0.05 kn over 11 events. Subordinate stations were subtler than tides because NOAA publishes two slack offsets — slack-before-flood (sbfTimeAdjMin) and slack-before-ebb (sbeTimeAdjMin) — not one. A slack takes the offset for the phase it precedes. Model it with a single slack offset and half your slacks land at the wrong minute.

One labeling insight fell out of matching NOAA at weak stations: classify max flood vs max ebb by the sign of the velocity, not by slope high/low. At a strong reversing pass, a velocity peak (slope zero) that’s positive is a flood and negative is an ebb, and high/low slope gives the same answer. But at a weak, non-reversing station a relaxation peak never crosses zero — a −0.3 kn local maximum during a long ebb is slope-high but it’s still an ebb. Label it by sign and you match NOAA’s max_slack exactly.

The bugs only a batch caught

Validating one station passed clean. Then I validated a diverse batch — different regions, offset signs, speed ratios, harmonic and subordinate — and it broke in two different ways the single-station test had walked right past. Both are the same shape: a category I’d treated as monolithic turned out to have a second variety, and only the second variety triggered the bug.

A reference is (station, bin), not just a station. A subordinate references a specific bin of its reference station (refStationBin) — because, same lesson as Wall 1, a current reference is depth-keyed. My extractor stored one bin’s constituents per reference. That’s fine until a reference publishes multiple bins with different constituents. SFB1201 publishes bins [26, 20, 10], each with its own harmonic set. Storing one silently resolved half the subordinates against the wrong constituents — ~50 min and ~0.6 kn off. The single-station test had happened to hit the bin I’d stored, so it passed and told me nothing. Fix: resolve each reference at its exact refStationBin.

“Subordinate” doesn’t always mean subordinate. Some NOAA type: S stations carry their own harmonic constituents, and NOAA predicts those harmonically — the offset reduction is only for stations that have none. PUG1716 (which references San Juan Channel) is type S but has its own 25-constituent harcon; reducing it from San Juan Channel over-shot it by 89 min / 0.7 kn. Predicted from its own constituents: 6.8 min / 0.06 kn. Fix: for a type-S station, fetch its own harcon first; fall back to the reduction only when it’s empty. With both fixes, nine genuinely-subordinate stations match NOAA to 0.9–7.7 min.

The lesson keeps recurring in this engine: n=1 validation hides class bugs. One passing station proves one station. Validate across the diversity of the data — regions, bins, ratios, harmonic and subordinate — and the class of bug that only shows up at the second variety finally has somewhere to show up.

The passes I set out for turned out served

There’s a fitting last twist. This whole project started to get currents for my home passes — Deception Pass, Rosario Strait, San Juan Channel, Turn Point. Early on those returned "not available", so I filed them as survey stations NOAA doesn’t predict and validated them only transitively — engine-correct-on-other-stations plus faithful constituents. That was Wall 2 in miniature, and I’d quietly surrendered to it.

Re-checked with the right bin and a browser User-Agent: every one is served. They validate directly against NOAA’s own predictions now — Deception Pass to 14 min, Admiralty Inlet to 3.5, Race Rocks to 6.0, on the significant currents. (The weak sub-¾-knot relaxation extrema at the mixed-tide stations disagree by tens of minutes — but those are ill-conditioned in NOAA’s computation too, and a boat doesn’t care when a third of a knot peaks.) The premise that my home water was unreachable was, like every wall in this story, my request being wrong — not the data being absent.

Five things I’m keeping

  1. Empty ≠ absent. An empty result to a query with a defaulted parameter (bin=0) is a fact about your query, not about the data. Check what you defaulted before you conclude the data doesn’t exist.
  2. “The service is down” is usually your request. Three stacked causes — User-Agent, rate, target — each looked like an outage. The endpoint was serving the whole time.
  3. An ugly UI is not evidence about data quality. XTide’s 1998 homepage says nothing about its constants. The reaction was wrong, but interrogating it led to the better architecture — go to the source.
  4. Verify against a known-good client before you touch your request. When your request matches a working client and still fails, the variable is the target, not the syntax.
  5. Validate at scale, not n=1. One passing station hid two bugs here, each triggered only by a second kind of station. Test across the diversity of the data — and the passes you gave up on may turn out served all along.

The engine is MIT-licensed and the currents fixtures are reproducible from NOAA’s own predictions: slackwater-engine. If it’s off at your home pass, the golden generator points at any served NOAA station — run it and send a number back.

Not for navigation. Current predictions are astronomical estimates and don’t account for wind, freshet, or local effects. Carry official current tables and charts.