vessel-api-python 1.0.0__tar.gz

vessel_api_python-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+  workflow_dispatch:
+
+jobs:
+  unit-tests:
+    name: Unit Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - run: pip install -e ".[dev]"
+      - run: ruff check src/ tests/
+      - run: mypy src/vessel_api_python/
+      - run: pytest -v tests/
+
+  smoke-tests:
+    name: Smoke Tests
+    runs-on: ubuntu-latest
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      github.event_name == 'push' ||
+      github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install -e ".[dev]"
+      - run: pytest -v -m smoke tests/
+        env:
+          VESSELAPI_API_KEY: ${{ secrets.VESSELAPI_API_KEY }}

vessel_api_python-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    name: Build & Publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install build
+      - run: python -m build
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

vessel_api_python-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg
+.env

vessel_api_python-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vessel API
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vessel_api_python-1.0.0/Makefile

@@ -0,0 +1,21 @@
+.PHONY: all lint typecheck test fmt install smoke
+
+all: fmt lint typecheck test
+
+lint:
+	ruff check src/ tests/
+
+typecheck:
+	mypy src/vesselapi/
+
+test:
+	pytest -v tests/
+
+fmt:
+	ruff format src/ tests/
+
+install:
+	pip install -e ".[dev]"
+
+smoke:
+	pytest -v -m smoke tests/

