How Lock Wait works

Ask the Corps for a lock's traffic and it returns the last thirty days. Ask again tomorrow and the window has moved: one new day at the front, one day gone from the back. Nothing older is published. Each bar below is one request we made for , drawn from the earliest to the latest arrival it returned.

The heavy line underneath is what the archive now holds for this lock: the union of every window. It grows by a day each day for as long as the collector runs. The same is true of lock status, which the Corps overwrites every fifteen minutes and does not publish at all as history.

The Corps' public lock application at ndc.ops.usace.army.mil is an Oracle APEX app. Behind it sits a documented JSON API (the Lock Performance Monitoring System, LPMS) with an OpenAPI catalogue. We use five parts of it.

One Python file using only the standard library, run as a systemd service with Restart=always. It does three things on a loop.

• Status, every 15 minutes. One request returns every reporting lock. This is the only record of live conditions that exists outside the Corps.
• A full sweep, every 24 hours. Lookups, then traffic and queue for each of the 192 locks, paced under the rate limit.
• A note of where it is. A small state.json records when the last sweep started and finished. A restart resumes the schedule; a sweep cut off part-way reruns.

Every response is written gzipped, byte for byte, before anything reads it, and one line is appended to a manifest. Failures are recorded the same way as successes. This is the manifest line for the most recent status request:

No database. The archive is a directory of gzipped files, one per request, named by endpoint, date and time:

/var/lib/corps-locks/
  manifest.jsonl              one line per request: time, url, status, bytes, sha256, rows
  state.json                  last sweep started / finished, last status pull
  raw/
    lock_status_report/2026-10-05/all_093905Z.json.gz
    traffic_report/2026-10-04/MI-27_150212Z.json.gz
    lock_queue_json/…   lock_numbers/…   river_codes/…
  reference/
    vessel_operators.csv      USCG official number → operating company
    lock_coords.csv           BTS lock locations, river miles, chamber sizes

Every 15 minutes a second script reads the whole archive and writes the JSON these pages use. It runs from scratch each time, so the site is always a pure function of the raw files.

1. Merge overlapping windows. Each lockage appears in up to thirty daily pulls. It is identified by lock, vessel number and arrival time and kept once.
2. Fold split flotillas. A tow too long for the chamber goes through in several cuts, each reported as a row. The builder keeps the first start, the last end and the largest barge count.
3. Measure the wait as start of lockage minus arrival. Values below zero or above two weeks are dropped as reporting errors.
4. Join three outside sources. Vessel numbers are Coast Guard official numbers, which the Corps' vessel-operator file and FCC ship-station licences both carry. Lock locations and dimensions come from the BTS National Transportation Atlas.
5. Fold status snapshots into a time series per lock.
6. Write and swap. Output goes to a sibling directory and replaces the live one in a single rename, so a reader never sees a half-written file.

Four static pages and one stylesheet. There is no build step and no framework. Each page fetches its JSON and draws with d3: a map of every lock, a small-multiples table of all 192, a page per lock that plots every lockage, and this one.

1. 4 Oct, morning Screened the idea as a data business: search demand, buyers, and whether the history really disappears.
2. 4 Oct 13:50 UTC Found the JSON API behind the Corps' lock app and confirmed the 30-day window.
3. 4 Oct 14:08 First collector run on a laptop. The first sweep finished at 15:36: 192 of 192 locks, no failures, 88 minutes.
4. 4 Oct 16:47 Made the collector restart itself after a crash or reboot; tested by killing it.
5. 4 Oct 17:01 Status every 15 minutes, matching the Corps' own refresh.
6. 4 Oct 20:18 Found a three-hour gap: the laptop had slept. Moved collection to a $4 server with a health check by 21:44.
7. 4 Oct, evening Joined vessels to operators through Coast Guard numbers and FCC licences.
8. 5 Oct Built the site, matched all 192 locks to locations, published at lockwait.com.