### Install vessel-api-python

Source: https://github.com/vessel-api/vesselapi-python/blob/master/README.md

Install the library using pip. Requires Python 3.9+.

```bash
pip install vessel-api-python
```

--------------------------------

### Async Quick Start with AsyncVesselClient

Source: https://github.com/vessel-api/vesselapi-python/blob/master/README.md

Initialize the asynchronous client and perform searches, demonstrating async iteration for port events.

```python
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())
```

--------------------------------

### Quick Start with VesselClient

Source: https://github.com/vessel-api/vesselapi-python/blob/master/README.md

Initialize the synchronous client and perform basic searches for vessels and ports, and paginate through port events.

```python
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}")
```

--------------------------------

### Get Port Events for a Specific Port

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Retrieves a list of events for a particular port, with support for pagination.

```python
rotterdam_events = client.port_events.by_port("NLRTM", pagination_limit=20)
for event in rotterdam_events.port_events or []:
    print(f"{event.vessel.name} - {event.event} at {event.timestamp}")
```

--------------------------------

### Get Vessels Heading to a Port

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Retrieves a list of vessels that are heading to a specific port within a given ETA range.

```python
inbound = client.ports.inbound(
    "NLRTM",
    eta_from="2024-01-01T00:00:00Z",
    eta_to="2024-01-31T23:59:59Z"
)
for vessel in inbound.vessel_etas or []:
    print(f"{vessel.vessel_name} ETA: {vessel.eta}")
```

--------------------------------

### Get Port Information by UN/LOCODE

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Retrieves detailed information about a specific port using its UN/LOCODE, including facilities, dimensions, and services.

```python
port = client.ports.get("NLRTM")  # Rotterdam
p = port.port
print(f"Name: {p.name}")
print(f"Country: {p.country.name} ({p.country.code})")
print(f"Latitude: {p.latitude}, Longitude: {p.longitude}")
print(f"Harbor Size: {p.harbor_size}")
print(f"Harbor Type: {p.harbor_type}")
print(f"Max Draft: {p.max_vessel_draft} {p.max_vessel_draft_unit}")
print(f"Pilotage: {'Required' if p.pilotage_compulsory else 'Optional'}")
print(f"Tugs Available: {p.tugs_available}")
print(f"Fuel Supply: {p.supply_fuel}")
```

--------------------------------

### Get Last Port Event for a Vessel

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Retrieves the most recent port event for a given vessel.

```python
last_event = client.port_events.last_by_vessel("9811000")
print(f"Last event: {last_event.port_event.event} at {last_event.port_event.port.name}")
```

--------------------------------

### Get Vessel ETA and Inspections

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Retrieves the estimated time of arrival (ETA) and port state control inspection records for a given vessel.

```python
eta = client.vessels.eta("9811000")
print(f"Destination: {eta.vessel_eta.destination}")
print(f"Destination Port: {eta.vessel_eta.destination_port}")
print(f"ETA: {eta.vessel_eta.eta}")
print(f"Draught: {eta.vessel_eta.draught}m")
```

```python
inspections = client.vessels.inspections("9811000")
print(f"Total Inspections: {inspections.inspection_count}")
for insp in inspections.inspections or []:
    print(f"Date: {insp.inspection_date}, Port: {insp.port}")
    print(f"Deficiencies: {insp.deficiencies}, Detained: {insp.detained}")
```

```python
detail = client.vessels.inspection_detail("9811000", "inspection-detail-id")
for deficiency in detail.inspection_detail.deficiencies or []:
    print(f"Deficiency: {deficiency.deficiency}, Count: {deficiency.count}")
```

--------------------------------

### Get Vessel Ownership and Casualties

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Retrieves ownership information and marine casualty records for a specified vessel.

```python
ownership = client.vessels.ownership("9811000")
own = ownership.ownership
print(f"Registered Owner: {own.registered_owner}")
print(f"Owner Address: {own.registered_owner_address}")
print(f"Ship Manager: {own.ship_manager}")
print(f"DOC Company: {own.doc_company}")
```

```python
casualties = client.vessels.casualties("9811000")
for cas in casualties.casualties or []:
    print(f"Date: {cas.date_of_occurrence}")
    print(f"Severity: {cas.occurrence_severity}")
    print(f"Event Type: {cas.event_type}")
    print(f"Lives Lost: {cas.lives_lost_total}")
```

--------------------------------

### Get Vessel Emissions Data

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Retrieve emissions data for a specific vessel, including CO2 totals and fuel consumption. Supports pagination and auto-pagination for listing all emissions.