vessel_api_python-1.0.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: vessel-api-python
+Version: 1.0.0
+Summary: Python client for the Vessel Tracking API — maritime vessel tracking, port events, emissions, and navigation data.
+Project-URL: Documentation, https://vesselapi.com/docs
+Project-URL: Repository, https://github.com/vessel-api/vesselapi-python
+Project-URL: Issues, https://github.com/vessel-api/vesselapi-python/issues
+Project-URL: Changelog, https://github.com/vessel-api/vesselapi-python/releases
+Author-email: Vessel API <support@vesselapi.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ais,maritime,sdk,tracking,vessel,vesselapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: eval-type-backport>=0.2.0; python_version < '3.10'
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# vesselapi-python
+
+[![CI](https://github.com/vessel-api/vesselapi-python/actions/workflows/ci.yml/badge.svg)](https://github.com/vessel-api/vesselapi-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/vessel-api-python.svg)](https://pypi.org/project/vessel-api-python/)
+[![Python](https://img.shields.io/pypi/pyversions/vessel-api-python.svg)](https://pypi.org/project/vessel-api-python/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Python client for the [Vessel Tracking API](https://vesselapi.com) — maritime vessel tracking, port events, emissions, and navigation data.
+
+**Resources**: [Documentation](https://vesselapi.com/docs) | [API Explorer](https://vesselapi.com/api-reference) | [Dashboard](https://dashboard.vesselapi.com) | [Contact Support](mailto:support@vesselapi.com)
+
+## Install
+
+```bash
+pip install vessel-api-python
+```
+
+Requires Python 3.9+.
+
+## Quick Start
+
+```python
+from vessel_api_python import VesselClient
+
+client = VesselClient(api_key="your-api-key")
+
+# Search for a vessel by name.
+result = client.search.vessels(filter_name="Ever Given")
+for v in result.vessels or []:
+    print(f"{v.name} (IMO {v.imo})")
+
+# Get a port by UN/LOCODE.
+port = client.ports.get("NLRTM")
+print(port.port.name)
+
+# Auto-paginate through port events.
+for event in client.port_events.list_all(pagination_limit=10):
+    print(f"{event.event} at {event.timestamp}")
+```
+
+### Async
+
+```python
+import asyncio
+from vessel_api_python import AsyncVesselClient
+
+async def main():
+    async with AsyncVesselClient(api_key="your-api-key") as client:
+        result = await client.search.vessels(filter_name="Ever Given")
+        async for event in client.port_events.list_all(pagination_limit=10):
+            print(f"{event.event} at {event.timestamp}")
+
+asyncio.run(main())
+```
+
+## Available Services
+
+| Service | Methods | Description |
+|---------|---------|-------------|
+| `vessels` | `get`, `position`, `casualties`, `classification`, `emissions`, `eta`, `inspections`, `inspection_detail`, `ownership`, `positions` | Vessel details, positions, and records |
+| `ports` | `get` | Port lookup by UN/LOCODE |
+| `port_events` | `list`, `by_port`, `by_ports`, `by_vessel`, `last_by_vessel`, `by_vessels` | Vessel arrival/departure events |
+| `emissions` | `list` | EU MRV emissions data |
+| `search` | `vessels`, `ports`, `dgps`, `light_aids`, `modus`, `radio_beacons` | Full-text search across entity types |
+| `location` | `vessels_bounding_box`, `vessels_radius`, `ports_bounding_box`, `ports_radius`, `dgps_bounding_box`, `dgps_radius`, `light_aids_bounding_box`, `light_aids_radius`, `modus_bounding_box`, `modus_radius`, `radio_beacons_bounding_box`, `radio_beacons_radius` | Geo queries by bounding box or radius |
+| `navtex` | `list` | NAVTEX maritime safety messages |
+
+**37 methods total.**
+
+## Error Handling
+
+All methods raise specific exception types on non-2xx responses:
+
+```python
+from vessel_api_python import VesselAPIError
+
+try:
+    client.ports.get("ZZZZZ")
+except VesselAPIError as err:
+    if err.is_not_found:
+        print("Port not found")
+    elif err.is_rate_limited:
+        print("Rate limited — back off")
+    elif err.is_auth_error:
+        print("Check API key")
+    print(err.status_code, err.message)
+```
+
+## Auto-Pagination
+
+Every list endpoint has an `all_*` / `list_all` variant returning an iterator:
+
+```python
+# Sync
+for vessel in client.search.all_vessels(filter_name="tanker"):
+    print(vessel.name)
+
+# Async
+async for vessel in client.search.all_vessels(filter_name="tanker"):
+    print(vessel.name)
+
+# Collect all at once
+vessels = client.search.all_vessels(filter_name="tanker").collect()
+```
+
+## Configuration
+
+```python
+client = VesselClient(
+    api_key="your-api-key",
+    base_url="https://custom-endpoint.example.com/v1",
+    timeout=60.0,
+    max_retries=5,  # default: 3
+    user_agent="my-app/1.0",
+)
+```
+
+Retries use exponential backoff with jitter on 429 and 5xx responses. The `Retry-After` header is respected.
+
+## Documentation
+
+- [API Documentation](https://vesselapi.com/docs) — endpoint guides, request/response schemas, and usage examples
+- [API Explorer](https://vesselapi.com/api-reference) — interactive API reference
+- [Dashboard](https://dashboard.vesselapi.com) — manage API keys and monitor usage
+
+## Contributing & Support
+
+Found a bug, have a feature request, or need help? You're welcome to [open an issue](https://github.com/vessel-api/vesselapi-python/issues). For API-level bugs and feature requests, please use the [main VesselAPI repository](https://github.com/vessel-api/VesselApi/issues).
+
+For security vulnerabilities, **do not** open a public issue — email security@vesselapi.com instead. See [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE)

vessel_api_python-1.0.0/README.md

@@ -0,0 +1,134 @@
+# vesselapi-python
+
+[![CI](https://github.com/vessel-api/vesselapi-python/actions/workflows/ci.yml/badge.svg)](https://github.com/vessel-api/vesselapi-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/vessel-api-python.svg)](https://pypi.org/project/vessel-api-python/)
+[![Python](https://img.shields.io/pypi/pyversions/vessel-api-python.svg)](https://pypi.org/project/vessel-api-python/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Python client for the [Vessel Tracking API](https://vesselapi.com) — maritime vessel tracking, port events, emissions, and navigation data.
+
+**Resources**: [Documentation](https://vesselapi.com/docs) | [API Explorer](https://vesselapi.com/api-reference) | [Dashboard](https://dashboard.vesselapi.com) | [Contact Support](mailto:support@vesselapi.com)
+
+## Install
+
+```bash
+pip install vessel-api-python
+```
+
+Requires Python 3.9+.
+
+## Quick Start
+
+```python
+from vessel_api_python import VesselClient
+
+client = VesselClient(api_key="your-api-key")
+
+# Search for a vessel by name.
+result = client.search.vessels(filter_name="Ever Given")
+for v in result.vessels or []:
+    print(f"{v.name} (IMO {v.imo})")
+
+# Get a port by UN/LOCODE.
+port = client.ports.get("NLRTM")
+print(port.port.name)
+
+# Auto-paginate through port events.
+for event in client.port_events.list_all(pagination_limit=10):
+    print(f"{event.event} at {event.timestamp}")
+```
+
+### Async
+
+```python
+import asyncio
+from vessel_api_python import AsyncVesselClient
+
+async def main():
+    async with AsyncVesselClient(api_key="your-api-key") as client:
+        result = await client.search.vessels(filter_name="Ever Given")
+        async for event in client.port_events.list_all(pagination_limit=10):
+            print(f"{event.event} at {event.timestamp}")
+
+asyncio.run(main())
+```
+
+## Available Services
+
+| Service | Methods | Description |
+|---------|---------|-------------|
+| `vessels` | `get`, `position`, `casualties`, `classification`, `emissions`, `eta`, `inspections`, `inspection_detail`, `ownership`, `positions` | Vessel details, positions, and records |
+| `ports` | `get` | Port lookup by UN/LOCODE |
+| `port_events` | `list`, `by_port`, `by_ports`, `by_vessel`, `last_by_vessel`, `by_vessels` | Vessel arrival/departure events |
+| `emissions` | `list` | EU MRV emissions data |
+| `search` | `vessels`, `ports`, `dgps`, `light_aids`, `modus`, `radio_beacons` | Full-text search across entity types |
+| `location` | `vessels_bounding_box`, `vessels_radius`, `ports_bounding_box`, `ports_radius`, `dgps_bounding_box`, `dgps_radius`, `light_aids_bounding_box`, `light_aids_radius`, `modus_bounding_box`, `modus_radius`, `radio_beacons_bounding_box`, `radio_beacons_radius` | Geo queries by bounding box or radius |
+| `navtex` | `list` | NAVTEX maritime safety messages |
+
+**37 methods total.**
+
+## Error Handling
+
+All methods raise specific exception types on non-2xx responses:
+
+```python
+from vessel_api_python import VesselAPIError
+
+try:
+    client.ports.get("ZZZZZ")
+except VesselAPIError as err:
+    if err.is_not_found:
+        print("Port not found")
+    elif err.is_rate_limited:
+        print("Rate limited — back off")
+    elif err.is_auth_error:
+        print("Check API key")
+    print(err.status_code, err.message)
+```
+
+## Auto-Pagination
+
+Every list endpoint has an `all_*` / `list_all` variant returning an iterator:
+
+```python
+# Sync
+for vessel in client.search.all_vessels(filter_name="tanker"):
+    print(vessel.name)
+
+# Async
+async for vessel in client.search.all_vessels(filter_name="tanker"):
+    print(vessel.name)
+
+# Collect all at once
+vessels = client.search.all_vessels(filter_name="tanker").collect()
+```
+
+## Configuration
+
+```python
+client = VesselClient(
+    api_key="your-api-key",
+    base_url="https://custom-endpoint.example.com/v1",
+    timeout=60.0,
+    max_retries=5,  # default: 3
+    user_agent="my-app/1.0",
+)
+```
+
+Retries use exponential backoff with jitter on 429 and 5xx responses. The `Retry-After` header is respected.
+
+## Documentation
+
+- [API Documentation](https://vesselapi.com/docs) — endpoint guides, request/response schemas, and usage examples
+- [API Explorer](https://vesselapi.com/api-reference) — interactive API reference
+- [Dashboard](https://dashboard.vesselapi.com) — manage API keys and monitor usage
+
+## Contributing & Support
+
+Found a bug, have a feature request, or need help? You're welcome to [open an issue](https://github.com/vessel-api/vesselapi-python/issues). For API-level bugs and feature requests, please use the [main VesselAPI repository](https://github.com/vessel-api/VesselApi/issues).
+
+For security vulnerabilities, **do not** open a public issue — email security@vesselapi.com instead. See [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE)

vessel_api_python-1.0.0/SECURITY.md

@@ -0,0 +1,11 @@
+# Security Policy
+
+This repository follows the security policy of the main VesselAPI project.
+
+## Reporting a Vulnerability
+
+**DO NOT** open a public GitHub issue for security vulnerabilities.
+
+**Email:** security@vesselapi.com
+
+For full details on reporting process, severity levels, scope, and safe harbor policy, see the [VesselAPI Security Policy](https://github.com/vessel-api/VesselApi/blob/master/SECURITY.md).

vessel_api_python-1.0.0/examples/async_basic.py

@@ -0,0 +1,49 @@
+"""Basic asynchronous usage of the Vessel API Python SDK."""
+
+import asyncio
+import os
+import sys
+
+from vesselapi import AsyncVesselClient, VesselAPIError
+
+
+async def main() -> None:
+    api_key = os.environ.get("VESSELAPI_API_KEY", "")
+    if not api_key:
+        print("VESSELAPI_API_KEY environment variable is required")
+        sys.exit(1)
+
+    async with AsyncVesselClient(api_key=api_key) as client:
+        # Search for vessels.
+        print("--- Search Vessels ---")
+        result = await client.search.vessels(filter_name="Ever Given")
+        for v in result.vessels or []:
+            print(f"Vessel: {v.name} (IMO: {v.imo})")
+
+        # Get a port.
+        print("\n--- Get Port ---")
+        port = await client.ports.get("NLRTM")
+        if port.port:
+            print(f"Port: {port.port.name} ({port.port.unlo_code})")
+
+        # Error handling.
+        print("\n--- Error Handling ---")
+        try:
+            await client.ports.get("ZZZZZ")
+        except VesselAPIError as err:
+            if err.is_not_found:
+                print(f"Port not found (status {err.status_code})")
+
+        # Auto-paginate (async).
+        print("\n--- Port Events (async paginated) ---")
+        count = 0
+        async for event in client.port_events.list_all(pagination_limit=10):
+            print(f"Event: {event.event} at {event.timestamp}")
+            count += 1
+            if count >= 25:
+                break
+        print(f"Total events shown: {count}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

vessel_api_python-1.0.0/examples/basic.py

@@ -0,0 +1,67 @@
+"""Basic synchronous usage of the Vessel API Python SDK."""
+
+import os
+import sys
+
+from vesselapi import VesselClient, VesselAPIError
+
+
+def main() -> None:
+    api_key = os.environ.get("VESSELAPI_API_KEY", "")
+    if not api_key:
+        print("VESSELAPI_API_KEY environment variable is required")
+        sys.exit(1)
+
+    client = VesselClient(api_key=api_key)
+
+    # Search for vessels by name.
+    print("--- Search Vessels ---")
+    result = client.search.vessels(filter_name="Ever Given")
+    for v in result.vessels or []:
+        print(f"Vessel: {v.name} (IMO: {v.imo})")
+
+    # Search for vessels by flag.
+    print("\n--- Search Vessels by Flag ---")
+    flag_result = client.search.vessels(filter_flag="PA", filter_vessel_type="Container Ship", pagination_limit=5)
+    for v in flag_result.vessels or []:
+        print(f"Vessel: {v.name} (IMO: {v.imo}, Country: {v.country})")
+
+    # Search for ports by country.
+    print("\n--- Search Ports by Country ---")
+    port_search = client.search.ports(filter_country="NL", pagination_limit=5)
+    for p in port_search.ports or []:
+        print(f"Port: {p.name} ({p.unlo_code})")
+
+    # Get a port by UNLOCODE.
+    print("\n--- Get Port ---")
+    port = client.ports.get("NLRTM")
+    if port.port:
+        print(f"Port: {port.port.name} ({port.port.unlo_code})")
+
+    # Handle a not-found port gracefully.
+    print("\n--- Not Found Handling ---")
+    try:
+        client.ports.get("ZZZZZ")
+    except VesselAPIError as err:
+        if err.is_not_found:
+            print(f"Port ZZZZZ not found (status {err.status_code})")
+        elif err.is_rate_limited:
+            print("Rate limited — try again later")
+        else:
+            print(f"API error: {err.message} (status {err.status_code})")
+
+    # Auto-paginate through port events.
+    print("\n--- Port Events (paginated) ---")
+    count = 0
+    for event in client.port_events.list_all(pagination_limit=10):
+        print(f"Event: {event.event} at {event.timestamp}")
+        count += 1
+        if count >= 25:
+            break
+    print(f"Total events shown: {count}")
+
+    client.close()
+
+
+if __name__ == "__main__":
+    main()