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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vessel-api-python
-Version: 1.1.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
@@ -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.1.0 → vessel_api_python-1.2.0}/README.md

@@ -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.1.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.1.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.1.0 → vessel_api_python-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vessel-api-python"
-version = "1.1.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"

{vessel_api_python-1.1.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.1.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")
 
 
 # ---------------------------------------------------------------------------

{vessel_api_python-1.1.0 → vessel_api_python-1.2.0}/src/vessel_api_python/_services.py

@@ -36,6 +36,7 @@ from ._models import (
     PortEvent,
     PortEventResponse,
     PortEventsResponse,
+    PortInboundResponse,
     PortResponse,
     PortsWithinLocationResponse,
     RadioBeacon,
@@ -46,6 +47,7 @@ from ._models import (
     Vessel,
     VesselEmission,
     VesselEmissionsResponse,
+    VesselETA,
     VesselETAResponse,
     VesselPosition,
     VesselPositionResponse,
@@ -179,6 +181,22 @@ class PortsService:
         error_from_response(r.status_code, r.content)
         return PortResponse.model_validate(r.json())
 
+    def inbound(self, unlocode: str, *, eta_from: str, eta_to: str, time_from: str | None = None, time_to: str | None = None, pagination_limit: int | None = None, pagination_next_token: str | None = None) -> PortInboundResponse:
+        """Retrieve vessels heading to a port."""
+        r = self._client.get(f"/port/{unlocode}/inbound", params=_strip_none({"filter.etaFrom": eta_from, "filter.etaTo": eta_to, "time.from": time_from, "time.to": time_to, "pagination.limit": pagination_limit, "pagination.nextToken": pagination_next_token}))
+        error_from_response(r.status_code, r.content)
+        return PortInboundResponse.model_validate(r.json())
+
+    def inbound_all(self, unlocode: str, *, eta_from: str, eta_to: str, time_from: str | None = None, time_to: str | None = None, pagination_limit: int | None = None) -> SyncIterator[VesselETA]:
+        """Iterate over all inbound vessels for a port across pages."""
+        token: str | None = None
+        def fetch() -> tuple[list[VesselETA], str | None]:
+            nonlocal token
+            resp = self.inbound(unlocode, eta_from=eta_from, eta_to=eta_to, time_from=time_from, time_to=time_to, pagination_limit=pagination_limit, pagination_next_token=token)
+            token = resp.next_token
+            return resp.vessel_etas or [], token
+        return SyncIterator(fetch)
+
 
 class PortEventsService:
     """Port event endpoints (sync)."""
@@ -743,6 +761,22 @@ class AsyncPortsService:
         error_from_response(r.status_code, r.content)
         return PortResponse.model_validate(r.json())
 
+    async def inbound(self, unlocode: str, *, eta_from: str, eta_to: str, time_from: str | None = None, time_to: str | None = None, pagination_limit: int | None = None, pagination_next_token: str | None = None) -> PortInboundResponse:
+        """Retrieve vessels heading to a port."""
+        r = await self._client.get(f"/port/{unlocode}/inbound", params=_strip_none({"filter.etaFrom": eta_from, "filter.etaTo": eta_to, "time.from": time_from, "time.to": time_to, "pagination.limit": pagination_limit, "pagination.nextToken": pagination_next_token}))
+        error_from_response(r.status_code, r.content)
+        return PortInboundResponse.model_validate(r.json())
+
+    def inbound_all(self, unlocode: str, *, eta_from: str, eta_to: str, time_from: str | None = None, time_to: str | None = None, pagination_limit: int | None = None) -> AsyncIterator[VesselETA]:
+        """Iterate over all inbound vessels for a port across pages."""
+        token: str | None = None
+        async def fetch() -> tuple[list[VesselETA], str | None]:
+            nonlocal token
+            resp = await self.inbound(unlocode, eta_from=eta_from, eta_to=eta_to, time_from=time_from, time_to=time_to, pagination_limit=pagination_limit, pagination_next_token=token)
+            token = resp.next_token
+            return resp.vessel_etas or [], token
+        return AsyncIterator(fetch)
+
 
 class AsyncPortEventsService:
     """Port event endpoints (async)."""

{vessel_api_python-1.1.0 → vessel_api_python-1.2.0}/tests/test_services.py

@@ -62,6 +62,58 @@ class TestPortsService:
             assert result.port.name == "Rotterdam"
             client.close()
 
+    def test_inbound(self) -> None:
+        with respx.mock() as mock:
+            route = mock.get("https://api.vesselapi.com/v1/port/NLRTM/inbound").mock(
+                return_value=httpx.Response(200, json={
+                    "vesselETAs": [
+                        {"imo": 9363728, "vessel_name": "Ever Given", "eta": "2026-03-10T12:00:00Z", "destination_port": "NLRTM"},
+                    ],
+                    "nextToken": None,
+                })
+            )
+            client = VesselClient(api_key="key", max_retries=0)
+            result = client.ports.inbound("NLRTM", eta_from="2026-03-07T00:00:00Z", eta_to="2026-03-14T00:00:00Z")
+            assert result.vessel_etas is not None
+            assert len(result.vessel_etas) == 1
+            assert result.vessel_etas[0].imo == 9363728
+            assert result.vessel_etas[0].vessel_name == "Ever Given"
+            # Verify filter params are sent.
+            url = str(route.calls[0].request.url)
+            assert "filter.etaFrom=2026-03-07" in url
+            assert "filter.etaTo=2026-03-14" in url
+            client.close()
+
+
+class TestResolutionMeta:
+    """Tests for _meta deserialization on response models."""
+
+    def test_meta_on_vessel_response(self) -> None:
+        with respx.mock() as mock:
+            mock.get("https://api.vesselapi.com/v1/vessel/477045900").mock(
+                return_value=httpx.Response(200, json={
+                    "vessel": {"imo": 9363728, "mmsi": 477045900},
+                    "_meta": {"requestedIdType": "imo", "resolvedIdType": "mmsi", "resolvedId": 477045900},
+                })
+            )
+            client = VesselClient(api_key="key", max_retries=0)
+            result = client.vessels.get("477045900", filter_id_type="imo")
+            assert result.meta is not None
+            assert result.meta.requested_id_type == "imo"
+            assert result.meta.resolved_id_type == "mmsi"
+            assert result.meta.resolved_id == 477045900
+            client.close()
+
+    def test_meta_absent_when_no_fallback(self) -> None:
+        with respx.mock() as mock:
+            mock.get("https://api.vesselapi.com/v1/vessel/9363728").mock(
+                return_value=httpx.Response(200, json={"vessel": {"imo": 9363728}})
+            )
+            client = VesselClient(api_key="key", max_retries=0)
+            result = client.vessels.get("9363728")
+            assert result.meta is None
+            client.close()
+
 
 class TestSearchService:
     """Tests for the SearchService."""

{vessel_api_python-1.1.0 → vessel_api_python-1.2.0}/tests/test_smoke.py

@@ -95,7 +95,7 @@ class TestSmoke_Vessels:
 
 
 # ---------------------------------------------------------------------------
-# Ports (1 subtest)
+# Ports (2 subtests)
 # ---------------------------------------------------------------------------
 
 
@@ -105,6 +105,33 @@ class TestSmoke_Ports:
         assert resp.port is not None
         assert resp.port.unlo_code == "NLRTM"
 
+    def test_inbound(self, client: VesselClient) -> None:
+        now = datetime.now(timezone.utc)
+        eta_from = now.isoformat()
+        eta_to = (now + timedelta(days=7)).isoformat()
+        resp = client.ports.inbound("NLRTM", eta_from=eta_from, eta_to=eta_to, pagination_limit=5)
+        assert resp is not None
+
+
+class TestSmoke_VesselETA_DestinationPort:
+    def test_destination_port(self, client: VesselClient) -> None:
+        # CMA CGM KHAO SOK — known to have active ETA with destination_port
+        resp = client.vessels.eta("9925837")
+        assert resp.vessel_eta is not None
+        assert resp.vessel_eta.destination_port is not None
+        assert len(resp.vessel_eta.destination_port) > 0
+
+
+class TestSmoke_Meta_Fallback:
+    def test_meta_fallback(self, client: VesselClient) -> None:
+        # Use an MMSI value but claim idType=imo to trigger fallback
+        resp = client.vessels.get("477045900", filter_id_type="imo")
+        assert resp.vessel is not None
+        assert resp.meta is not None
+        assert resp.meta.requested_id_type == "imo"
+        assert resp.meta.resolved_id_type == "mmsi"
+        assert resp.meta.resolved_id == 477045900
+
 
 # ---------------------------------------------------------------------------
 # PortEvents (9 subtests)