```python
emissions = client.vessels.emissions("9811000", pagination_limit=10)
for e in emissions.emissions or []:
    print(f"Period: {e.reporting_period}")
    print(f"CO2 Total: {e.co2_emissions_total} tonnes")
    print(f"Fuel Consumption: {e.fuel_consumption_total} tonnes")
    print(f"CO2 per Distance: {e.co2_per_distance}")
```

```python
all_emissions = client.emissions.list(filter_period=2023, pagination_limit=100)
for e in all_emissions.emissions or []:
    print(f"{e.name}: {e.co2_emissions_total} tonnes CO2")
```

```python
for emission in client.emissions.list_all(filter_period=2023):
    print(f"{emission.name}: {emission.co2_emissions_total} tonnes")
```

--------------------------------

### GET /vessels/{id}

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Retrieve detailed vessel information including name, type, dimensions, ownership, and classification data using IMO number or MMSI.

```APIDOC
## GET /vessels/{id}

### Description
Retrieve detailed vessel information using an IMO number (default) or MMSI.

### Method
GET

### Endpoint
/vessels/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The IMO number or MMSI of the vessel.

#### Query Parameters
- **filter_id_type** (string) - Optional - The type of ID provided (e.g., 'imo' or 'mmsi').

### Response
#### Success Response (200)
- **vessel** (object) - Contains vessel details including name, type, country, gross_tonnage, year_built, and owner_name.
```

--------------------------------

### GET /vessels/{id}/position

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Get real-time AIS position data for a specific vessel including coordinates, speed, heading, course, and navigation status.

```APIDOC
## GET /vessels/{id}/position

### Description
Get real-time AIS position data for a single vessel.

### Method
GET

### Endpoint
/vessels/{id}/position

### Parameters
#### Path Parameters
- **id** (string) - Required - The IMO number of the vessel.

### Response
#### Success Response (200)
- **vessel_position** (object) - Contains latitude, longitude, sog (speed), heading, cog (course), and timestamp.
```

--------------------------------

### Get Port Events for a Specific Vessel

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Retrieves a list of port events for a specific vessel, with filtering by event type and sort order.

```python
vessel_events = client.port_events.by_vessel(
    "9811000",
    filter_event_type="departure",
    filter_sort_order="desc"
)
for event in vessel_events.port_events or []:
    print(f"Departed {event.port.name} at {event.timestamp}")
```

--------------------------------

### GET /vessels/{id}/classification

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Retrieve comprehensive vessel classification information including certificates, surveys, dimensions, and class notations.

```APIDOC
## GET /vessels/{id}/classification

### Description
Retrieve comprehensive vessel classification information from classification societies.

### Method
GET

### Endpoint
/vessels/{id}/classification

### Parameters
#### Path Parameters
- **id** (string) - Required - The IMO number of the vessel.

### Response
#### Success Response (200)
- **classification** (object) - Contains identification, dimensions, classification details, and certificates.
```

--------------------------------

### Initialize VesselClient

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Configure the synchronous or asynchronous client with an API key and optional settings like base URL and timeouts. Use context managers to ensure proper resource cleanup.

```python
from vessel_api_python import VesselClient, AsyncVesselClient

# Basic synchronous client
client = VesselClient(api_key="your-api-key")

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

# Use as context manager for automatic cleanup
with VesselClient(api_key="your-api-key") as client:
    result = client.search.vessels(filter_name="Ever Given")
    for v in result.vessels or []:
        print(f"{v.name} (IMO {v.imo})")

# Async client with context manager
async with AsyncVesselClient(api_key="your-api-key") as client:
    result = await client.search.vessels(filter_name="Ever Given")
    for v in result.vessels or []:
        print(f"{v.name} (IMO {v.imo})")
```

--------------------------------

### Configure VesselClient

Source: https://github.com/vessel-api/vesselapi-python/blob/master/README.md

Customize client behavior by setting the base URL, timeout, maximum retries, and user agent.

```python
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",
)
```

--------------------------------

### Synchronous Auto-Pagination

Source: https://github.com/vessel-api/vesselapi-python/blob/master/README.md

Iterate over all results from a list endpoint using the `all_*` variant, useful for fetching large datasets.

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

--------------------------------

### Auto-paginate Port Events

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Use list_all to automatically iterate through all events matching the specified filters.

```python
for event in client.port_events.list_all(filter_country="NL", pagination_limit=100):
    print(f"{event.vessel.name}: {event.event}")
```

--------------------------------

