> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axiomancer.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Cargo validation methodology
> How Axiom Overwatch infers cargo volumes from vessel position, draft, and dimensions — and what we cross-check against to keep the numbers honest.
Axiom Overwatch publishes weekly cargo volume estimates by port. This page explains how those numbers are produced and the validation paths that keep them grounded in reality.
## The inference chain
For each vessel arriving at or departing from a monitored port:
AIS message identifies the vessel by IMO. We look up its registered DWT, length, beam, and design draft from the global vessel registry.
The AIS Type-5 (static report) and Type-1/3 (position) messages include the vessel's current draft, broadcast by the captain. Differences between design draft and operational draft tell us whether the vessel is loading, unloading, or in ballast.
Tonnage carried = `f(DWT, draft, hull form)` using a hydrostatic curve appropriate for the vessel type (bulker, tanker, container). For bulkers, this is well-modeled with TPC (tonnes per centimetre).
When a vessel has a hydrostatic profile on file, Overwatch uses the full displacement table and trim model to produce a higher-confidence estimate. Water density at the port is factored in when available. Vessels without a profile fall back to the standard DWT-based approximation.
Sum across all departures for the week. Adjust for vessel-type-specific calibration factors derived from historical USDA actuals.
## What we validate against
| Source | Frequency | What it confirms |
| ------------------------------------ | ----------------- | -------------------------------------------------------------------------------------------------------- |
| **USDA Grain Transportation Report** | Weekly | Grain volumes at US ports (corn, wheat, soy) |
| **EIA petroleum data** | Weekly | Crude oil and refined product flows |
| **Port authority statistics** | Monthly–quarterly | Total throughput by port |
| **UN Comtrade** | Monthly | Bilateral trade flows for cross-check |
| **Mirror data** | Annual | Exporter-reported vs importer-reported volumes — large gaps signal misclassification or trade re-routing |
When our estimates diverge from authoritative sources by more than the tier-specific tolerance, the affected port is flagged in `/api/v1/anomalies/maturity` and a banner appears on the port detail page.
## Confidence tiers
Every estimate carries a confidence tier:
* **High** — historical agreement with authoritative data within ±5%
* **Medium** — within ±15%, or limited authoritative data available
* **Low** — within ±30%, or recent calibration changes
* **Indicative** — port is too new to validate against history; numbers are model-only
## Hydrostatic estimation
For vessels with a hydrostatic profile, Overwatch uses a multi-factor estimation path that produces more accurate cargo figures than the standard DWT-based method:
1. **Displacement table lookup** — the vessel's hydrostatic rows map draft readings to displacement tonnage, accounting for hull geometry.
2. **Trim correction** — a trim model adjusts the estimate for the difference between fore and aft drafts at arrival and departure.
3. **Water density adjustment** — local water density measurements at the port correct for the difference between freshwater and saltwater displacement.
The API exposes the estimation method and confidence score for each visit through the `hydrostatic_method`, `hydrostatic_confidence`, and `hydrostatic_confidence_score` fields on vessel visit records. See the [estimates API](/overwatch/api/estimates) for details.
### Water density sources
Each port's surface water density is refreshed monthly and used directly in the displacement step above. The ingestion picks the most accurate source available per port:
| Tier | Source | Coverage | Notes |
| ---- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | NOAA CO-OPS real-time water temperature + climatological salinity | US ports with a confirmed CO-OPS temperature gauge (New Orleans, Houston, Baltimore, Norfolk, Los Angeles) | Live temperature from a station inside the port approach paired with the regional climatological salinity for that water body. CO-OPS does not publish reliable real-time salinity at most open-ocean and Gulf stations, so salinity is always climatological. |
| 2 | Published climatological constants — slug override | Ports in unusual water bodies (Yamal/Arctic, Persian Gulf interior, Strait of Hormuz, Red Sea, Black Sea, English Channel) | Hand-tuned T/S for enclosed seas, Arctic ports, and high-salinity basins where a country-level mean would be misleading. |
| 3 | Published climatological constants — country | All other ports globally | Per-country regional means derived from WOA23 published surface climatology and NOAA Atlas 14. Currently covers USA, Brazil, Australia, Russia, Qatar, South Africa, the UAE, Iran, Saudi Arabia, Singapore, China, Oman, the Netherlands, Germany, Belgium, France, and Romania, with a global default for everything else. |
Density is computed from the resulting temperature and salinity using the **UNESCO-80** seawater equation of state at surface pressure. Each refreshed reading is stored per port at H3 resolution 8 along with its source identifier (`noaa_coops:+climato_sal` or `climato:`), so cargo estimates remain reproducible against the exact water density value that was used at the time.
The pipeline runs on the 1st of each month at 03:30 UTC, and rows older than 90 days are pruned automatically. Water density only changes meaningfully on a seasonal cycle, so a monthly refresh is sufficient for hydrostatic accuracy without introducing churn into historical estimates.
Historical vessel visits are periodically re-estimated as new hydrostatic profiles become available. If you notice cargo figures change for past visits, this is expected — the re-estimation improves accuracy for vessels that previously lacked profile data.
## What the model doesn't see
* **Ship-to-ship transfers** in international waters before arrival (we detect these separately under `/api/v1/risk/sts`, but they reduce arrival-port volume estimates).
* **Captain-falsified draft** declarations on AIS. We surface anomalies via `/api/v1/risk/mismatches`.
* **Container cargo** value — we estimate TEU counts, not invoice value.
* **Bagged cargo** in general-cargo vessels — TPC is less precise than bulk.
## Cross-checks built into the API
* `/api/v1/anomalies` — surfaces seasonal and trailing anomalies in the export volumes
* `/api/v1/anomalies/maturity` — per-port data sufficiency scores
* `/api/v1/calibration` — current calibration factors per vessel type
* `/api/v1/forecasts/accuracy` — MAE / MAPE / directional accuracy of forecasts vs actuals
If you're using Overwatch numbers in regulated reporting (commodity trading, ESG disclosure), pull the calibration + accuracy data alongside the estimates — it shows your auditor we're not hiding the residuals.