vessel-api-python 2.0.1__tar.gz → 2.1.1__tar.gz

{vessel_api_python-2.0.1 → vessel_api_python-2.1.1}/CHANGELOG.md

@@ -3,6 +3,57 @@
 All notable changes to this package are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [2.1.1] - 2026-10-27
+
+Documentation and spec only. No method, parameter or model changed.
+
+### Changed
+
+- The API now returns `identity_match` in `PositionCheck` only when it holds a
+  record for the vessel and an identifier can be compared. In other cases the
+  field is `None`. Before this change, a vessel with no record always got `True`.
+- The API now checks every returned position for a suspected glitch, measured
+  from the vessel's previous clean report. More positions can come back with
+  `suspected_glitch` set to `True`.
+- The bundled OpenAPI spec is synced with the API. Field descriptions no longer
+  begin with an internal field name ("DistanceNM Great-circle distance..." now
+  reads "Great-circle distance...").
+
+### Fixed
+
+- Docstrings now say when `identity_match` and `vessel_eta` are `None`.
+  `vessel_eta` is `None` when no destination or ETA is available, including when
+  the lookup does not finish in time. The 2.1.0 notes said it was `None` only
+  when the API held no record.
+- `exceeds_typical_speed` and `speed_observed_max` describe the vessel's usual
+  top speed (the 99th percentile of its recent speeds) and no longer call it a
+  peak.
+- Docstrings call the position in the response the "returned" position, where
+  they said "served".
+
+## [2.1.0] - 2026-10-27
+
+### 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.

{vessel_api_python-2.0.1 → vessel_api_python-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vessel-api-python
-Version: 2.0.1
+Version: 2.1.1
 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

{vessel_api_python-2.0.1 → vessel_api_python-2.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vessel-api-python"
-version = "2.0.1"
+version = "2.1.1"
 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.1 → vessel_api_python-2.1.1}/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.1 → vessel_api_python-2.1.1}/src/vessel_api_python/_constants.py

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

{vessel_api_python-2.0.1 → vessel_api_python-2.1.1}/src/vessel_api_python/_models.py

@@ -127,7 +127,11 @@ class VesselResponse(_Base):
 
 
 class VesselPosition(_Base):
-    """A real-time vessel position record from AIS data."""
+    """A real-time vessel position record from AIS data.
+
+    ``suspected_glitch`` is true when the move from the previous clean report
+    implies a speed over 500 knots.
+    """
 
     cog: float | None = None
     heading: int | None = None
@@ -144,10 +148,47 @@ class VesselPosition(_Base):
     vessel_name: str | None = None
 
 
+class PreviousPosition(_Base):
+    """The vessel's newest position report before the returned one."""
+
+    latitude: float | None = None
+    longitude: float | None = None
+    timestamp: str | None = None
+
+
+class PositionCheck(_Base):
+    """How the returned position compares with the vessel's previous position report.
+
+    ``lookback_hours`` is always present. ``identity_match`` is present only when a
+    vessel record exists and an identifier can be compared. It is true when the
+    returned position's identifiers match those in the record. The other fields
+    need a previous report within ``lookback_hours``. ``exceeds_typical_speed`` is
+    true when the implied speed exceeds the vessel's usual top speed (99th
+    percentile of its recent speeds).
+    """
+
+    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`` is ``None`` when no vessel record exists. ``vessel_eta`` is ``None``
+    when no destination or ETA is available, including when the lookup does not
+    finish in time.
+    """
 
     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.1 → vessel_api_python-2.1.1}/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())