### List Port Events with Filters

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Lists port events (arrivals, departures) with support for filtering by country, event type, and time range. Includes pagination.

```python
events = client.port_events.list(
    filter_country="NL",
    filter_event_type="arrival",
    time_from="2024-01-01T00:00:00Z",
    time_to="2024-01-31T23:59:59Z",
    pagination_limit=50
)
for event in events.port_events or []:
    print(f"{event.event}: {event.vessel.name} at {event.port.name}")
    print(f"Timestamp: {event.timestamp}")
```

--------------------------------

### Asynchronous Auto-Pagination

Source: https://github.com/vessel-api/vesselapi-python/blob/master/README.md

Iterate over all results from a list endpoint asynchronously using the `all_*` variant.

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

--------------------------------

### Query Location Data with Python

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Retrieve various maritime entities like ports, DGPS stations, light aids, and MODUs using radius or bounding box filters.

```python
ports = client.location.ports_radius(
    latitude=51.9225,
    longitude=4.47917,
    radius=50000
)
for p in ports.ports or []:
    print(f"{p.name} ({p.unlo_code}) at {p.latitude}, {p.longitude}")
```

```python
ports = client.location.ports_bounding_box(
    lat_min=50.0,
    lat_max=53.0,
    lon_min=3.0,
    lon_max=7.0
)
for p in ports.ports or []:
    print(f"{p.name}, {p.country.name}")
```

```python
dgps = client.location.dgps_radius(latitude=51.9, longitude=4.5, radius=100000)
for station in dgps.dgps_stations or []:
    print(f"DGPS: {station.name}")
```

```python
lights = client.location.light_aids_bounding_box(
    lat_min=51.0, lat_max=52.5, lon_min=3.0, lon_max=5.0
)
for light in lights.light_aids or []:
    print(f"Light: {light.name}")
```

```python
modus = client.location.modus_radius(latitude=28.0, longitude=-89.0, radius=200000)
for modu in modus.modus or []:
    print(f"MODU: {modu.name} - Status: {modu.rig_status}")
```

--------------------------------

### Collect Paginated Results

Source: https://github.com/vessel-api/vesselapi-python/blob/master/README.md

Fetch all paginated results and collect them into a list at once, specifying a maximum number of items.

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

--------------------------------

### Search Navigation Aids

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Retrieve information on DGPS stations, light aids, radio beacons, and MODUs.

```python
from vessel_api_python import VesselClient

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

# Search DGPS stations
dgps = client.search.dgps(filter_name="Rotterdam", pagination_limit=10)
for station in dgps.dgps_stations or []:
    print(f"{station.name} - Frequency: {station.frequency}, Range: {station.range}")

# Search light aids
lights = client.search.light_aids(filter_name="North Sea", pagination_limit=10)
for light in lights.light_aids or []:
    print(f"{light.name} - Characteristic: {light.characteristic}")

# Search radio beacons
beacons = client.search.radio_beacons(filter_name="Channel", pagination_limit=10)
for beacon in beacons.radio_beacons or []:
    print(f"{beacon.name} - Frequency: {beacon.frequency}")

# Search MODUs (Mobile Offshore Drilling Units)
modus = client.search.modus(filter_name="Deepwater", pagination_limit=10)
for modu in modus.modus or []:
    print(f"{modu.name} - Status: {modu.rig_status}, Region: {modu.navigation_area}")
```

--------------------------------

### Access Vessel Emissions Data

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Retrieve EU MRV emissions metrics for specific vessels.

```python
from vessel_api_python import VesselClient

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

--------------------------------

### Search Ports

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Query ports based on geographic location, size, or name.

```python
from vessel_api_python import VesselClient

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

# Search ports by country
result = client.search.ports(filter_country="NL", pagination_limit=20)
for p in result.ports or []:
    print(f"{p.name} ({p.unlo_code}) - {p.harbor_size} harbor")

# Search with multiple criteria
result = client.search.ports(
    filter_region="Europe",
    filter_harbor_size="Large",
    filter_port_type="Sea Port",
    pagination_limit=50
)
for p in result.ports or []:
    print(f"{p.name}, {p.country.name} - Type: {p.type}")

# Search by name
result = client.search.ports(filter_name="Rotterdam")
for p in result.ports or []:
    print(f"{p.name} ({p.unlo_code})")

# Auto-paginate through ports
for port in client.search.all_ports(filter_country="US"):
    print(f"{port.name}: {port.harbor_size}")
```

--------------------------------

### Port Events API

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Track vessel arrivals and departures at ports worldwide with filtering and pagination support.

```APIDOC
## List port events with filters

