vessel-api-python 2.0.0__py3-none-any.whl → 2.1.0__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.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/_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/_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.0.dist-info → vessel_api_python-2.1.0.dist-info}/METADATA

@@ -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.1.0.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=rfYu8M4IeUngAqYB6h_N0iwrtVpBA5jDzcT46RjJu7Y,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=BizjprJtFxyl7064ovks81m31SFdgfxKi6fg3rXjatk,20773
+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.0.dist-info/METADATA,sha256=IGgln4OImtva-TRMJIcFqUgPLX8jQdwJYekDdtZ8HiM,10153
+vessel_api_python-2.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+vessel_api_python-2.1.0.dist-info/licenses/LICENSE,sha256=zoj_abq99mj8cz-Bz71XCnwB-Qv3kU1VzVXeKEntuQU,1067
+vessel_api_python-2.1.0.dist-info/RECORD,,

{vessel_api_python-2.0.0.dist-info → vessel_api_python-2.1.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.32.0
+Generator: hatchling 1.32.4
 Root-Is-Purelib: true
 Tag: py3-none-any

vessel_api_python-2.0.0.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=Im6d9J9HSo5D-Rt4SVIQ35lqqGXIovSxhGsBhNqTVdU,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.0.dist-info/METADATA,sha256=1HWjKevhtZDfUq9F1k4DNZoGZvtfaWnzsJw5dnPOVA0,10048
-vessel_api_python-2.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-vessel_api_python-2.0.0.dist-info/licenses/LICENSE,sha256=zoj_abq99mj8cz-Bz71XCnwB-Qv3kU1VzVXeKEntuQU,1067
-vessel_api_python-2.0.0.dist-info/RECORD,,