Backtesting

The backtesting API compares Overwatch hydrostatic cargo estimates against ground truth observations from port authority manifests, bills of lading, and customs declarations. Use it to audit estimate accuracy, identify systematic biases by vessel class or route, and calibrate the hydrostatic model. For how the estimates themselves are produced, see the cargo validation methodology.

GET /api/v1/backtesting/cargo-validation

Runs a full backtesting report over a configurable lookback window. The endpoint matches vessel visits with ground truth records by IMO number and arrival date, then computes error metrics overall and by segment.

Parameters

Response

{
  "generated_at": "2026-04-18T12:00:00Z",
  "window": {
    "from": "2025-04-18T12:00:00Z",
    "to": "2026-04-18T12:00:00Z",
    "lookback_days": 365,
    "max_match_distance_days": 7
  },
  "methodology": {
    "ground_truth_sources": [
      {
        "key": "antaq_vessel_calls",
        "type": "port_authority_manifest",
        "description": "Brazil ANTAQ vessel call records with cargo_tons used as observed cargo proxy."
      },
      {
        "key": "cargo_ground_truth_observations",
        "type": "bill_of_lading/customs_declaration",
        "description": "Externally sourced bill-of-lading and customs declaration observations when available."
      }
    ],
    "matching_rule": {
      "join_key": "imo_number",
      "timing_alignment": "closest observed_at to vessel_visits.arrived_at within 7 days",
      "port_alignment": "port-name fuzzy alignment receives higher ranking"
    },
    "error_metrics": ["MAPE", "MAE", "RMSE", "mean signed error"]
  },
  "ground_truth_source_counts": {},
  "overall_metrics": {
    "sample_size": 847,
    "mape_pct": 12.4,
    "mae_tons": 3200,
    "rmse_tons": 4800,
    "mean_signed_error_tons": -420
  },
  "breakdowns": {
    "vessel_class": [],
    "route": [],
    "cargo_type": [],
    "weather": []
  },
  "trim_salinity_feedback": [],
  "persistence": { "run_id": null, "saved": true, "error": null },
  "matched_rows": []
}

ground_truth_source_counts maps "<source_type>:<source_name>" (e.g. "port_authority_manifest:antaq_vessel_calls") to the number of matched rows sourced from it.

Overall metrics

Breakdowns

The breakdowns object contains the same set of metrics grouped by four dimensions:

• vessel_class — by vessel type (bulk carrier, tanker, container, etc.)
• route — by origin–destination country pair
• cargo_type — by commodity
• weather — by weather conditions at departure (calm, moderate, rough, unknown)

Each breakdown entry includes bucket, sample_size, mape_pct, mae_tons, rmse_tons, and mean_signed_error_tons.

Trim/salinity feedback

The trim_salinity_feedback array highlights vessel segments where the hydrostatic model shows systematic bias. Each entry includes the observed bias direction and a recommendation for tuning the trim or salinity correction factor. Only segments with at least five matched observations are included.

Methodology

Each response includes a methodology block that documents which ground truth sources were used, how visits were matched, and which error metrics were computed. This makes every backtesting run self-documenting for audit purposes.

Matched rows

Each matched_rows entry carries visit_id, imo_number, vessel_type, commodity, route, weather_bucket, estimated_cargo_hydrostatic, actual_cargo_tons, error_tons, abs_error_tons, ape_pct, hydrostatic_method, hydrostatic_confidence_score, ground_truth_source, ground_truth_source_type.

Persistence

Each backtesting run is saved automatically. The persistence block in the response includes a run_id you can use to reference the run later, and a saved flag indicating whether persistence succeeded.

Errors

• 403 — Admin API key required (analyst access: caller must resolve to internal or admin tier)
• 500 — Database query failed

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://www.axiomoverwatch.io/api/v1/backtesting/cargo-validation?lookback_days=180&max_match_days=5"