→

Developer reference

Vessels API documentation

18 REST endpoints for AIS tracking, fleet ops, port intelligence, and IMO CII emissions — pick a topic from the sidebar or a category below.

Try it

Live demo on homepage

5 free calls, no signup

Introduction

Ship tracking data, structured as JSON, delivered over REST. One key, one base URL, 18 endpoints — from vessel search to IMO CII emissions scoring. No SDKs, no OAuth, no per-endpoint auth differences.

Base URL

https://vessels-api.com/api/V1

Response envelope

Every response follows the same envelope regardless of HTTP status:

JSON — success 
{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": { ... }
}
JSON — error 
{
  "status": 404,
  "success": false,
  "message": "Vessel not found",
  "data": []
}

Authentication

Pass your API key in the X-API-Key request header on every call. Keys are scoped to your account and carry your rate-limit quota.

Get your API key from the dashboard.

Replace YOUR_API_KEY in the examples below.

cURL 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/vessels/search?query=atlantic"
GET /vessels/track Run in Postman

Live position, speed, and course — plus up to 168h of position history. Optionally include the active route, port call history, predicted ETA, and weather at current position.

Parameters

Parameter Type Required Description
imo string cond. IMO number (imo or mmsi required)
mmsi string cond. MMSI number (imo or mmsi required)
hours integer optional History window in hours (default: 24, max: 168)
include_route boolean optional Include active voyage route (default: true)
include_predicted_eta boolean optional Predicted ETA from internal model (default: false)
include_weather boolean optional Weather at current position (default: false)
cURL 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48"
JSON Response 
{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "vessel": {
      "imo": "9702510",
      "mmsi": "258785000",
      "name": "ATLANTIC STAR"
    },
    "current_position": {
      "latitude": -34.603722,
      "longitude": -58.381592,
      "speed_knots": 15.5,
      "course_degrees": 145,
      "heading_degrees": 143,
      "navigational_status": "Underway using engine",
      "timestamp_utc": "2026-02-09T10:30:00Z",
      "destination": "BRSSZ",
      "eta": "2026-02-11T08:00:00Z"
    },
    "position_history": [
      {
        "latitude": -34.612345,
        "longitude": -58.371234,
        "speed_knots": 14.2,
        "timestamp_utc": "2026-02-09T09:00:00Z"
      }
    ],
    "route": {
      "departure_port": "Buenos Aires",
      "departure_time": "2026-02-08T08:00:00Z",
      "destination_port": "Santos",
      "eta": "2026-02-11T08:00:00Z",
      "distance_nm": 1050,
      "avg_speed_knots": 14.5
    },
    "last_port_visits": [
      {
        "port_id": "ARBUE",
        "port_name": "Buenos Aires",
        "arrival_time": "2026-02-05T12:00:00+00:00",
        "departure_time": "2026-02-08T08:00:00+00:00",
        "duration_hours": 68.0
      }
    ],
    "predicted_eta": null,
    "weather": null
  }
}
GET /vessels/nearby Run in Postman

Returns all vessels whose most recent AIS position falls within a given radius (nautical miles) of a lat/lon point. Useful for port approach detection, collision avoidance data, or traffic density visualisation.

Parameters

Parameter Type Required Description
latitude float required Center latitude
longitude float required Center longitude
radius integer optional Radius in nautical miles (default: 50, max: 200)
limit integer optional Maximum results (default: 50)
cURL 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/vessels/nearby?latitude=-34.60&longitude=-58.38&radius=30"
JSON Response 
{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "center": { "latitude": -34.60, "longitude": -58.38 },
    "radius_nm": 30,
    "total": 12,
    "vessels": [
      {
        "imo": null,
        "mmsi": "258785000",
        "name": null,
        "ship_type": null,
        "position": {
          "latitude": -34.603722,
          "longitude": -58.381592,
          "timestamp_utc": "2026-02-09T10:30:00Z"
        },
        "distance_nm": 5.2,
        "speed_knots": 15.5,
        "course_degrees": 145.0,
        "navigational_status": "Underway using engine"
      }
    ]
  }
}
GET /vessels/analytics Run in Postman