### Description
Retrieves a list of port events (arrivals, departures, etc.) with support for various filters and pagination.

### Method
GET

### Endpoint
`/port_events`

### Parameters
#### Query Parameters
- **filter_country** (string) - Optional - Filters events by country code (e.g., 'NL').
- **filter_event_type** (string) - Optional - Filters events by type (e.g., 'arrival', 'departure').
- **time_from** (string) - Optional - The start of the time range for events (ISO 8601 format).
- **time_to** (string) - Optional - The end of the time range for events (ISO 8601 format).
- **pagination_limit** (integer) - Optional - The maximum number of events to return per page.

### Response
#### Success Response (200)
- **port_events** (array) - A list of port event records.
  - **event** (string) - The type of event (e.g., 'Arrival', 'Departure').
  - **vessel** (object)
    - **name** (string) - The name of the vessel.
  - **port** (object)
    - **name** (string) - The name of the port.
  - **timestamp** (string) - The timestamp of the event (ISO 8601 format).

### Request Example
```python
events = client.port_events.list(filter_country="NL", filter_event_type="arrival", time_from="2024-01-01T00:00:00Z", time_to="2024-01-31T23:59:59Z", pagination_limit=50)
```

### Response Example
```json
{
  "port_events": [
    {
      "event": "Arrival",
      "vessel": {"name": "Cargo Ship A"},
      "port": {"name": "Rotterdam"},
      "timestamp": "2024-01-10T08:00:00Z"
    }
  ]
}
```

## Get events for a specific port

### Description
Retrieves a list of port events for a specific port, with pagination support.

### Method
GET

### Endpoint
`/port_events/by_port/{un_locode}`

### Parameters
#### Path Parameters
- **un_locode** (string) - Required - The UN/LOCODE of the port.
#### Query Parameters
- **pagination_limit** (integer) - Optional - The maximum number of events to return per page.

### Response
#### Success Response (200)
- **port_events** (array) - A list of port event records for the specified port.
  - **vessel** (object)
    - **name** (string) - The name of the vessel.
  - **event** (string) - The type of event.
  - **timestamp** (string) - The timestamp of the event (ISO 8601 format).

### Request Example
```python
rotterdam_events = client.port_events.by_port("NLRTM", pagination_limit=20)
```

### Response Example
```json
{
  "port_events": [
    {
      "vessel": {"name": "Tanker B"},
      "event": "Departure",
      "timestamp": "2024-01-11T15:45:00Z"
    }
  ]
}
```

## Get events for a specific vessel

### Description
Retrieves a list of port events associated with a specific vessel, with filtering and sorting options.

### Method
GET

### Endpoint
`/port_events/by_vessel/{vessel_id}`

### Parameters
#### Path Parameters
- **vessel_id** (string) - Required - The unique identifier for the vessel.
#### Query Parameters
- **filter_event_type** (string) - Optional - Filters events by type (e.g., 'departure').
- **filter_sort_order** (string) - Optional - The order to sort the results ('asc' or 'desc').

### Response
#### Success Response (200)
- **port_events** (array) - A list of port event records for the specified vessel.
  - **port** (object)
    - **name** (string) - The name of the port.
  - **timestamp** (string) - The timestamp of the event (ISO 8601 format).
  - **event** (string) - The type of event.

### Request Example
```python
vessel_events = client.port_events.by_vessel("9811000", filter_event_type="departure", filter_sort_order="desc")
```

### Response Example
```json
{
  "port_events": [
    {
      "port": {"name": "Shanghai"},
      "timestamp": "2024-01-12T20:00:00Z",
      "event": "Departure"
    }
  ]
}
```

## Get last port event for a vessel

### Description
Retrieves the most recent port event recorded for a specific vessel.

### Method
GET

### Endpoint
`/port_events/last_by_vessel/{vessel_id}`

### Parameters
#### Path Parameters
- **vessel_id** (string) - Required - The unique identifier for the vessel.

### Response
#### Success Response (200)
- **port_event** (object) - The last recorded port event for the vessel.
  - **event** (string) - The type of event.
  - **port** (object)
    - **name** (string) - The name of the port.
  - **timestamp** (string) - The timestamp of the event (ISO 8601 format).

### Request Example
```python
last_event = client.port_events.last_by_vessel("9811000")
```

