vessel-api-python 2.0.1__py3-none-any.whl → 2.1.1__py3-none-any.whl

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/_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/_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/_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())

{vessel_api_python-2.0.1.dist-info → vessel_api_python-2.1.1.dist-info}/METADATA

@@ -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.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+vessel_api_python/__init__.py,sha256=hUlZdyZGgArdYr8XJ30yQibkXXkQPqx3Y9zmVKvi6fc,3200
+vessel_api_python/_client.py,sha256=L7qkzUiATDpPlxWViEKicNpNx7D90gCohas56uCimgA,4919
+vessel_api_python/_constants.py,sha256=uYgcJuAHCdK1VA7SCknrl41TrRblNCsyXkTOwIAu3fY,244
+vessel_api_python/_errors.py,sha256=DaiyCjYKJZTo6-6sOqAcJBdOeFaIYgWHE48nsHWGeGA,6414
+vessel_api_python/_iterator.py,sha256=SkgsGSdxLrKtw-ad8fSUPaEDDJCamAKK0PrG_P8HX-4,3198
+vessel_api_python/_models.py,sha256=bvvd0yrK4Sa8rZ9ZTWRW2E9VedyInNDQm1NxdOCrbi0,21355
+vessel_api_python/_services.py,sha256=UOGpajcZAYrt03DfkG86nIR8zyCGwokq_qB4ZYit7BY,109699
+vessel_api_python/_transport.py,sha256=pfRaJwkq_GYpA5Ev8wH7tBdlzN2ykgy29Ag1L3F5K4Y,6956
+vessel_api_python/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vessel_api_python-2.1.1.dist-info/METADATA,sha256=-TbomFF0ihDCKicRL34-iCsPG9EUyuKuW6YX0G4cqp0,10153
+vessel_api_python-2.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+vessel_api_python-2.1.1.dist-info/licenses/LICENSE,sha256=zoj_abq99mj8cz-Bz71XCnwB-Qv3kU1VzVXeKEntuQU,1067
+vessel_api_python-2.1.1.dist-info/RECORD,,

vessel_api_python-2.0.1.dist-info/RECORD

@@ -1,13 +0,0 @@
-vessel_api_python/__init__.py,sha256=-c0Rq1t5pDN4OY1w_9uNNeHjUI__kovOiyWvvU319jo,3114
-vessel_api_python/_client.py,sha256=L7qkzUiATDpPlxWViEKicNpNx7D90gCohas56uCimgA,4919
-vessel_api_python/_constants.py,sha256=BLbDdSkVaGVmYuyp3grx7XSw-NczIZ5Js8Hjq_m3lZg,244
-vessel_api_python/_errors.py,sha256=DaiyCjYKJZTo6-6sOqAcJBdOeFaIYgWHE48nsHWGeGA,6414
-vessel_api_python/_iterator.py,sha256=SkgsGSdxLrKtw-ad8fSUPaEDDJCamAKK0PrG_P8HX-4,3198
-vessel_api_python/_models.py,sha256=rJnRaZZ9y-h3xYbn0e-7nRLm6Sr9bSkigLIC6jY_HW0,19739
-vessel_api_python/_services.py,sha256=8f6yxKHvzDuIbrQCpN01wT_g4OsByWGHOIhKgDGeaQg,108285
-vessel_api_python/_transport.py,sha256=pfRaJwkq_GYpA5Ev8wH7tBdlzN2ykgy29Ag1L3F5K4Y,6956
-vessel_api_python/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-vessel_api_python-2.0.1.dist-info/METADATA,sha256=4nMuQEUIeVNjbFW9TNwNSKLEpIekmKsX_jZGRZaeWGQ,10153
-vessel_api_python-2.0.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-vessel_api_python-2.0.1.dist-info/licenses/LICENSE,sha256=zoj_abq99mj8cz-Bz71XCnwB-Qv3kU1VzVXeKEntuQU,1067
-vessel_api_python-2.0.1.dist-info/RECORD,,