API Documentation

The ShipRadar REST API gives you live AIS vessel positions, search, and port traffic data.

Authentication

All /api/v1/* endpoints require a Pro API key in the Authorization header. Generate keys at /account/api-keys.

curl https://shipradar.io/api/v1/vessels/565819000 \
  -H "Authorization: Bearer sr_live_…"

Rate limits

Authed: 600 requests / minute per key.
Anonymous: 60 / minute per IP (for the public site-rendering endpoints; not the v1 surface).

Every response includes x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset headers. 429 with { "error": "rate limited" } when exceeded.

GET /api/v1/vessels/:mmsi

Latest snapshot for one vessel. Falls back to Postgres if the vessel has aged out of the Redis hot cache.

{
  "vessel": {
    "mmsi": 565819000,
    "name": "MAERSK ALGOL",
    "imo": 9333394,
    "category": "cargo",
    "flag": "SG",
    "lat": 33.732,
    "lon": -118.248,
    "sog": 0,
    "cog": 213.2,
    "heading": 70,
    "navStatus": 5,
    "destination": "LONG BEACH",
    "lastSeen": 1700000000000
  }
}

GET /api/v1/vessels/:mmsi/track

Vessel position history. Query params: hours (default 6, max 168 = 7 days; capped server-side).

{
  "mmsi": 565819000,
  "hours": 24,
  "points": [
    { "ts": 1700000000000, "lat": 33.74, "lon": -118.27, "sog": 12.4, "cog": 90 },
    …
  ]
}

GET /api/v1/vessels/search

Search by name (substring), MMSI/IMO/call sign (prefix). Query params: q (≥ 2 chars), limit (1–50).

GET /api/v1/ports

All known ports. v1 ships with 32 high-traffic container ports; growing toward the full UN/LOCODE list.

GET /api/v1/ports/:unlocode

Port detail with currently-nearby vessels. Query param: radiusKm (default 10, max 50).

Webhooks (watchlists)

When a vessel enters or leaves a watched region, we POST a JSON payload to your webhook URL. Verify the x-shipradar-signature header (HMAC-SHA256) against the secret shown when you created the watch.

POST <your-url>
content-type: application/json
x-shipradar-signature: sha256=<hex>
x-shipradar-event: vessel.enter

{
  "id": "<event id>",
  "type": "vessel.enter",
  "watch_id": "<watch id>",
  "mmsi": 565819000,
  "vessel_name": "MAERSK ALGOL",
  "lat": 33.74,
  "lon": -118.27,
  "occurred_at": "2026-01-01T12:00:00Z"
}