API Documentation

Integrate ATRACAI's Time-to-Berth predictions and congestion forecasts into your applications.

Quick Start

No authentication required for read-only demo endpoints. Get an API key for production use.

What You Can Do

TTB Predictions

Get Time-to-Berth predictions with P50 and P90 confidence intervals

Congestion Forecasts

Predict port congestion 8h, 24h, 48h, and 72h ahead

Vessel Tracking

Track vessels within 350nm with position, zone, and characteristics

Model Metrics

Access real-time accuracy metrics and validation history

Authentication

API requests require an API key passed in the X-API-Key header. 

# Example request with authentication
curl -X GET "https://api.atracai.com/v1/predictions/STS" \
  -H "X-API-Key: your_api_key_here"

To get an API key, sign up for a plan or contact us for a trial.

Base URL

https://api.atracai.com/v1

All endpoints are relative to this base URL.

Rate Limits

Plan Requests/min Predictions/month
Starter 60 10,000
Growth 120 50,000
Enterprise 600 Unlimited

Ports

Get list of available ports with current status.

GET /ports

Response

{
  "ports": [
    {
      "code": "STS",
      "name": "Santos",
      "lat": -23.9674,
      "lon": -46.3280,
      "berths_total": 65,
      "queue": 12,
      "berths_occupied": 48,
      "utilization": 73.8,
      "vessels_tracked": 156,
      "last_update": "2026-01-23T14:30:00Z"
    }
  ],
  "timestamp": "2026-01-23T14:30:05Z"
}

Vessels

Get vessels for a specific port with positions and predictions.

GET /vessels/{port_code}

Path Parameters

port_code Port code (STS, VIX, SIN, PNG)

Response

{
  "vessels": [
    {
      "mmsi": 538008594,
      "name": "PACIFIC TRADER",
      "lat": -24.1234,
      "lon": -46.2345,
      "sog": 0.2,
      "cog": 180.5,
      "distance_nm": 2.3,
      "zone": "QUEUE",
      "destination": "SANTOS",
      "vessel_type": "Bulk Carrier",
      "dwt": 82500,
      "length_m": 229,
      "ttb_hours": 8.2,
      "ttb_p90": 12.4,
      "last_seen": "2026-01-23T14:28:00Z"
    }
  ],
  "zone_counts": {
    "BERTH": 48,
    "QUEUE": 12,
    "APPROACH_CLOSE": 8,
    "APPROACH_FAR": 23
  }
}

TTB Predictions

Get Time-to-Berth predictions for vessels at a port.

GET /predictions/{port_code}

Query Parameters

mmsi Optional. Filter by specific vessel MMSI
zone Optional. Filter by zone (QUEUE, APPROACH_CLOSE, APPROACH_FAR)

Response

{
  "predictions": [
    {
      "mmsi": 538008594,
      "vessel_name": "PACIFIC TRADER",
      "zone": "QUEUE",
      "ttb_hours": 8.2,
      "ttb_p90": 12.4,
      "time_slice": "0-8h",
      "model_version": "ttb_sts_prod_v4",
      "prediction_time": "2026-01-23T14:30:00Z",
      "features": {
        "queue_total": 12,
        "berth_utilization": 0.738,
        "dwt_class": "panamax",
        "distance_nm": 2.3
      }
    }
  ],
  "model_accuracy": {
    "mae_0_8h": 0.57,
    "mae_8_24h": 1.22
  }
}

Congestion Forecast

Get port congestion predictions at multiple time horizons.

GET /congestion/{port_code}

Response

{
  "port_code": "STS",
  "current_state": {
    "queue_total": 12,
    "berth_utilization": 0.738,
    "congestion_level": "moderate"
  },
  "forecasts": {
    "8h": {
      "probability": 0.65,
      "risk_level": "elevated",
      "confidence": 0.93
    },
    "24h": {
      "probability": 0.72,
      "risk_level": "high",
      "confidence": 0.91
    },
    "48h": {
      "probability": 0.58,
      "risk_level": "moderate",
      "confidence": 0.88
    },
    "72h": {
      "probability": 0.45,
      "risk_level": "normal",
      "confidence": 0.85
    }
  },
  "model_metrics": {
    "auc": 0.92,
    "f1": 0.80
  }
}

Berths

Get berth status and occupancy for a port.

GET /berths/{port_code}

Response

{
  "berths": [
    {
      "berth_id": "STS_B01",
      "name": "Berth 01 - Container",
      "status": "occupied",
      "current_vessel": {
        "mmsi": 477123456,
        "name": "EVER FORTUNE",
        "arrived": "2026-01-23T08:15:00Z"
      },
      "avg_turnaround_hours": 18.5
    }
  ],
  "summary": {
    "total": 65,
    "occupied": 48,
    "available": 17,
    "utilization": 0.738
  }
}

Validation Logs

Get historical prediction accuracy logs.

GET /validation-logs/{port_code}

Query Parameters

days Number of days of history (default: 7, max: 30)

Response

{
  "logs": [
    {
      "mmsi": 538008594,
      "vessel_name": "PACIFIC TRADER",
      "predicted_ttb": 8.2,
      "actual_ttb": 7.8,
      "error_hours": 0.4,
      "prediction_time": "2026-01-22T10:30:00Z",
      "berth_time": "2026-01-22T18:18:00Z"
    }
  ],
  "accuracy_summary": {
    "mae": 1.34,
    "median_error": 0.92,
    "predictions_count": 156
  }
}

MLOps Metrics

Get model performance metrics and operational health.

GET /mlops/{port_code}

Response

{
  "ttb_model": {
    "version": "ttb_sts_prod_v4",
    "algorithm": "LightGBM",
    "training_samples": 187006,
    "features": 11,
    "accuracy": {
      "mae_0_8h": 0.57,
      "mae_8_24h": 1.22,
      "mae_24_48h": 2.15
    }
  },
  "congestion_model": {
    "version": "congestion_catboost_v2",
    "algorithm": "CatBoost",
    "accuracy": {
      "auc_8h": 0.931,
      "auc_24h": 0.927,
      "f1_8h": 0.796
    }
  },
  "data_freshness": {
    "last_ais_update": "2026-01-23T14:30:00Z",
    "last_prediction_run": "2026-01-23T14:30:05Z",
    "update_frequency_minutes": 15
  }
}

Error Codes

Code Meaning
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing API key
403 Forbidden - Port not included in your plan
404 Not Found - Unknown port code or vessel
429 Rate Limit Exceeded - Too many requests
500 Server Error - Contact support

Changelog

v1.0 January 2026
  • Initial API release
  • TTB predictions for STS, VIX, SIN, PNG
  • Congestion forecasting at 8h, 24h, 48h, 72h
  • Vessel tracking with zone classification
  • MLOps metrics and validation logs

Ready to Integrate?

Get your API key and start making predictions today.

View Pricing Contact Sales