Aggregated voyage statistics for a single vessel, a port, or a fleet of vessels over a configurable time window. Use type to switch between analytical modes.

Parameters

Parameter Type Required Description
type string required vessel | port | fleet
imo string cond. IMO (when type=vessel)
mmsi string cond. MMSI (when type=vessel or fleet)
port_id string cond. Port ID (when type=port), e.g. ARBUE
mmsi_list string cond. Comma-separated MMSIs (when type=fleet)
period string optional 24h | 7d | 30d | 90d (default: 7d)
cURL 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/vessels/analytics?type=vessel&mmsi=258785000&period=7d"
JSON Response 
{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "type": "vessel",
    "mmsi": "258785000",
    "imo": "9702510",
    "name": "ATLANTIC STAR",
    "period": "7d",
    "statistics": {
      "total_distance_nm": 1250.5,
      "avg_speed_knots": 14.2,
      "max_speed_knots": 18.5,
      "port_calls_count": 3,
      "total_time_in_port_hours": 72,
      "ports_visited": [
        "Buenos Aires", "Montevideo", "Santos"
      ]
    }
  }
}
POST /vessels/fleet Run in Postman

Batch-query positions, routes, and summary statistics for a list of vessels in a single request. Ideal for fleet-management dashboards where you need a live snapshot of all owned or tracked vessels.

Request Body (application/json)

Parameter Type Required Description
vessels array required Array of objects with imo and/or mmsi
include_positions boolean optional Include current AIS position (default: true)
include_routes boolean optional Include active voyage route (default: true)
cURL 
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vessels": [
      {"imo": "9702510"},
      {"mmsi": "309374000"}
    ],
    "include_positions": true,
    "include_routes": true
  }' \
  "https://vessels-api.com/api/V1/vessels/fleet"
JSON Response 
{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "fleet": {
      "total_vessels": 2,
      "vessels_at_sea": 2,
      "vessels_in_port": 0
    },
    "vessels": [
      {
        "imo": "9702510",
        "mmsi": "258785000",
        "name": "ATLANTIC STAR",
        "position": {
          "latitude": -34.603722,
          "longitude": -58.381592,
          "speed_knots": 15.5,
          "navigational_status": "Underway using engine",
          "timestamp_utc": "2026-02-09T10:30:00Z"
        },
        "route": {
          "departure_port": "Buenos Aires",
          "destination_port": "Santos",
          "eta": "2026-02-11T08:00:00Z"
        }
      },
      {
        "imo": "9234567",
        "mmsi": "309374000",
        "name": "PACIFIC REEFER",
        "position": {
          "latitude": -23.950834,
          "longitude": -46.333056,
          "speed_knots": 0.0,
          "navigational_status": "Moored",
          "timestamp_utc": "2026-02-09T10:25:00+00:00"
        },
        "route": null
      }
    ],
    "summary": {
      "total_distance_nm": 1050.0,
      "avg_speed_knots": 7.75
    }
  }
}
GET /vessels/green NEW Run in Postman

IMO CII Emissions & Decarbonisation Scoring

Returns estimated CO₂ emissions and an IMO Carbon Intensity Indicator (CII) rating for any vessel over a configurable period. Built for ESG reporting, fleet sustainability dashboards, and regulatory compliance workflows.

Parameters

Parameter Type Required Description
imo string cond. IMO number (imo or mmsi required)
mmsi string cond. MMSI number (imo or mmsi required)
period string optional 24h | 7d | 30d | 1y (default: 30d)
CII Ratings: A (best) → B → C → D → E (worst). Based on IMO MEPC.339(76) methodology using vessel type, distance sailed, and estimated fuel consumption.
cURL 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/vessels/green?mmsi=258785000&period=30d"
JSON Response 
{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "imo": "9702510",
    "mmsi": "258785000",
    "name": "ATLANTIC STAR",
    "period": "30d",
    "distance_nm": 4200,
    "estimated_emissions": {
      "co2_tons": 1850.3,
      "co2_per_nm": 0.44,
      "method": "internal_model_v1"
    },
    "cii": {
      "score": 13.2,
      "rating": "C",
      "year": 2026,
      "regulation_reference": "IMO CII"
    }
  }
}
GET /ports/congestion Run in Postman