### Response Example
```json
{
  "port_event": {
    "event": "Arrival",
    "port": {"name": "Singapore"},
    "timestamp": "2024-01-13T05:30:00Z"
  }
}
```
```

--------------------------------

### Search Vessels

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Search for vessels by name, owner, or specific technical criteria. Supports standard result sets and auto-pagination.

```python
from vessel_api_python import VesselClient

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

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

# Search with multiple filters
result = client.search.vessels(
    filter_flag="PA",
    filter_vessel_type="Container Ship",
    filter_year_built_min=2015,
    filter_year_built_max=2023,
    filter_class_society="Lloyd's Register",
    pagination_limit=20
)
for v in result.vessels or []:
    print(f"{v.name} - Built: {v.year_built}, Flag: {v.country}")

# Search by owner
result = client.search.vessels(filter_owner="Maersk", pagination_limit=50)
for v in result.vessels or []:
    print(f"{v.name} owned by {v.owner_name}")

# Auto-paginate through all tankers
for vessel in client.search.all_vessels(filter_vessel_type="Tanker"):
    print(f"{vessel.name} (IMO: {vessel.imo})")

# Collect bounded results
tankers = client.search.all_vessels(
    filter_vessel_type="Tanker",
    pagination_limit=100
).collect()
print(f"Found {len(tankers)} tankers")
```

--------------------------------

### Lookup Vessel by IMO or MMSI

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Retrieve detailed vessel metadata using either an IMO number or an MMSI identifier.

```python
from vessel_api_python import VesselClient

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

# Get vessel by IMO number (default)
vessel = client.vessels.get("9811000")
print(f"Name: {vessel.vessel.name}")
print(f"Type: {vessel.vessel.vessel_type}")
print(f"Flag: {vessel.vessel.country}")
print(f"Gross Tonnage: {vessel.vessel.gross_tonnage}")
print(f"Year Built: {vessel.vessel.year_built}")
print(f"Owner: {vessel.vessel.owner_name}")

# Get vessel by MMSI
vessel = client.vessels.get("123456789", filter_id_type="mmsi")
print(f"Vessel: {vessel.vessel.name}")
```

--------------------------------

### Retrieve Vessel Classification Data

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Access technical classification details, including dimensions, certificates, and class notations.

```python
from vessel_api_python import VesselClient

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

# Get vessel classification data
classification = client.vessels.classification("9811000")
cls = classification.classification

# Identification details
print(f"IMO: {cls.identification.imo_number}")
print(f"Flag: {cls.identification.flag_name}")
print(f"Status: {cls.identification.operational_status_string}")

# Dimensions
print(f"Length: {cls.dimensions.length_overall}m")
print(f"Beam: {cls.dimensions.bm}m")
print(f"Deadweight: {cls.dimensions.dwt} tons")

# Classification info
print(f"Class: {cls.classification.main_class}")
print(f"Class Notation: {cls.classification.class_notation_string}")

# Certificates
for cert in cls.certificates or []:
    print(f"Certificate: {cert.certificate}, Expires: {cert.expires}")
```

--------------------------------

### Find Vessels within Radius

Source: https://github.com/vessel-api/vesselapi-python/blob/master/README.md

Query for vessels located within a specified radius (in meters) from a given latitude and longitude.

```python
# 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}")
```

--------------------------------

### Handle API Errors

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Implement robust error handling using specific exception classes to catch authentication, rate limiting, and server-side issues.

```python
from vessel_api_python import (
    VesselClient,
    VesselAPIError,
    VesselAuthError,
    VesselNotFoundError,
    VesselRateLimitError,
    VesselServerError,
)

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

try:
    port = client.ports.get("INVALID")
except VesselNotFoundError as err:
    print(f"Port not found: {err.message}")
except VesselAuthError as err:
    print(f"Authentication failed: {err.message}")
except VesselRateLimitError as err:
    print(f"Rate limited - retry later: {err.message}")
except VesselServerError as err:
    print(f"Server error: {err.message}")
except VesselAPIError as err:
    print(f"API error {err.status_code}: {err.message}")

    # Check error properties
    if err.is_not_found:
        print("Resource not found")
    elif err.is_rate_limited:
        print("Too many requests")
    elif err.is_auth_error:
        print("Check your API key")

    # Access raw response body
    print(f"Raw body: {err.body}")
```

--------------------------------

### Vessel Emissions API

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Retrieve and list emissions data for vessels. Supports filtering by period and pagination.

```APIDOC
## Get emissions for a specific vessel

### Description
Retrieves detailed emissions data for a given vessel, with support for pagination.

### Method
GET

### Endpoint
`/vessels/{vessel_id}/emissions`

