vessel-api-python 2.0.0__tar.gz → 2.1.0__tar.gz

{vessel_api_python-2.0.0 → vessel_api_python-2.1.0}/CHANGELOG.md

@@ -3,6 +3,44 @@
 All notable changes to this package are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [2.1.0] - 2026-10-26
+
+### Added
+
+- `VesselPositionResponse` has three new fields, which the API returns on every
+  position response since 25 October 2026: `vessel` (a `Vessel`, as from
+  `vessels.get()`), `vessel_eta` (a `VesselETA`, as from `vessels.eta()`) and
+  `position_check` (the new `PositionCheck` model). `vessel` and `vessel_eta`
+  are `None` when the API holds no record for them. Earlier versions drop these
+  keys when parsing.
+- `PositionCheck` compares the position with the vessel's previous report from
+  the last 80 hours (`previous_position`, the new `PreviousPosition` model). It
+  gives the time and great-circle distance since then, and the speed and course
+  that would cover that distance. It also says whether that speed is more than
+  1.2 times the vessel's usual top speed, and whether the MMSI and IMO match.
+- `vessels.position()` takes `filter_sat_lookback_minutes` and
+  `filter_sat_max_age_minutes`, which set the satellite fallback's time windows.
+  Both the sync and async clients have them.
+
+### Changed
+
+- The bundled OpenAPI spec is synced with the API.
+
+## [2.0.1] - 2026-10-08
+
+Documentation only. No method, parameter or model changed.
+
+### Fixed
+
+- The bundled OpenAPI spec named the satellite fallback parameter `sat`; the
+  API's parameter is `filter.sat`. Descriptions corrected.
+
+### Changed
+
+- README: the satellite fallback note says when it fires (no recent terrestrial
+  position stored); the radius example describes the time window it searches
+  (default 2 hours, at most 4).
+
 ## [2.0.0] - 2026-08-16
 
 Vessel ownership, classification and inspection data, and NAVTEX messages, were

{vessel_api_python-2.0.0 → vessel_api_python-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vessel-api-python
-Version: 2.0.0
+Version: 2.1.0
 Summary: Python client for the Vessel Tracking API: maritime vessel tracking, port events, emissions, and nautical infrastructure.
 Project-URL: Documentation, https://vesselapi.com/docs
 Project-URL: Repository, https://github.com/vessel-api/vesselapi-python
@@ -131,11 +131,12 @@ print(f"{vessel.vessel.name} ({vessel.vessel.vessel_type})")
 pos = client.vessels.position("232003239", filter_id_type="mmsi")
 print(f"Position: {pos.vessel_position.latitude}, {pos.vessel_position.longitude}")
 
-# filter_sat=True falls back to satellite AIS when nothing is stored.
+# filter_sat=True falls back to satellite AIS when no recent terrestrial position is stored.
 # ⚠️ Satellite lookups draw on a prepaid balance and are charged per call.
 # Omit it unless you need that fallback.
 
-# Find all vessels within 10 km of Rotterdam.
+# Find vessels with an AIS position within 10 km of Rotterdam in the last 2 hours
+# (the default time window, at most 4 hours).
 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}")

{vessel_api_python-2.0.0 → vessel_api_python-2.1.0}/README.md

@@ -97,11 +97,12 @@ print(f"{vessel.vessel.name} ({vessel.vessel.vessel_type})")
 pos = client.vessels.position("232003239", filter_id_type="mmsi")
 print(f"Position: {pos.vessel_position.latitude}, {pos.vessel_position.longitude}")
 
-# filter_sat=True falls back to satellite AIS when nothing is stored.
+# filter_sat=True falls back to satellite AIS when no recent terrestrial position is stored.
 # ⚠️ Satellite lookups draw on a prepaid balance and are charged per call.
 # Omit it unless you need that fallback.
 
-# Find all vessels within 10 km of Rotterdam.
+# Find vessels with an AIS position within 10 km of Rotterdam in the last 2 hours
+# (the default time window, at most 4 hours).
 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}")