Real-time congestion snapshot and historical wait-time statistics for a port. Returns vessels in anchorage vs. at berth, average wait time over the period, and individual vessel wait times.

Parameters

Parameter Type Required Description
port_id string required Port identifier, e.g. ARBUE
period string optional 24h | 3d | 7d (default: 7d)
cURL 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/ports/congestion?port_id=ARBUE&period=7d"
JSON Response 
{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "port_id": "ARBUE",
    "port_name": "Buenos Aires",
    "period": "7d",
    "snapshot": {
      "timestamp_utc": "2026-02-09T10:30:00Z",
      "vessels_in_anchorage": 14,
      "vessels_at_berth": 9
    },
    "statistics": {
      "avg_wait_time_hours_last_7d": 22.5,
      "max_wait_time_hours_last_7d": 64.0,
      "avg_berth_time_hours_last_7d": 22.5,
      "port_calls_count": 135
    },
    "example_vessels": [
      {
        "mmsi": "258785000",
        "name": "ATLANTIC STAR",
        "status": "berth",
        "wait_time_hours": 22.5
      }
    ]
  }
}
GET /ports Run in Postman

Returns the full port catalog with identifiers, coordinates, and country. Use port_id values from this endpoint in other port queries.

Parameters

No parameters required.

cURL 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/ports"
JSON Response 
{
  "current_page": 1,
  "data": [
    {
      "port_id": "ARBUE",
      "name": "Buenos Aires",
      "country": "Argentina",
      "type": "Sea Port",
      "size": "Large"
    },
    {
      "port_id": "BRSSZ",
      "name": "Santos",
      "country": "Brazil",
      "type": "Sea Port",
      "size": "Large"
    }
  ],
  "first_page_url": "",
  "from": 1,
  "last_page": 5,
  "last_page_url": "",
  "next_page_url": "",
  "path": "",
  "per_page": 50,
  "prev_page_url": null,
  "to": 50,
  "total": 248
}
GET /ports/data Run in Postman

Detailed information for a single port including live vessel counts.

Parameters

Parameter Type Required Description
port_id string required Port identifier, e.g. ARBUE
cURL 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/ports/data?port_id=ARBUE"
JSON Response 
{
  "id": 1,
  "port_id": "ARBUE",
  "name": "Buenos Aires",
  "country": "Argentina",
  "type": "Sea Port",
  "size": "Large",
  "created_at": null,
  "updated_at": null
}
GET /port/expected-arrivals Run in Postman

Vessels expected to arrive at the given port within the next period, with ETA and origin port.

Parameters

Parameter Type Required Description
port_id string required Port identifier, e.g. ARBUE
page integer optional Page number
cURL 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/port/expected-arrivals?port_id=ARBUE"
JSON Response 
{
  "success": true,
  "status": 200,
  "port": "Buenos Aires",
  "id": "ARBUE",
  "expected_arrivals": 12,
  "page": 1,
  "expected_arrivals_data": [
    {
      "mmsi": "258785000",
      "name": "ATLANTIC STAR",
      "eta": "2026-02-11T08:00:00Z"
    }
  ]
}
GET /port/activity Run in Postman

Recent arrivals and departures at a port, useful for building port call logs and logistics event feeds.

Parameters