### Parameters
#### Path Parameters
- **vessel_id** (string) - Required - The unique identifier for the vessel.
#### Query Parameters
- **pagination_limit** (integer) - Optional - The maximum number of emissions records to return per page.

### Response
#### Success Response (200)
- **emissions** (array) - A list of emission records.
  - **reporting_period** (string) - The period for which the emissions data is reported.
  - **co2_emissions_total** (number) - Total CO2 emissions in tonnes.
  - **fuel_consumption_total** (number) - Total fuel consumption in tonnes.
  - **co2_per_distance** (number) - CO2 emissions per unit of distance.

### Request Example
```python
emissions = client.vessels.emissions("9811000", pagination_limit=10)
```

### Response Example
```json
{
  "emissions": [
    {
      "reporting_period": "2023",
      "co2_emissions_total": 1500.50,
      "fuel_consumption_total": 5000.75,
      "co2_per_distance": 0.15
    }
  ]
}
```

## List all emissions data with pagination

### Description
Lists all available emissions data, with options to filter by reporting period and control pagination.

### Method
GET

### Endpoint
`/emissions`

### Parameters
#### Query Parameters
- **filter_period** (integer) - Optional - Filters emissions data for a specific reporting period.
- **pagination_limit** (integer) - Optional - The maximum number of emissions records to return per page.

### Response
#### Success Response (200)
- **emissions** (array) - A list of emissions records.
  - **name** (string) - The name of the vessel.
  - **co2_emissions_total** (number) - Total CO2 emissions in tonnes.

### Request Example
```python
all_emissions = client.emissions.list(filter_period=2023, pagination_limit=100)
```

### Response Example
```json
{
  "emissions": [
    {
      "name": "Vessel Alpha",
      "co2_emissions_total": 1200.00
    }
  ]
}
```

## Auto-paginate through all emissions

### Description
Retrieves all emissions data by automatically handling pagination.

### Method
GET

### Endpoint
`/emissions` (with auto-pagination)

### Parameters
#### Query Parameters
- **filter_period** (integer) - Optional - Filters emissions data for a specific reporting period.

### Response
#### Success Response (200)
- **emissions** (array) - A list of emissions records.
  - **name** (string) - The name of the vessel.
  - **co2_emissions_total** (number) - Total CO2 emissions in tonnes.

### Request Example
```python
for emission in client.emissions.list_all(filter_period=2023):
    print(f"{emission.name}: {emission.co2_emissions_total} tonnes")
```

### Response Example
```json
{
  "emissions": [
    {
      "name": "Vessel Beta",
      "co2_emissions_total": 1350.75
    }
  ]
}
```
```

--------------------------------

### Vessel ETA and Inspections API

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Provides estimated time of arrival (ETA) and port state control inspection records for vessels.

```APIDOC
## Get vessel ETA

### Description
Retrieves the estimated time of arrival (ETA) details for a specific vessel.

### Method
GET

### Endpoint
`/vessels/{vessel_id}/eta`

### Parameters
#### Path Parameters
- **vessel_id** (string) - Required - The unique identifier for the vessel.

### Response
#### Success Response (200)
- **vessel_eta** (object) - ETA details for the vessel.
  - **destination** (string) - The final destination of the vessel.
  - **destination_port** (string) - The name of the destination port.
  - **eta** (string) - The estimated time of arrival (ISO 8601 format).
  - **draught** (number) - The vessel's draught in meters.

### Request Example
```python
eta = client.vessels.eta("9811000")
```

### Response Example
```json
{
  "vessel_eta": {
    "destination": "New York",
    "destination_port": "Port of New York and New Jersey",
    "eta": "2024-07-20T14:30:00Z",
    "draught": 15.5
  }
}
```

## Get inspection records

### Description
Retrieves a summary of port state control inspection records for a specific vessel.

### Method
GET

### Endpoint
`/vessels/{vessel_id}/inspections`

### Parameters
#### Path Parameters
- **vessel_id** (string) - Required - The unique identifier for the vessel.

### Response
#### Success Response (200)
- **inspection_count** (integer) - The total number of inspections recorded.
- **inspections** (array) - A list of inspection records.
  - **inspection_date** (string) - The date of the inspection (YYYY-MM-DD).
  - **port** (string) - The port where the inspection took place.
  - **deficiencies** (integer) - The number of deficiencies found during the inspection.
  - **detained** (boolean) - Indicates if the vessel was detained after the inspection.

### Request Example
```python
inspections = client.vessels.inspections("9811000")
```