{vessel_api_python-2.0.0 → vessel_api_python-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vessel-api-python"
-version = "2.0.0"
+version = "2.1.0"
 description = "Python client for the Vessel Tracking API: maritime vessel tracking, port events, emissions, and nautical infrastructure."
 readme = "README.md"
 requires-python = ">=3.9"

{vessel_api_python-2.0.0 → vessel_api_python-2.1.0}/src/vessel_api_python/__init__.py

@@ -45,6 +45,8 @@ from ._models import (
     PortReference,
     PortResponse,
     PortsWithinLocationResponse,
+    PositionCheck,
+    PreviousPosition,
     RadioBeacon,
     RadioBeaconsWithinLocationResponse,
     ResolutionMeta,
@@ -96,6 +98,8 @@ __all__ = [
     "VesselResponse",
     "VesselPosition",
     "VesselPositionResponse",
+    "PositionCheck",
+    "PreviousPosition",
     "VesselPositionsResponse",
     "MarineCasualty",
     "MarineCasualtiesResponse",

{vessel_api_python-2.0.0 → vessel_api_python-2.1.0}/src/vessel_api_python/_constants.py

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

{vessel_api_python-2.0.0 → vessel_api_python-2.1.0}/src/vessel_api_python/_models.py

@@ -144,10 +144,40 @@ class VesselPosition(_Base):
     vessel_name: str | None = None
 
 
+class PreviousPosition(_Base):
+    """The vessel's newest position report before the served one."""
+
+    latitude: float | None = None
+    longitude: float | None = None
+    timestamp: str | None = None
+
+
+class PositionCheck(_Base):
+    """How the served position compares with the vessel's previous position report.
+
+    Only ``lookback_hours`` is present when no previous report falls within it.
+    """
+
+    previous_position: PreviousPosition | None = None
+    minutes_since_previous: int | None = None
+    distance_nm: float | None = None
+    implied_speed_kn: float | None = None
+    implied_course: int | None = None
+    exceeds_typical_speed: bool | None = None
+    identity_match: bool | None = None
+    lookback_hours: int | None = None
+
+
 class VesselPositionResponse(_Base):
-    """Response for a single vessel position lookup."""
+    """Response for a single vessel position lookup.
+
+    ``vessel`` and ``vessel_eta`` are ``None`` when the API holds no record for them.
+    """
 
     vessel_position: VesselPosition | None = Field(default=None, alias="vesselPosition")
+    vessel: Vessel | None = None
+    vessel_eta: VesselETA | None = Field(default=None, alias="vesselEta")
+    position_check: PositionCheck | None = Field(default=None, alias="positionCheck")
     meta: ResolutionMeta | None = Field(default=None, alias="_meta")
 
 

{vessel_api_python-2.0.0 → vessel_api_python-2.1.0}/src/vessel_api_python/_services.py

@@ -94,15 +94,32 @@ class VesselsService:
         return VesselResponse.model_validate(r.json())
 
     def position(
-        self, vessel_id: str, *, filter_id_type: str = "imo", filter_sat: bool | None = None
+        self,
+        vessel_id: str,
+        *,
+        filter_id_type: str = "imo",
+        filter_sat: bool | None = None,
+        filter_sat_lookback_minutes: int | None = None,
+        filter_sat_max_age_minutes: int | None = None,
     ) -> VesselPositionResponse:
         """Retrieve the latest position for a vessel.
 
         ``filter_sat`` enables satellite AIS fallback; the server defaults it to false.
+        With ``filter_sat=True``, ``filter_sat_lookback_minutes`` (60 to 4800, default 180)
+        sets how old a satellite fix may be and still be returned.
+        ``filter_sat_max_age_minutes`` (15 to 4800, default 60, paid plans only) sets how
+        old a stored position may be before a satellite lookup is made.
         """
         r = self._client.get(
             f"/vessel/{vessel_id}/position",
-            params=_strip_none({"filter.idType": filter_id_type, "filter.sat": filter_sat}),
+            params=_strip_none(
+                {
+                    "filter.idType": filter_id_type,
+                    "filter.sat": filter_sat,
+                    "filter.satLookbackMinutes": filter_sat_lookback_minutes,
+                    "filter.satMaxAgeMinutes": filter_sat_max_age_minutes,
+                }
+            ),
         )
         error_from_response(r.status_code, r.content)
         return VesselPositionResponse.model_validate(r.json())
@@ -1561,15 +1578,32 @@ class AsyncVesselsService:
         return VesselResponse.model_validate(r.json())
 
     async def position(
-        self, vessel_id: str, *, filter_id_type: str = "imo", filter_sat: bool | None = None
+        self,
+        vessel_id: str,
+        *,
+        filter_id_type: str = "imo",
+        filter_sat: bool | None = None,
+        filter_sat_lookback_minutes: int | None = None,
+        filter_sat_max_age_minutes: int | None = None,
     ) -> VesselPositionResponse:
         """Retrieve the latest position for a vessel.
 
         ``filter_sat`` enables satellite AIS fallback; the server defaults it to false.
+        With ``filter_sat=True``, ``filter_sat_lookback_minutes`` (60 to 4800, default 180)
+        sets how old a satellite fix may be and still be returned.
+        ``filter_sat_max_age_minutes`` (15 to 4800, default 60, paid plans only) sets how
+        old a stored position may be before a satellite lookup is made.
         """
         r = await self._client.get(
             f"/vessel/{vessel_id}/position",
-            params=_strip_none({"filter.idType": filter_id_type, "filter.sat": filter_sat}),
+            params=_strip_none(
+                {
+                    "filter.idType": filter_id_type,
+                    "filter.sat": filter_sat,
+                    "filter.satLookbackMinutes": filter_sat_lookback_minutes,
+                    "filter.satMaxAgeMinutes": filter_sat_max_age_minutes,
+                }
+            ),
         )
         error_from_response(r.status_code, r.content)
         return VesselPositionResponse.model_validate(r.json())