Parameter Type Required Description
port_id string required Port identifier, e.g. ARBUE
page integer optional Page number
cURL 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/port/activity?port_id=ARBUE"
JSON Response 
{
  "success": true,
  "status": 200,
  "port": "Buenos Aires",
  "id": "ARBUE",
  "events": 45,
  "page": 1,
  "event": [
    {
      "mmsi": "258785000",
      "name": "ATLANTIC STAR",
      "event_type": "arrival",
      "time": "2026-02-09T06:00:00Z"
    }
  ]
}

Legacy endpoint

These endpoints use the singular /vessel/ path prefix. They remain stable but the newer /vessels/ endpoints return richer, paginated data.

GET /vessel/info Run in Postman

Returns static vessel particulars (name, flag, dimensions, engine type) for a single vessel identified by IMO.

Parameters

Parameter Type Required Description
imoCode string required 7-digit IMO number
cURL 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/vessel/info?imoCode=9702510"
JSON Response 
{
  "status": 200,
  "success": true,
  "message": "IMO Code 9702510 is valid",
  "data": {
    "imo_number": "9702510",
    "vessel_name": "ATLANTIC STAR",
    "ship_type": "Container Ship",
    "flag": "Panama",
    "gross_tonnage": "50420",
    "summer_deadweight_t": "60200",
    "length_overall_m": "294",
    "beam_m": "32",
    "year_of_built": "2010"
  }
}

Legacy endpoint

These endpoints use the singular /vessel/ path prefix. They remain stable but the newer /vessels/ endpoints return richer, paginated data.

GET /vessel/route Run in Postman

Current or most recent voyage route for a vessel: departure/destination port, ETA, and average speed.

Parameters

Parameter Type Required Description
imoCode string required 7-digit IMO number
cURL 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/vessel/route?imoCode=9702510"
JSON Response 
{
  "status": 200,
  "success": true,
  "message": "IMO Code 9702510 is valid",
  "data": {
    "departure_port": "Buenos Aires",
    "departure_atd": "2026-02-08T08:00:00Z",
    "flag": "Panama",
    "length_beam": "294 / 32",
    "imo_mmsi": "9702510 / 258785000",
    "navigation_status": "Underway using engine",
    "current_draught": "12.5",
    "course_speed": "145° / 14.5 kn",
    "arrival_port": "Santos",
    "arrival_atd": "2026-02-11T08:00:00Z",
    "latest_port_calls": []
  }
}

Legacy endpoint

These endpoints use the singular /vessel/ path prefix. They remain stable but the newer /vessels/ endpoints return richer, paginated data.

GET /vessel/position Run in Postman

Last known AIS position for a vessel identified by IMO. For historical positions use /vessels/track.

Parameters

Parameter Type Required Description
imoCode string required 7-digit IMO number
cURL 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/vessel/position?imoCode=9702510"
JSON Response 
{
  "status": 200,
  "success": true,
  "message": "IMO Code 9702510 is valid",
  "data": {
    "position_received": "2 hours ago",
    "vessel_local_time": "14:32",
    "area": "South Atlantic Ocean",
    "current_port": "At Sea",
    "latitude_longitude": "-34.60350° / -58.38120°",
    "navigational_status": "Underway using engine",
    "speed_course": "14.5 kn / 145°",
    "ais_source": "Satellite AIS"
  }
}

Legacy endpoint

These endpoints use the singular /vessel/ path prefix. They remain stable but the newer /vessels/ endpoints return richer, paginated data.

GET /vessel/mmsi-position Run in Postman

Same as /vessel/position but accepts MMSI instead of IMO.

Parameters

Parameter Type Required Description
mmsiCode string required 9-digit MMSI number
cURL 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/vessel/mmsi-position?mmsiCode=258785000"
JSON Response 
{
  "status": 200,
  "success": true,
  "message": "MMSI Code 258785000 is valid",
  "data": {
    "destination": "Santos",
    "reported_eta": "2026-02-11",
    "speed": "14.5 kn / 145°",
    "heading": "143°",
    "draught": "12.5",
    "position_received": "2 hours ago",
    "latitude_longitude": "-34.60350° / -58.38120°",
    "navigational_status": "Underway using engine"
  }
}

