vessel-api-python 1.3.0

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

vesselapi-python

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

Service	Methods	Description
vessels	get, position, casualties, classification, emissions, eta, inspections, inspection_detail, ownership, positions	Vessel details, positions, and records
ports	get	Port lookup by UN/LOCODE
port_events	list, by_port, by_ports, by_vessel, last_by_vessel, by_vessels	Vessel arrival/departure events
emissions	list	EU MRV emissions data
search	vessels, ports, dgps, light_aids, modus, radio_beacons	Full-text search across entity types
location	vessels_bounding_box, vessels_radius, ports_bounding_box, ports_radius, dgps_bounding_box, dgps_radius, light_aids_bounding_box, light_aids_radius, modus_bounding_box, modus_radius, radio_beacons_bounding_box, radio_beacons_radius	Geo queries by bounding box or radius
navtex	list	NAVTEX maritime safety messages

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 [e-mail] instead. See SECURITY.md.

License

MIT