vesselapi-python

[!WARNING] This version is no longer maintained. Several endpoints wrapped by 1.x were retired from the VesselAPI service on 10 August 2026 and now return HTTP 410. Please upgrade:

pip install 'vessel-api-python>=2'

2.x removes the retired surface, requires the parameters the API requires, and adds unified search, repeatable filters and satellite position fallback. See the CHANGELOG for migration notes.

Python client for the Vessel Tracking API — maritime vessel tracking, port events, emissions, and navigation data.

Resources: Documentation | API Explorer | Dashboard | Contact Support

Install

pip install vessel-api-python

Requires Python 3.9+.

Quick Start

from vessel_api_python import VesselClient

client = VesselClient(api_key="your-api-key")

# Search for a vessel by name.
result = client.search.vessels(filter_name="Ever Given")
for v in result.vessels or []:
    print(f"{v.name} (IMO {v.imo})")

# Get a port by UN/LOCODE.
port = client.ports.get("NLRTM")
print(port.port.name)

# Auto-paginate through port events.
for event in client.port_events.list_all(pagination_limit=10):
    print(f"{event.event} at {event.timestamp}")

Async

import asyncio
from vessel_api_python import AsyncVesselClient

async def main():
    async with AsyncVesselClient(api_key="your-api-key") as client:
        result = await client.search.vessels(filter_name="Ever Given")
        async for event in client.port_events.list_all(pagination_limit=10):
            print(f"{event.event} at {event.timestamp}")

asyncio.run(main())

Available Services

37 methods total.

Vessel Lookup & Location

# Get vessel details by IMO number (defaults to IMO; pass filter_id_type="mmsi" for MMSI).
vessel = client.vessels.get("9811000")
print(f"{vessel.vessel.name} ({vessel.vessel.vessel_type})")

# Get the vessel's latest AIS position.
pos = client.vessels.position("9811000")
print(f"Position: {pos.vessel_position.latitude}, {pos.vessel_position.longitude}")

# Find all vessels within 10 km of Rotterdam.
nearby = client.location.vessels_radius(latitude=51.9225, longitude=4.47917, radius=10000)
for v in nearby.vessels or []:
    print(f"{v.vessel_name} at {v.latitude}, {v.longitude}")

Error Handling

All methods raise specific exception types on non-2xx responses:

from vessel_api_python import VesselAPIError

try:
    client.ports.get("ZZZZZ")
except VesselAPIError as err:
    if err.is_not_found:
        print("Port not found")
    elif err.is_rate_limited:
        print("Rate limited — back off")
    elif err.is_auth_error:
        print("Check API key")
    print(err.status_code, err.message)

Auto-Pagination

Every list endpoint has an all_* / list_all variant returning an iterator:

# Sync
for vessel in client.search.all_vessels(filter_vessel_type="Tanker"):
    print(vessel.name)

# Async
async for vessel in client.search.all_vessels(filter_vessel_type="Tanker"):
    print(vessel.name)

# Collect a bounded set at once
vessels = client.search.all_vessels(filter_vessel_type="Tanker", pagination_limit=50).collect()

Configuration

client = VesselClient(
    api_key="your-api-key",
    base_url="https://custom-endpoint.example.com/v1",
    timeout=60.0,
    max_retries=5,  # default: 3
    user_agent="my-app/1.0",
)

Retries use exponential backoff with jitter on 429 and 5xx responses. The Retry-After header is respected.

Documentation

• API Documentation — endpoint guides, request/response schemas, and usage examples
• API Explorer — interactive API reference
• Dashboard — manage API keys and monitor usage

Contributing & Support

Found a bug, have a feature request, or need help? You're welcome to open an issue. For API-level bugs and feature requests, please use the main VesselAPI repository.

For security vulnerabilities, do not open a public issue — email security@vesselapi.com instead. See SECURITY.md.

License

MIT