> ## 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.

# Forecasts

> Cargo volume forecasts and accuracy tracking by port and commodity, plus per-vessel ETA distributions for in-transit voyages with rolling backtest metrics.

Cargo volume forecasts and accuracy tracking.

## `GET` `/api/v1/forecasts`

Cargo volume forecasts by port and methodology.

**Parameters**

| Name     | Type   | Required | Description                         |
| -------- | ------ | -------- | ----------------------------------- |
| `port`   | string |          | Port slug                           |
| `method` | string |          | 'pipeline' \| 'statistical' \| 'ml' |
| `limit`  | number |          | Default 50, max 200                 |

**Response**

```json theme={null}
{ "forecasts": [...] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/forecasts?port=VALUE&method=VALUE
```

## `GET` `/api/v1/forecasts/accuracy`

Forecast accuracy metrics (MAE, MAPE, directional accuracy).

**Parameters**

| Name     | Type   | Required | Description     |
| -------- | ------ | -------- | --------------- |
| `port`   | string |          | Port slug       |
| `method` | string |          | Forecast method |

**Response**

```json theme={null}
{ "accuracy": [...] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/forecasts/accuracy?port=VALUE&method=VALUE
```

## `POST` `/api/v1/predict-destination`

<Note>Requires API key.</Note>

Predict the next destination port for a vessel from its recent movement pattern. The model consumes an ordered sequence of H3 cells the vessel has passed through and, optionally, draft changes that hint at loading or discharge events. Use this when you need a live forward-looking guess — for example, to populate an ETA widget, rank which vessels to investigate next, or enrich a dashboard where the AIS-reported destination is missing or unreliable.

Pair this endpoint with `GET /api/v1/destination-reliability` to decide whether to trust the vessel's declared destination or fall back to the model prediction.

**Body**

| Name                 | Type      | Required | Description                                                                                   |
| -------------------- | --------- | -------- | --------------------------------------------------------------------------------------------- |
| `mmsi`               | string    | ✓        | Vessel MMSI                                                                                   |
| `active_h3_sequence` | string\[] | ✓        | Ordered list of H3 cell indexes the vessel has moved through, oldest first. Up to 256 entries |
| `draft_current`      | number    |          | Current reported draft in meters                                                              |
| `draft_delta`        | number    |          | Change in draft since start of the sequence, in meters                                        |

Request payloads are capped at 32 KB.

**Response**

```json theme={null}
{
  "predictions": [
    { "port": "sgsin", "probability": 0.42 },
    { "port": "mypkg", "probability": 0.19 },
    { "port": "idjkt", "probability": 0.11 }
  ]
}
```

**Example**

```bash theme={null}
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://axiomoverwatch.io/api/v1/predict-destination \
  -d '{
    "mmsi": "563123456",
    "active_h3_sequence": ["8a2a1072b59ffff", "8a2a1072b58ffff", "8a2a1072b41ffff"],
    "draft_current": 12.4,
    "draft_delta": -0.8
  }'
```

## `GET` `/api/v1/destination-reliability`

Vessel destination declaration reliability scores.

**Parameters**

| Name     | Type   | Required | Description                              |
| -------- | ------ | -------- | ---------------------------------------- |
| `vessel` | string |          | IMO number                               |
| `tier`   | string |          | 'reliable' \| 'moderate' \| 'unreliable' |
| `limit`  | number |          | Default 100, max 500                     |

**Response**

```json theme={null}
{ "reliability": [...] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/destination-reliability?vessel=VALUE&tier=VALUE
```