ATRACAI | Interactive API Documentation

ATRACAI API Reference

Real-time maritime intelligence for 18+ global ports. Access TTB predictions, congestion forecasts, commodity flows, vessel DNA profiles, and fleet analytics through a unified REST API.

Base URL

All endpoints are served from https://api.atracai.com (port 8090). Responses are JSON. Timestamps are ISO 8601 UTC. Distances are in nautical miles. Times are in hours.

Quick Start

1. Create an account to get your API key.
2. Include the key in requests: X-API-Key: atrc_your_key_here
3. Make your first call: GET /api/global/ports

Authentication

All API endpoints require authentication via the X-API-Key header or the api_key query parameter. Get your key from the Developer Portal.

# Header authentication (recommended)
curl -H "X-API-Key: atrc_your_key_here" \
  https://api.atracai.com/api/global/ports

# Query parameter authentication
curl https://api.atracai.com/api/global/ports?api_key=atrc_your_key_here

Rate Limits

Rate limits are enforced per API key per minute. The response includes X-RateLimit-* headers showing your current usage and remaining quota.

Tier	Requests/min	Data Delay	Ports
Free	10	60 min	1 (STS)
Basic	60	Real-time	1
Professional	300	Real-time	3
Enterprise	1,000	Real-time	10+

Port State

Full intelligence report for any port -- queue depth, berth utilization, inbound vessels, congestion level.

GET /api/report/{port_code} AUTH

Param	Type		Description
port_code	string	required	3-letter port code (e.g. STS, PNG)

curl Python JavaScript

curl -H "X-API-Key: YOUR_KEY" \
  https://api.atracai.com/api/report/STS

import requests

resp = requests.get(
    "https://api.atracai.com/api/report/STS",
    headers={"X-API-Key": "YOUR_KEY"}
)
data = resp.json()
print(data["port"], data["summary"])

const resp = await fetch(
  "https://api.atracai.com/api/report/STS",
  { headers: { "X-API-Key": "YOUR_KEY" } }
);
const data = await resp.json();
console.log(data.port, data.summary);

Try It

Port Snapshot History

Time-series port state (last 24h, 15min intervals). Queue depth, berth utilization, inbound count.

GET /api/snapshot/{port_code} AUTH

Param	Type		Description
port_code	string	required	3-letter port code

// Response
{
  "port_code": "STS",
  "snapshots": [
    {
      "time": "2026-03-01T10:00:00+00:00",
      "queue": 22,
      "berths": 41,
      "utilization": 74.5,
      "inbound": 12
    }
  ]
}

Try It

Congestion Forecast

ML-based congestion probability at 8h, 24h, 48h, and 72h horizons. AUC ~0.76-0.77.

GET /api/global/overview AUTH

Returns congestion status for all ports your API key has access to.

// Response fields per port
{
  "code": "STS",
  "name": "Santos",
  "queue": 22,
  "berths_occupied": 41,
  "utilization": 74.5,
  "congestion": "HIGH",
  "delta_queue_6h": 3,
  "inbound": 12
}

Try It

Active TTB Predictions

Live Time-to-Berth predictions for all inbound vessels, using 6 vessel-type LightGBM models. Predictions include confidence, queue probability, and JIT advice.

GET /api/predictions/{port_code} AUTH

Param	Type		Description
port_code	string	required	3-letter port code

{
  "predictions": [
    {
      "mmsi": "636092587",
      "vessel_name": "NORD VENUS",
      "ttb_hours": 48.2,
      "distance_nm": 145.3,
      "zone": "APPROACH_FAR",
      "dwt_class": "bulk",
      "confidence": 0.35,
      "will_queue": true,
      "queue_probability": 0.82,
      "prediction_time": "2026-03-01T12:00:00Z"
    }
  ],
  "total": 28
}

Try It

Vessel Journey

Full prediction history for a specific vessel showing zone transitions, TTB convergence, and actual outcome.