Legacy endpoint

These endpoints use the singular /vessel/ path prefix. They remain stable but the newer /vessels/ endpoints return richer, paginated data.

GET /vessel/live-position Run in Postman

Live AIS position from satellite and terrestrial feeds. Both imo and mmsi are required query parameters. On success, the response is a JSON array with an AIS object per vessel, plus optional VOYAGE and MASTERDATA blocks when extradata is set.

Premium quota endpoint: included in Professional and Business plans with a separate monthly allowance. It does not consume the standard request pool.

Parameters

Parameter Type Required Description
imo integer required IMO number (7 digits)
mmsi integer required MMSI number (9 digits)
sat integer optional Set to 1 to request satellite AIS positions (0 = terrestrial)
interval integer optional Maximum age of returned positions in minutes (1-60)
extradata string optional Additional datasets: voyage, master, or voyage,master
cURL 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/vessel/live-position?imo=9873888&mmsi=356882000"
JSON Response 
[
  {
    "AIS": {
      "MMSI": 356882000,
      "TIMESTAMP": "2026-06-16 16:32:17 UTC",
      "LATITUDE": -26.3431,
      "LONGITUDE": -70.65968,
      "COURSE": 337,
      "SPEED": 0.2,
      "HEADING": 231,
      "NAVSTAT": 1,
      "IMO": 9873888,
      "NAME": "ULTRA FOREST",
      "CALLSIGN": "3FEM6",
      "TYPE": 70,
      "A": 151,
      "B": 28,
      "C": 18,
      "D": 12,
      "DRAUGHT": 7.3,
      "DESTINATION": "CLPAT<=>CLBAR",
      "LOCODE": "",
      "ETA_AIS": "06-06 16:00",
      "ETA": "2026-06-06 16:00:00",
      "SRC": "TER",
      "ZONE": "South America West Coast",
      "ECA": false,
      "DISTANCE_REMAINING": null,
      "ETA_PREDICTED": null
    }
  }
]

Legacy endpoint

These endpoints use the singular /vessel/ path prefix. They remain stable but the newer /vessels/ endpoints return richer, paginated data.

GET /vessel/port Run in Postman

Lists vessels currently in or recently departed from a port, identified by port code.

Parameters

Parameter Type Required Description
port_id string required Port identifier, e.g. ARBUE
page integer optional Page number
cURL 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/vessel/port?port_id=ARBUE"
JSON Response 
{
  "success": true,
  "status": 200,
  "port": "Buenos Aires",
  "id": "ARBUE",
  "vessel_in_port": 23,
  "page": 1,
  "vessels": [
    {
      "mmsi": "258785000",
      "name": "ATLANTIC STAR",
      "vessel_type": "Container Ship",
      "flag": "Panama"
    }
  ]
}

Legacy endpoint

These endpoints use the singular /vessel/ path prefix. They remain stable but the newer /vessels/ endpoints return richer, paginated data.

GET /vessel/port/mmsi Run in Postman

Returns the current or most recent port call for a vessel identified by MMSI.

Parameters

Parameter Type Required Description
mmsi string required MMSI number
cURL 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/vessel/port/mmsi?mmsi=258785000"
JSON Response 
{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "mmsi": "258785000",
    "imo": "9702510",
    "name": "ATLANTIC STAR",
    "current_port": {
      "port_id": "ARBUE",
      "port_name": "Buenos Aires",
      "arrival_time": "2026-02-05T12:00:00Z",
      "status": "at_berth"
    }
  }
}

Error Codes

HTTP success Typical message Cause
200 true OK Request succeeded
400 false Missing required parameter: imo or mmsi Required parameter absent or invalid
401 false Invalid or missing API key X-API-Key header absent or key revoked
404 false Vessel not found No data for the given IMO/MMSI
422 false Validation error: radius exceeds maximum Parameter value out of allowed range
429 false Rate limit exceeded Quota exhausted — retry after the window resets