OFFICIAL SDK

VesselAPI Python SDK

vessel-api-python is the official Python client for the VesselAPI REST API: vessel particulars and positions, port events, ports, emissions and casualty records. It has a sync and an async client, typed errors, retries with backoff, and an iterator for every list endpoint.

Get a free API key vessel-api-python on PyPI

Methods, one per endpoint

Auto-paginating iterators

3.9+

Python, sync and async

MIT

Source on GitHub

Installation and authentication

pip install vessel-api-python

The package depends on httpx and pydantic. Python 3.9 and later are supported.

The client takes the API key as a keyword argument. Keys are created in the dashboard and sent as a bearer token on every request. AsyncVesselClient has the same methods and is used as an async context manager.

import os
from vessel_api_python import VesselClient, AsyncVesselClient

client = VesselClient(api_key=os.environ["VESSELAPI_API_KEY"])

# Optional settings and their defaults
client = VesselClient(
    api_key=os.environ["VESSELAPI_API_KEY"],
    timeout=30.0,
    max_retries=3,
    user_agent="my-app/1.0",
)

3 examples

1. Look up a vessel and its latest position

Vessel endpoints take an IMO number by default; pass the MMSI id type to look up by MMSI. A vessel that exists may have no stored position, and the API answers that with 404.

# Particulars by IMO number (the default id type)
vessel = client.vessels.get("9811000").vessel
print(vessel.name, vessel.vessel_type, vessel.country)

# Latest stored position by MMSI
pos = client.vessels.position("232003239", filter_id_type="mmsi").vessel_position
print(pos.latitude, pos.longitude, pos.sog, pos.timestamp)

2. Vessels within 10 km of a point

Area queries return vessels with a position in the last 2 hours by default, and at most 4 hours. The radius is in metres, up to 100 km.

nearby = client.location.vessels_radius(
    latitude=51.9225, longitude=4.47917, radius=10000
)
for v in nearby.vessels or []:
    print(v.vessel_name, v.latitude, v.longitude, v.nav_status)

3. Page through port events

Every list method has an iterator variant that follows nextToken for you. Each page is one API call against your quota, so the page size sets how many calls a full walk costs.

# Every port event in the last 24 hours, 50 per page
from datetime import datetime, timedelta, timezone

since = datetime.now(timezone.utc) - timedelta(hours=24)
for event in client.port_events.list_all(
    filter_time_from=since.isoformat(), pagination_limit=50
):
    print(event.event, event.port_name, event.vessel_name, event.timestamp)

# Take a fixed number: stop the iterator yourself
from itertools import islice
first_100 = list(islice(client.search.all_vessels(filter_vessel_type="Tanker"), 100))

Errors and retries

Non-2xx responses raise VesselAPIError with the status code, the API's error code and the message. 429 and 5xx responses are retried with exponential backoff, and the Retry-After header is honoured.

from vessel_api_python import VesselAPIError

try:
    client.ports.get("ZZZZZ")
except VesselAPIError as err:
    if err.is_not_found:
        print("no such port")
    elif err.is_rate_limited:
        print("quota or rate limit reached")
    elif err.is_auth_error:
        print("check the API key")
    print(err.status_code, err.message)

Services

Service	Covers	Guide
vessels	Vessel particulars, latest and batch positions, ETA, emissions and casualty records	Vessel tracking
ports	Port lookup by UN/LOCODE and inbound vessels	Ports and navigation
port_events	Arrivals and departures by port, by vessel or across all covered ports	Port events
emissions	EU MRV emissions reports by reporting year	Emissions and casualty records
search	Search across vessels, ports, lights, radio beacons, DGPS stations and MODUs	Vessel tracking
location	Bounding-box and radius queries for every entity type	Ports and navigation

The Notifications API (webhooks and WebSocket) is not part of the SDK; the notifications guide shows the plain HTTP calls. Request and response schemas for every endpoint are in the API reference, and the package is on PyPI with its source on GitHub. For an AI assistant, the MCP server exposes the same endpoints as tools.

Start with the free tier

150 calls a month, every endpoint, no card. Paid tiers raise the quota.

Get a free API key View pricing