GET /api/vessel-journey/{port_code}/{mmsi} AUTH

Param	Type		Description
port_code	string	required	3-letter port code
mmsi	string	required	Vessel MMSI number

Port Commodity Flow

Real-time commodity breakdown by queue, berth, and approaching vessels.

GET /api/commodity/flow/{port_code} AUTH

{
  "port_code": "STS",
  "commodities": [
    {
      "commodity_group": "GRAIN",
      "queue_count": 8,
      "berth_count": 5,
      "total_dwt_queue": 480000,
      "delta_queue_24h": 2
    }
  ]
}

Global Commodity Tracking

Track a commodity across all ports. Where is the soy? The iron ore? Across your subscribed ports.

GET /api/commodity/global/{commodity_code} AUTH

Param	Type		Description
commodity_code	string	required	Commodity group: GRAIN, MINERALS, PETROLEUM, CHEMICALS, CONTAINER, VEHICLE, FOREST, AGRI

Vessel DNA Profile

Computed vessel profile: ballast/laden draught, cargo capacity estimate, block coefficient, recent draught history.

GET /api/vessel/{mmsi}/dna AUTH

{
  "mmsi": 636092587,
  "vessel_type": "Bulk Carrier",
  "size_class": "Capesize",
  "deadweight": 180000,
  "ballast_draught": 7.2,
  "laden_draught": 18.1,
  "max_cargo_capacity": 165000,
  "observations": 47
}

Carbon Profile

Idle carbon cost for vessels at anchor. EU ETS exposure calculation, daily fuel burn, CO2 emissions.

GET /api/vessel/{mmsi}/carbon AUTH

Returns carbon cost breakdown for vessels currently at anchor.

Fleet Vessels

Get real-time status for a fleet of vessels. Positions, zones, predictions, and alerts.

GET /api/fleet/vessels?mmsis={csv} AUTH

Param	Type		Description
mmsis	string	required	Comma-separated MMSI numbers

Alert Feed

Live commodity trader alert feed. Filterable by commodity, port, severity, and time window.

GET /api/alerts/feed PUBLIC

Param	Type	Description
commodity	string	Comma-separated: SOYBEANS,IRON_ORE
port	string	Comma-separated: STS,PNG
severity	string	Comma-separated: HIGH,CRITICAL
since	string	Time window: 2h, 6h, 24h, 7d

Try It

Charter Predictions

TTB predictions with JIT slow-steam advice for charterers. Includes fuel savings estimates.

GET /api/charter/predictions PUBLIC

Param	Type		Description
port	string		Port code (default: STS)
vessel_type	string		Filter: bulk, tanker, general, vehicle, passenger

Try It

Subscribe to Webhook

Create a webhook subscription to receive real-time event notifications. Enterprise tier required.

POST /api/webhooks/subscribe AUTH + ENTERPRISE

// Request body
{
  "webhook_url": "https://your-server.com/webhook",
  "event_types": ["vessel.arrived", "congestion.high"],
  "port_codes": ["STS", "PNG"]
}

// Response
{
  "subscription_id": 42,
  "webhook_secret": "a1b2c3d4...",
  "status": "active",
  "note": "Store the webhook_secret securely."
}

Available event types: vessel.arrived, vessel.departed, vessel.zone_change, congestion.high, congestion.critical, prediction.new, commodity.surge, ais_gap.detected

Error Codes

All errors return JSON with a detail field describing the issue.

Code	Meaning	Action
200	Success	--
400	Bad Request	Check parameters
401	Unauthorized	Provide valid API key
403	Forbidden	Port or feature not in your tier
404	Not Found	Invalid port code or endpoint
429	Rate Limited	Check X-RateLimit-Reset header
500	Server Error	Contact support@atracai.com

{
  "detail": "Rate limit exceeded (10/min for free tier)"
}

Port Codes

All supported 3-letter port codes.

        Loading port codes...
      