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"

MCP Server

Vessels API runs a native Model Context Protocol server, so an AI agent (Claude, Cursor, Cline, ...) can search vessels, track positions, check port congestion, and pull emissions data directly in conversation — no custom integration code.

Example: ask Claude "Where is IMO 9873888 right now?" and it calls track-vessel-tool automatically.

Server URL

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

It's authenticated and metered exactly like the REST API — the same X-API-Key or Authorization: Bearer credential, counted against the same quota. There is no browser login/authorize screen to click through — the token you paste in is the credential.

Tools

track-vessel-tool — live AIS position, heading, speed, route and ETA by IMO/MMSI. Maps to GET /vessels/track.
search-vessels-tool — search by name, IMO, MMSI, type, or flag. Maps to GET /vessels/search.
port-congestion-tool — live congestion index and wait times. Maps to GET /ports/congestion.
vessel-emissions-tool — CII rating and emissions data. Maps to GET /vessels/green.

Building an autonomous agent instead of using a chat client? It can mint its own sandbox credential without a human filling out a form — see /auth.md.

cURL — tools/list

curl -X POST https://mcp.vessels-api.com/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Sanity-check your key from a terminal before wiring up a client — a 200 with a tools array means you're good to go.

Connect your AI client

Same server URL and credential everywhere — only the steps to enter them change per app.

Claude Desktop & claude.ai

Go to Settings → Connectors (Team/Enterprise: Customize → Connectors) and click Add custom connector.
Server URL: https://mcp.vessels-api.com/mcp.
Under Authentication, choose No sign-in — there's no OAuth flow to detect.
Open Request headers, add Authorization = Bearer YOUR_API_KEY, mark it Required.
Click Add, then Connect on the connector.

Request-header auth is an Anthropic beta with limited rollout — if your dialog has no Request headers section yet, use Claude Code below instead, which supports it for every account today.

Claude Code (CLI)

One command — works today regardless of the Request-headers rollout:

bash

claude mcp add --transport http vessels-api \
  https://mcp.vessels-api.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Add --scope project to share it via a checked-in .mcp.json instead of your personal user scope.

Cursor

Paste into ~/.cursor/mcp.json (global) or .cursor/mcp.json in a project, then restart Cursor:

mcp.json

{
  "mcpServers": {
    "vessels-api": {
      "url": "https://mcp.vessels-api.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Python example

The server is stateless — no initialize handshake or session id required, a direct tools/call is enough.

track_vessel.py

import httpx
import json

MCP_SERVER_URL = "https://mcp.vessels-api.com/mcp"
API_KEY = "YOUR_API_KEY"

def call_tool(name: str, arguments: dict) -> dict:
    response = httpx.post(
        MCP_SERVER_URL,
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {"name": name, "arguments": arguments},
        },
        timeout=30,
    )
    return response.json()

result = call_tool("track-vessel-tool", {"imo": "9873888"})
print(json.dumps(result, indent=2))

FAQ

Do MCP calls count against my API quota?

Yes — each tool call is one API request, billed and rate-limited exactly like a REST call made with the same key.

Do I need to click through an OAuth login to connect Claude or Cursor?

No. Vessels API doesn't run a browser authorize screen for MCP — paste your X-API-Key as a static Authorization: Bearer header, either in Claude's connector settings or in the client's config file, as shown above.

Can an autonomous agent get a key without a human signing up?

POST /oauth/register followed by POST /oauth/token (RFC 6749 Client Credentials Grant) issues a scoped trial key with no dashboard signup. Full spec at /auth.md.

Which MCP client should I use if my Claude account has no Request headers option?

Claude Code's claude mcp add --header flag works for every account regardless of the Claude Desktop/claude.ai beta rollout. Cursor's mcp.json also supports headers directly, no beta gate.

GET /vessels/search Run in Postman

Find any vessel by name, IMO, or MMSI — with fuzzy matching. Filter by type, flag, DWT, TEU, or build year. Returns paginated results ready to power a search UI.

Parameters

Parameter	Type	Required	Description
query	string	optional	Vessel name (fuzzy — typos tolerated)
imo	string	optional	IMO number
mmsi	string	optional	MMSI number
ship_type	string	optional	e.g. Container Ship, Tanker, Bulk Carrier
flag	string	optional	Flag state, e.g. Panama
min_dwt / max_dwt	integer	optional	Deadweight tonnage range
year_built_from / year_built_to	integer	optional	Construction year range
page	integer	optional	Page number (default: 1)
per_page	integer	optional	Results per page (default: 50, max: 100)

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/vessels/search?query=atlantic&flag=Panama&per_page=20"

JSON Response

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "vessels": [
      {
        "imo": "9702510",
        "mmsi": null,
        "name": "ZJ ATLANTIC",
        "flag": "Liberia",
        "vessel_type": "Bulk Carrier",
        "gross_tonnage": "50420",
        "deadweight_tonnage": "60200",
        "year_built": "2010",
        "length_m": 294.0,
        "width_m": 32.0
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 150,
      "last_page": 8
    }
  }
}

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": "ZJ ATLANTIC"
    },
    "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",
      "age_minutes": 12,
      "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": "84",
        "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. Each hit includes the hull's name, IMO and type when that MMSI is already in the vessel roster, plus the destination and ETA reported with the same AIS fix.

