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

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

@@ -3,7 +3,41 @@
 All notable changes to this package are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
-## [2.1.0] - 2026-10-26
+## [2.1.2] - 2026-11-01
+
+### Deprecated
+
+- The satellite fallback (`filter_sat`, `filter_sat_lookback_minutes` and `filter_sat_max_age_minutes`) is withdrawn in its current form. The parameters keep working for existing credit holders until 00:00 UTC on 30 November 2026; from then they are accepted and ignored, no credit is charged, and the response carries a Warning header. Responses carry Deprecation and Sunset headers from 31 October 2026. Credit packs are no longer on sale; unspent credits are refunded on request. Documentation and spec only, no function, parameter or type changed.
+
+## [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
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vessel-api-python
-Version: 2.1.0
+Version: 2.1.2
 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,9 +131,7 @@ 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 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.
+# filter_sat is deprecated: the satellite fallback is withdrawn in its current form.
 
 # Find vessels with an AIS position within 10 km of Rotterdam in the last 2 hours
 # (the default time window, at most 4 hours).
@@ -142,6 +140,8 @@ for v in nearby.vessels or []:
     print(f"{v.vessel_name} at {v.latitude}, {v.longitude}")
 ```
 
+> **Deprecated.** The satellite fallback is withdrawn in its current form. Requests with `filter.sat=true` keep working for existing credit holders until the cutoff date and carry Deprecation and Sunset headers. From the cutoff date the parameter is accepted and ignored, the response carries a Warning header, and no credit is charged. Credit packs are no longer on sale; unspent credits are refunded on request to support@vesselapi.com. The cutoff date is given in the `Sunset` header.
+
 ## Search
 
 `search.vessels` accepts `q`, a unified search across IMO, MMSI, ENI, callsign and

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

@@ -97,9 +97,7 @@ 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 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.
+# filter_sat is deprecated: the satellite fallback is withdrawn in its current form.
 
 # Find vessels with an AIS position within 10 km of Rotterdam in the last 2 hours
 # (the default time window, at most 4 hours).
@@ -108,6 +106,8 @@ for v in nearby.vessels or []:
     print(f"{v.vessel_name} at {v.latitude}, {v.longitude}")
 ```
 
+> **Deprecated.** The satellite fallback is withdrawn in its current form. Requests with `filter.sat=true` keep working for existing credit holders until the cutoff date and carry Deprecation and Sunset headers. From the cutoff date the parameter is accepted and ignored, the response carries a Warning header, and no credit is charged. Credit packs are no longer on sale; unspent credits are refunded on request to support@vesselapi.com. The cutoff date is given in the `Sunset` header.
+
 ## Search
 
 `search.vessels` accepts `q`, a unified search across IMO, MMSI, ENI, callsign and

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

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

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

{vessel_api_python-2.1.0 → vessel_api_python-2.1.2}/src/vessel_api_python/_errors.py

@@ -54,8 +54,12 @@ class VesselAPIError(Exception):
         """True if the error is a 402 Payment Required response.
 
         Returned when a satellite-backed call is made with no satellite credits
-        left. Retry without ``filter_sat`` to serve stored data instead, or top
-        up the balance.
+        left. Retry without ``filter_sat`` to serve stored data instead.
+
+        .. deprecated::
+            The satellite fallback is withdrawn in its current form. From the
+            cutoff date ``filter_sat`` is ignored and no satellite request
+            returns 402.
         """
         return self.status_code == 402
 
@@ -75,7 +79,12 @@ class VesselAuthError(VesselAPIError):
 
 
 class VesselPaymentRequiredError(VesselAPIError):
-    """Raised on 402 Payment Required responses (satellite credits exhausted)."""
+    """Raised on 402 Payment Required responses (satellite credits exhausted).
+
+    .. deprecated::
+        The satellite fallback is withdrawn in its current form. From the cutoff
+        date ``filter_sat`` is ignored and no satellite request returns 402.
+    """
 
 
 class VesselForbiddenError(VesselAPIError):

{vessel_api_python-2.1.0 → vessel_api_python-2.1.2}/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
@@ -145,7 +149,7 @@ class VesselPosition(_Base):
 
 
 class PreviousPosition(_Base):
-    """The vessel's newest position report before the served one."""
+    """The vessel's newest position report before the returned one."""
 
     latitude: float | None = None
     longitude: float | None = None
@@ -153,9 +157,14 @@ class PreviousPosition(_Base):
 
 
 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.
+    """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
@@ -171,7 +180,9 @@ class PositionCheck(_Base):
 class VesselPositionResponse(_Base):
     """Response for a single vessel position lookup.
 
-    ``vessel`` and ``vessel_eta`` are ``None`` when the API holds no record for them.
+    ``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_api_python-2.1.0 → vessel_api_python-2.1.2}/src/vessel_api_python/_services.py

@@ -109,6 +109,13 @@ class VesselsService:
         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.
+
+        .. deprecated::
+            ``filter_sat``, ``filter_sat_lookback_minutes`` and
+            ``filter_sat_max_age_minutes`` are deprecated. The satellite fallback
+            is withdrawn in its current form. From the cutoff date in the
+            ``Sunset`` header they are accepted and ignored and no credit is
+            charged.
         """
         r = self._client.get(
             f"/vessel/{vessel_id}/position",
@@ -1593,6 +1600,13 @@ class AsyncVesselsService:
         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.
+
+        .. deprecated::
+            ``filter_sat``, ``filter_sat_lookback_minutes`` and
+            ``filter_sat_max_age_minutes`` are deprecated. The satellite fallback
+            is withdrawn in its current form. From the cutoff date in the
+            ``Sunset`` header they are accepted and ignored and no credit is
+            charged.
         """
         r = await self._client.get(
             f"/vessel/{vessel_id}/position",