### Response Example
```json
{
  "inspection_count": 5,
  "inspections": [
    {
      "inspection_date": "2023-05-15",
      "port": "Rotterdam",
      "deficiencies": 2,
      "detained": false
    }
  ]
}
```

## Get detailed inspection with deficiencies

### Description
Retrieves detailed information about a specific inspection, including a list of deficiencies.

### Method
GET

### Endpoint
`/vessels/{vessel_id}/inspections/{inspection_detail_id}`

### Parameters
#### Path Parameters
- **vessel_id** (string) - Required - The unique identifier for the vessel.
- **inspection_detail_id** (string) - Required - The unique identifier for the inspection detail.

### Response
#### Success Response (200)
- **inspection_detail** (object) - Detailed inspection information.
  - **deficiencies** (array) - A list of deficiencies found.
    - **deficiency** (string) - Description of the deficiency.
    - **count** (integer) - The number of times this deficiency was noted.

### Request Example
```python
detail = client.vessels.inspection_detail("9811000", "inspection-detail-id")
```

### Response Example
```json
{
  "inspection_detail": {
    "deficiencies": [
      {
        "deficiency": "Fire safety equipment",
        "count": 1
      }
    ]
  }
}
```
```

--------------------------------

### Track Vessel Position

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Fetch real-time AIS position data for individual vessels or batch queries for multiple vessels.

```python
from vessel_api_python import VesselClient

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

# Get latest position for a single vessel
pos = client.vessels.position("9811000")
print(f"Latitude: {pos.vessel_position.latitude}")
print(f"Longitude: {pos.vessel_position.longitude}")
print(f"Speed (SOG): {pos.vessel_position.sog} knots")
print(f"Heading: {pos.vessel_position.heading}°")
print(f"Course (COG): {pos.vessel_position.cog}°")
print(f"Timestamp: {pos.vessel_position.timestamp}")

# Get positions for multiple vessels
positions = client.vessels.positions(
    filter_ids="9811000,9363728",
    filter_id_type="imo",
    pagination_limit=50
)
for vp in positions.vessel_positions or []:
    print(f"{vp.vessel_name}: {vp.latitude}, {vp.longitude}")
```

--------------------------------

### Port Lookup API

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Provides detailed information about ports worldwide, including facilities, dimensions, and services.

```APIDOC
## Get port by UN/LOCODE

### Description
Retrieves detailed information for a specific port using its UN/LOCODE.

### Method
GET

### Endpoint
`/ports/{un_locode}`

### Parameters
#### Path Parameters
- **un_locode** (string) - Required - The UN/LOCODE of the port (e.g., 'NLRTM').

### Response
#### Success Response (200)
- **port** (object) - Detailed port information.
  - **name** (string) - The name of the port.
  - **country** (object)
    - **name** (string) - The name of the country.
    - **code** (string) - The ISO 3166-1 alpha-2 country code.
  - **latitude** (number) - The latitude coordinate of the port.
  - **longitude** (number) - The longitude coordinate of the port.
  - **harbor_size** (string) - The size category of the harbor (e.g., 'Large', 'Medium').
  - **harbor_type** (string) - The type of harbor (e.g., 'Commercial', 'Fishing').
  - **max_vessel_draft** (number) - The maximum vessel draft allowed.
  - **max_vessel_draft_unit** (string) - The unit for the maximum vessel draft (e.g., 'm').
  - **pilotage_compulsory** (boolean) - Indicates if pilotage is compulsory.
  - **tugs_available** (boolean) - Indicates if tug services are available.
  - **supply_fuel** (boolean) - Indicates if fuel bunkering services are available.

### Request Example
```python
port = client.ports.get("NLRTM")
```

### Response Example
```json
{
  "port": {
    "name": "Rotterdam",
    "country": {
      "name": "Netherlands",
      "code": "NL"
    },
    "latitude": 51.9244,
    "longitude": 4.4677,
    "harbor_size": "Large",
    "harbor_type": "Commercial",
    "max_vessel_draft": 25.0,
    "max_vessel_draft_unit": "m",
    "pilotage_compulsory": true,
    "tugs_available": true,
    "supply_fuel": true
  }
}
```

## Get vessels heading to a port

### Description
Retrieves a list of vessels that are expected to arrive at a specific port within a given time range.

### Method
GET

### Endpoint
`/ports/{un_locode}/inbound`

### Parameters
#### Path Parameters
- **un_locode** (string) - Required - The UN/LOCODE of the destination port.
#### Query Parameters
- **eta_from** (string) - Required - The start of the ETA time range (ISO 8601 format).
- **eta_to** (string) - Required - The end of the ETA time range (ISO 8601 format).