Position freshness matters here. A vessel making 15 knots covers roughly 15 NM per hour, so an older fix may place a ship outside the radius it is reported inside. Every result carries position.age_minutes so you can weigh it. By default only positions from the last 24 hours are considered, which excludes vessels that have stopped reporting; if your use case is time-critical, pass a tighter max_age_minutes.

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)
max_age_minutes	integer	optional	Ignore positions older than this (default: 1440 = 24h, max: 10080 = 7d)

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,
    "max_age_minutes": 1440,
    "total": 12,
    "vessels": [
      {
        "imo": "9702510",
        "mmsi": "258785000",
        "name": "ZJ ATLANTIC",
        "ship_type": "Container Ship",
        "position": {
          "latitude": -34.603722,
          "longitude": -58.381592,
          "timestamp_utc": "2026-02-09T10:30:00Z",
          "age_minutes": 12,
          "destination": "BUENOS AIRES",
          "eta": "2026-02-09T18:00:00+00:00"
        },
        "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. 84
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": "ZJ ATLANTIC",
    "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": "ZJ ATLANTIC",
        "position": {
          "latitude": -34.603722,
          "longitude": -58.381592,
          "speed_knots": 15.5,
          "navigational_status": "Underway using engine",
          "timestamp_utc": "2026-02-09T10:30:00Z",
          "age_minutes": 12
        },
        "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",
          "age_minutes": 17
        },
        "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": "ZJ ATLANTIC",
    "period": "30d",
    "data_coverage": {
      "positions": 412,
      "first_position_utc": "2026-01-10T08:00:00Z",
      "last_position_utc": "2026-02-09T10:30:00Z",
      "last_position_age_minutes": 12
    },
    "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. 84
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=84&period=7d"

JSON Response

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "port_id": "84",
    "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": "ZJ ATLANTIC",
        "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

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "ports": [
      {
        "port_id": "84",
        "name": "Buenos Aires",
        "country": "Argentina",
        "type": "Sea Port",
        "size": "Large"
      },
      {
        "port_id": "97",
        "name": "Santos",
        "country": "Brazil",
        "type": "Sea Port",
        "size": "Large"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total": 7183,
      "last_page": 144
    }
  }
}

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

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/ports/data?port_id=84"

JSON Response

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 1,
    "port_id": "84",
    "name": "Buenos Aires",
    "country": "Argentina",
    "type": "Sea Port",
    "size": "Large",
    "vessel_in_port": 82,
    "expected_arrivals": 3,
    "cloud_coverage": "20%",
    "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. 84
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=84"

JSON Response

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "port": "Buenos Aires",
    "id": "84",
    "expected_arrivals": 12,
    "page": 1,
    "expected_arrivals_data": [
      {
        "mmsi": "258785000",
        "name": "ZJ ATLANTIC",
        "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. 84
page	integer	optional	Page number

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/port/activity?port_id=84"

JSON Response

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "port": "Buenos Aires",
    "id": "84",
    "events": 45,
    "page": 1,
    "event": [
      {
        "mmsi": "258785000",
        "name": "ZJ ATLANTIC",
        "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": "ZJ ATLANTIC",
    "ship_type": "Bulk Carrier",
    "flag": "Liberia",
    "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": "Liberia",
    "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 VesselFinder. Look up by mmsi (the radio you are tracking). imo is optional and is not sent upstream when MMSI is present — VesselFinder resolves by IMO and ignores MMSI, so sending both after a reflag returns the previous radio. Without sat the feed is terrestrial (1 credit). Set sat=1 to request satellite AIS (10 credits); it is never added for you. 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: the monthly allowance is VesselFinder credits, not hits. Terrestrial = 1 credit. sat=1 = 10 credits (Scale 1,500 = 1,500 terrestrial or 150 satellite). It does not consume the standard request pool.

Parameters

Parameter	Type	Required	Description
mmsi	integer	optional	MMSI (9 digits). Prefer this after a reflag — it is the AIS identity the feed queries.
imo	integer	optional	IMO (7 digits). Used only when mmsi is omitted. Ignored for the upstream lookup when mmsi is present.
sat	integer	optional	Omit for terrestrial AIS (1 credit). Set to 1 for satellite (10 credits). Not defaulted.
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?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. 84
page	integer	optional	Page number

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://vessels-api.com/api/V1/vessel/port?port_id=84"

JSON Response

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "port": "Buenos Aires",
    "id": "84",
    "vessel_in_port": 23,
    "page": 1,
    "vessels": [
      {
        "mmsi": "258785000",
        "name": "ZJ ATLANTIC",
        "vessel_type": "Bulk Carrier",
        "flag": "Liberia"
      }
    ]
  }
}

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": "MMSI Code 258785000 is valid",
  "data": {
    "position_received": "5 mins ago",
    "vessel_local_time": null,
    "area": "North Sea",
    "current_port": "Rotterdam",
    "latitude_longitude": "51.9 / 4.5",
    "navigational_status": "Underway using engine",
    "speed_course": "12 Knots, 90°",
    "ais_source": "terrestrial",
    "last_port_calls": [
      {
        "port": "Rotterdam",
        "arrival": "Jul 20, 08:00",
        "departure": "Jul 21, 14:00",
        "time_in_port": "1 day, 6 hours"
      }
    ]
  }
}

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
429	false	Rate limit exceeded	Quota exhausted — retry after the window resets

Vessels API documentation

Vessel Intelligence

Fleet Operations

Port Intelligence

Reference

Introduction

Authentication

MCP Server

Connect your AI client

Claude Desktop & claude.ai

Claude Code (CLI)

Cursor

Python example

FAQ

Error Codes