Telemetry Harbor Python SDK

A modern, production-ready SDK for sending telemetry data to the Telemetry Harbor service from any Python application.

This SDK simplifies data sending by handling HTTP communication, JSON serialization, and robust error handling with automatic retries.

Repo Link: https://github.com/TelemetryHarbor/harbor-sdk-python

Features

• ✅ Pydantic Models for strong validation and ease of use.
• 🔁 Automatic Retries with exponential backoff for network resilience.
• 📦 Batch Support for efficient multi-reading uploads.
• ⚙️ Simple API with intuitive methods like send and send_batch.
• 🌐 Universal — works in any Python 3.7+ environment.

Installation

pip install telemetryharborsdk

Quickstart Guide

Here is a basic example of how to use the SDK.

from telemetryharborsdk import HarborClient, GeneralReading

# 1. Initialize the client
client = HarborClient(
    endpoint="https://api.telemetry-harbor.com/v2/ingest/{harbor_id}",
    api_key="your_secret_api_key"
)

# 2. Create a reading
reading = GeneralReading(
    ship_id="MV-Explorer",
    cargo_id="C-1138",
    value=42.5
)

# 3. Send the reading
response = client.send(reading)
print("Successfully sent data!", response)

# --- Or send a batch ---
batch = [
    GeneralReading(ship_id="MV-Explorer", cargo_id="C-1138", value=42.5),
    GeneralReading(ship_id="MV-Explorer", cargo_id="temperature", value=21.7),
]
batch_response = client.send_batch(batch)
print("Successfully sent batch!", batch_response)

GPS and Cargo Data Rules

When sending GPS coordinates, send latitude and longitude as separate readings with:

• The same ship_id and timestamp.
• Distinct cargo_ids "latitude" and "longitude".

This allows proper grouping in the backend for time-series queries.

Example batch:

[
  {
    "ship_id": "MV-Explorer",
    "cargo_id": "latitude",
    "value": 41.123,
    "timestamp": "2025-07-17T10:00:00Z"
  },
  {
    "ship_id": "MV-Explorer",
    "cargo_id": "longitude",
    "value": 29.456,
    "timestamp": "2025-07-17T10:00:00Z"
  }
]

✅ This enables SQL queries to reconstruct full GPS points by grouping on ship_id and timestamp.

Query example (PostgreSQL/TimescaleDB):

SELECT
    time,
    MAX(value) FILTER (WHERE cargo_id = 'latitude') AS latitude,
    MAX(value) FILTER (WHERE cargo_id = 'longitude') AS longitude,
    ship_id
FROM cargo_data
WHERE $__timeFilter(time)
  AND ship_id IN (${ship_id:sqlstring})
  AND cargo_id IN ('latitude', 'longitude')
GROUP BY time, ship_id
ORDER BY time;

API Reference

HarborClient(endpoint, api_key, max_retries=5, initial_backoff=1.0)

Create a new client instance.

• endpoint (str): Telemetry Harbor ingestion URL.
• api_key (str): Your API key.
• max_retries (int, optional): Retry attempts on failure (default 5).
• initial_backoff (float, optional): Initial backoff in seconds (default 1.0).

send(reading: GeneralReading)

Send a single telemetry reading.

send_batch(readings: List[GeneralReading])

Send multiple readings in a batch.