### Response
#### Success Response (200)
- **vessel_etas** (array) - A list of vessel ETA records.
  - **vessel_name** (string) - The name of the vessel.
  - **eta** (string) - The estimated time of arrival (ISO 8601 format).

### Request Example
```python
inbound = client.ports.inbound("NLRTM", eta_from="2024-01-01T00:00:00Z", eta_to="2024-01-31T23:59:59Z")
```

### Response Example
```json
{
  "vessel_etas": [
    {
      "vessel_name": "Container Ship X",
      "eta": "2024-01-15T10:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Perform Asynchronous API Operations

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Utilize the AsyncVesselClient for non-blocking requests, supporting async iteration and collection of results.

```python
import asyncio
from vessel_api_python import AsyncVesselClient, VesselAPIError

async def main():
    async with AsyncVesselClient(api_key="your-api-key") as client:
        # Search vessels
        result = await client.search.vessels(filter_name="Ever Given")
        for v in result.vessels or []:
            print(f"Vessel: {v.name} (IMO: {v.imo})")

        # Get port information
        port = await client.ports.get("NLRTM")
        print(f"Port: {port.port.name}")

        # Get vessel position
        pos = await client.vessels.position("9811000")
        print(f"Position: {pos.vessel_position.latitude}, {pos.vessel_position.longitude}")

        # Find nearby vessels
        nearby = await 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
        try:
            await client.ports.get("INVALID")
        except VesselAPIError as err:
            if err.is_not_found:
                print(f"Port not found (status {err.status_code})")

        # Async pagination
        count = 0
        async for event in client.port_events.list_all(pagination_limit=10):
            print(f"Event: {event.event} at {event.timestamp}")
            count += 1
            if count >= 25:
                break

        # Collect async results
        vessels = await client.search.all_vessels(
            filter_vessel_type="Tanker",
            pagination_limit=50
        ).collect()
        print(f"Found {len(vessels)} tankers")

asyncio.run(main())
```

--------------------------------

### Retrieve NAVTEX Maritime Safety Messages

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Fetch and paginate through NAVTEX safety information using time-based filters or the list_all helper.

```python
from vessel_api_python import VesselClient

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

# List NAVTEX messages with time filter
messages = client.navtex.list(
    time_from="2024-01-01T00:00:00Z",
    time_to="2024-01-31T23:59:59Z",
    pagination_limit=20
)
for msg in messages.navtex_messages or []:
    print(f"Label: {msg.label}")
    print(f"Office: {msg.issuing_office}")
    print(f"METAREA: {msg.metarea_name} ({msg.metarea_id})")
    print(f"Timestamp: {msg.timestamp}")
    print(f"Content: {msg.raw_content[:200]}...")
    print("---")

# Auto-paginate through all messages
for msg in client.navtex.list_all(pagination_limit=50):
    print(f"{msg.timestamp}: {msg.label}")
```

--------------------------------

### Auto-Pagination Iterators in Python

Source: https://context7.com/vessel-api/vesselapi-python/llms.txt

Use built-in iterators to fetch large result sets automatically. The collect() method can be used to materialize paginated results into a list.

```python
from vessel_api_python import VesselClient

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

# Iterate through all vessels matching criteria
for vessel in client.search.all_vessels(filter_vessel_type="Tanker"):
    print(f"{vessel.name} (IMO: {vessel.imo})")

# Iterate through all port events
for event in client.port_events.list_all(filter_country="NL"):
    print(f"{event.vessel.name}: {event.event} at {event.port.name}")

# Iterate through emissions data
for emission in client.emissions.list_all(filter_period=2023):
    print(f"{emission.name}: {emission.co2_emissions_total} tonnes CO2")

# Iterate through vessel positions in area
for position in client.location.all_vessels_radius(
    latitude=51.9225,
    longitude=4.47917,
    radius=50000
):
    print(f"{position.vessel_name}: {position.latitude}, {position.longitude}")

# Collect all results into a list
all_ports = client.search.all_ports(filter_country="US").collect()
print(f"Found {len(all_ports)} US ports")

# Limit collection with pagination_limit
first_100 = client.search.all_vessels(
    filter_vessel_type="Container Ship",
    pagination_limit=100
).collect()
```

--------------------------------

### Handle VesselAPI Errors

Source: https://github.com/vessel-api/vesselapi-python/blob/master/README.md

Catch and handle specific exceptions raised by the API, such as not found, rate limiting, or authentication errors.

```python
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)
```