vessel-api-python 1.0.0__tar.gz → 1.2.0__tar.gz

{vessel_api_python-1.0.0 → vessel_api_python-1.2.0}/Makefile

@@ -6,7 +6,7 @@ lint:
 	ruff check src/ tests/
 
 typecheck:
-	mypy src/vesselapi/
+	mypy src/vessel_api_python/
 
 test:
 	pytest -v tests/

{vessel_api_python-1.0.0 → vessel_api_python-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vessel-api-python
-Version: 1.0.0
+Version: 1.2.0
 Summary: Python client for the Vessel Tracking API — maritime vessel tracking, port events, emissions, and navigation data.
 Project-URL: Documentation, https://vesselapi.com/docs
 Project-URL: Repository, https://github.com/vessel-api/vesselapi-python
@@ -10,7 +10,7 @@ Author-email: Vessel API <support@vesselapi.com>
 License-Expression: MIT
 License-File: LICENSE
 Keywords: ais,maritime,sdk,tracking,vessel,vesselapi
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
@@ -34,7 +34,7 @@ Description-Content-Type: text/markdown
 
 # vesselapi-python
 
-[![CI](https://github.com/vessel-api/vesselapi-python/actions/workflows/ci.yml/badge.svg)](https://github.com/vessel-api/vesselapi-python/actions/workflows/ci.yml)
+[![CI](https://github.com/vessel-api/vesselapi-python/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/vessel-api/vesselapi-python/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/vessel-api-python.svg)](https://pypi.org/project/vessel-api-python/)
 [![Python](https://img.shields.io/pypi/pyversions/vessel-api-python.svg)](https://pypi.org/project/vessel-api-python/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -101,6 +101,23 @@ asyncio.run(main())
 
 **37 methods total.**
 
+## Vessel Lookup & Location
+
+```python
+# 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:
@@ -126,15 +143,15 @@ Every list endpoint has an `all_*` / `list_all` variant returning an iterator:
 
 ```python
 # Sync
-for vessel in client.search.all_vessels(filter_name="tanker"):
+for vessel in client.search.all_vessels(filter_vessel_type="Tanker"):
     print(vessel.name)
 
 # Async
-async for vessel in client.search.all_vessels(filter_name="tanker"):
+async for vessel in client.search.all_vessels(filter_vessel_type="Tanker"):
     print(vessel.name)
 
-# Collect all at once
-vessels = client.search.all_vessels(filter_name="tanker").collect()
+# Collect a bounded set at once
+vessels = client.search.all_vessels(filter_vessel_type="Tanker", pagination_limit=50).collect()
 ```
 
 ## Configuration

{vessel_api_python-1.0.0 → vessel_api_python-1.2.0}/README.md

@@ -1,6 +1,6 @@
 # vesselapi-python
 
-[![CI](https://github.com/vessel-api/vesselapi-python/actions/workflows/ci.yml/badge.svg)](https://github.com/vessel-api/vesselapi-python/actions/workflows/ci.yml)
+[![CI](https://github.com/vessel-api/vesselapi-python/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/vessel-api/vesselapi-python/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/vessel-api-python.svg)](https://pypi.org/project/vessel-api-python/)
 [![Python](https://img.shields.io/pypi/pyversions/vessel-api-python.svg)](https://pypi.org/project/vessel-api-python/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -67,6 +67,23 @@ asyncio.run(main())
 
 **37 methods total.**
 
+## Vessel Lookup & Location
+
+```python
+# 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:
@@ -92,15 +109,15 @@ Every list endpoint has an `all_*` / `list_all` variant returning an iterator:
 
 ```python
 # Sync
-for vessel in client.search.all_vessels(filter_name="tanker"):
+for vessel in client.search.all_vessels(filter_vessel_type="Tanker"):
     print(vessel.name)
 
 # Async
-async for vessel in client.search.all_vessels(filter_name="tanker"):
+async for vessel in client.search.all_vessels(filter_vessel_type="Tanker"):
     print(vessel.name)
 
-# Collect all at once
-vessels = client.search.all_vessels(filter_name="tanker").collect()
+# Collect a bounded set at once
+vessels = client.search.all_vessels(filter_vessel_type="Tanker", pagination_limit=50).collect()
 ```
 
 ## Configuration

{vessel_api_python-1.0.0 → vessel_api_python-1.2.0}/examples/async_basic.py

@@ -4,7 +4,7 @@ import asyncio
 import os
 import sys
 
-from vesselapi import AsyncVesselClient, VesselAPIError
+from vessel_api_python import AsyncVesselClient, VesselAPIError
 
 
 async def main() -> None:
@@ -26,6 +26,24 @@ async def main() -> None:
         if port.port:
             print(f"Port: {port.port.name} ({port.port.unlo_code})")
 
+        # Get vessel details by IMO number (defaults to IMO; pass filter_id_type="mmsi" for MMSI).
+        print("\n--- Vessel by IMO ---")
+        vessel = await client.vessels.get("9811000")
+        if vessel.vessel:
+            print(f"Vessel: {vessel.vessel.name} (Type: {vessel.vessel.vessel_type})")
+
+        # Get the vessel's latest AIS position.
+        print("\n--- Vessel Position ---")
+        pos = await client.vessels.position("9811000")
+        if pos.vessel_position:
+            print(f"Position: {pos.vessel_position.latitude}, {pos.vessel_position.longitude}")
+
+        # Find vessels within 10 km of Rotterdam.
+        print("\n--- Vessels Near Rotterdam ---")
+        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} (IMO: {v.imo}) at {v.latitude}, {v.longitude}")
+
         # Error handling.
         print("\n--- Error Handling ---")
         try:

{vessel_api_python-1.0.0 → vessel_api_python-1.2.0}/examples/basic.py

@@ -3,7 +3,7 @@
 import os
 import sys
 
-from vesselapi import VesselClient, VesselAPIError
+from vessel_api_python import VesselClient, VesselAPIError
 
 
 def main() -> None:
@@ -38,6 +38,25 @@ def main() -> None:
     if port.port:
         print(f"Port: {port.port.name} ({port.port.unlo_code})")
 
+    # Get vessel details by IMO number (defaults to IMO; pass filter_id_type="mmsi" for MMSI).
+    print("\n--- Vessel by IMO ---")
+    vessel = client.vessels.get("9811000")
+    if vessel.vessel:
+        print(f"Vessel: {vessel.vessel.name} (Type: {vessel.vessel.vessel_type})")
+
+    # Get the vessel's latest AIS position.
+    print("\n--- Vessel Position ---")
+    pos = client.vessels.position("9811000")
+    if pos.vessel_position:
+        print(f"Position: {pos.vessel_position.latitude}, {pos.vessel_position.longitude}")
+        print(f"Speed: {pos.vessel_position.sog} knots, Heading: {pos.vessel_position.heading}")
+
+    # Find vessels within 10 km of Rotterdam.
+    print("\n--- Vessels Near 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} (IMO: {v.imo}) at {v.latitude}, {v.longitude}")
+
     # Handle a not-found port gracefully.
     print("\n--- Not Found Handling ---")
     try:

{vessel_api_python-1.0.0 → vessel_api_python-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vessel-api-python"
-version = "1.0.0"
+version = "1.2.0"
 description = "Python client for the Vessel Tracking API — maritime vessel tracking, port events, emissions, and navigation data."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -14,7 +14,7 @@ authors = [
 ]
 keywords = ["vesselapi", "maritime", "vessel", "tracking", "ais", "sdk"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",

{vessel_api_python-1.0.0 → vessel_api_python-1.2.0}/src/vessel_api_python/__init__.py

@@ -65,11 +65,13 @@ from ._models import (
     PortEvent,
     PortEventResponse,
     PortEventsResponse,
+    PortInboundResponse,
     PortReference,
     PortResponse,
     PortsWithinLocationResponse,
     RadioBeacon,
     RadioBeaconsWithinLocationResponse,
+    ResolutionMeta,
     TypesInspectionDetailResponse,
     TypesInspectionsResponse,
     TypesOwnershipResponse,
@@ -111,6 +113,7 @@ __all__ = [
     "VesselReference",
     "VesselFormerName",
     "BroadcastStation",
+    "ResolutionMeta",
     # Models — Classification sub-models
     "ClassificationCertificate",
     "ClassificationCondition",
@@ -159,6 +162,7 @@ __all__ = [
     "PortEvent",
     "PortEventResponse",
     "PortEventsResponse",
+    "PortInboundResponse",
     # Models — Search
     "FindVesselsResponse",
     "FindPortsResponse",

{vessel_api_python-1.0.0 → vessel_api_python-1.2.0}/src/vessel_api_python/_constants.py

@@ -1,6 +1,6 @@
 """Constants for the Vessel API Python SDK."""
 
-VERSION = "1.0.0"
+VERSION = "1.1.0"
 DEFAULT_BASE_URL = "https://api.vesselapi.com/v1"
 DEFAULT_USER_AGENT = f"vesselapi-python/{VERSION}"
 DEFAULT_MAX_RETRIES = 3

{vessel_api_python-1.0.0 → vessel_api_python-1.2.0}/src/vessel_api_python/_models.py

@@ -224,6 +224,18 @@ class ClassificationYard(_Base):
     keel_date: str | None = Field(default=None, alias="keelDate")
 
 
+# ---------------------------------------------------------------------------
+# Resolution metadata
+# ---------------------------------------------------------------------------
+
+
+class ResolutionMeta(_Base):
+    """Metadata about ID resolution fallback. Present when the API resolved using a different ID type."""
+    requested_id_type: str | None = Field(default=None, alias="requestedIdType")
+    resolved_id_type: str | None = Field(default=None, alias="resolvedIdType")
+    resolved_id: int | None = Field(default=None, alias="resolvedId")
+
+
 # ---------------------------------------------------------------------------
 # Vessel models
 # ---------------------------------------------------------------------------
@@ -264,6 +276,7 @@ class VesselResponse(_Base):
     """Response for a single vessel lookup."""
 
     vessel: Vessel | None = None
+    meta: ResolutionMeta | None = Field(default=None, alias="_meta")
 
 
 class VesselPosition(_Base):
@@ -290,6 +303,7 @@ class VesselPositionResponse(_Base):
     vessel_position: VesselPosition | None = Field(
         default=None, alias="vesselPosition"
     )
+    meta: ResolutionMeta | None = Field(default=None, alias="_meta")
 
 
 class VesselPositionsResponse(_Base):
@@ -299,6 +313,7 @@ class VesselPositionsResponse(_Base):
         default=None, alias="vesselPositions"
     )
     next_token: str | None = Field(default=None, alias="nextToken")
+    meta: ResolutionMeta | None = Field(default=None, alias="_meta")
 
 
 # ---------------------------------------------------------------------------
@@ -352,6 +367,7 @@ class MarineCasualtiesResponse(_Base):
 
     casualties: list[MarineCasualty] | None = None
     next_token: str | None = Field(default=None, alias="nextToken")
+    meta: ResolutionMeta | None = Field(default=None, alias="_meta")
 
 
 class ClassificationVessel(_Base):
@@ -379,6 +395,7 @@ class ClassificationResponse(_Base):
     """Response for vessel classification."""
 
     classification: ClassificationVessel | None = None
+    meta: ResolutionMeta | None = Field(default=None, alias="_meta")
 
 
 class VesselEmission(_Base):
@@ -432,12 +449,14 @@ class VesselEmissionsResponse(_Base):
 
     emissions: list[VesselEmission] | None = None
     next_token: str | None = Field(default=None, alias="nextToken")
+    meta: ResolutionMeta | None = Field(default=None, alias="_meta")
 
 
 class VesselETA(_Base):
     """Vessel Estimated Time of Arrival information."""
 
     destination: str | None = None
+    destination_port: str | None = None
     draught: float | None = None
     eta: str | None = None
     imo: int | None = None
@@ -450,6 +469,13 @@ class VesselETAResponse(_Base):
     """Response for vessel ETA."""
 
     vessel_eta: VesselETA | None = Field(default=None, alias="vesselEta")
+    meta: ResolutionMeta | None = Field(default=None, alias="_meta")
+
+
+class PortInboundResponse(_Base):
+    """Response containing vessels heading to a port."""
+    vessel_etas: list[VesselETA] | None = Field(default=None, alias="vesselETAs")
+    next_token: str | None = Field(default=None, alias="nextToken")
 
 
 # ---------------------------------------------------------------------------
@@ -652,12 +678,14 @@ class PortEventsResponse(_Base):
         default=None, alias="portEvents"
     )
     next_token: str | None = Field(default=None, alias="nextToken")
+    meta: ResolutionMeta | None = Field(default=None, alias="_meta")
 
 
 class PortEventResponse(_Base):
     """Response for a single port event (e.g. last by vessel)."""
 
     port_event: PortEvent | None = Field(default=None, alias="portEvent")
+    meta: ResolutionMeta | None = Field(default=None, alias="_meta")
 
 
 # ---------------------------------------------------------------------------