taglogger-sdk 1.0.0__py3-none-any.whl

taglogger_sdk/__init__.py

@@ -0,0 +1,55 @@
+"""Official Python SDK for the TagLogger API.
+
+Quick start::
+
+    from taglogger_sdk import TagLoggerClient
+
+    client = TagLoggerClient(api_key="tl_live_...")
+    for tag in client.tags.iterate():
+        print(tag["id"], tag.get("name"))
+
+The :mod:`taglogger_sdk.analytics` subpackage bundles a pure-math, client-side
+location-analytics toolkit (conditioning, stops/trips, dwell, clustering,
+GeoJSON/polyline shaping, battery projection) that runs entirely in-process.
+"""
+
+from . import analytics
+from .client import TagLoggerClient
+from .errors import TagLoggerError
+from .http import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RESPONSE_BYTES,
+    SDK_VERSION,
+    HttpClient,
+    HttpResponse,
+    Transport,
+    make_default_transport,
+)
+from .pagination import Paginator
+from .webhooks import (
+    SIGNATURE_HEADER,
+    compute_webhook_signature,
+    construct_webhook_event,
+    verify_webhook_signature,
+)
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "__version__",
+    "TagLoggerClient",
+    "TagLoggerError",
+    "HttpClient",
+    "HttpResponse",
+    "Transport",
+    "make_default_transport",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_MAX_RESPONSE_BYTES",
+    "SDK_VERSION",
+    "Paginator",
+    "compute_webhook_signature",
+    "verify_webhook_signature",
+    "construct_webhook_event",
+    "SIGNATURE_HEADER",
+    "analytics",
+]

taglogger_sdk/analytics/__init__.py

@@ -0,0 +1,110 @@
+"""Bundled client-side analytics for TagLogger location data.
+
+Pure-math helpers that run entirely in-process over the location data you
+already hold — no network calls, no provider dependencies. The typical pipeline
+is: condition the raw fixes, then segment, cluster, or shape them.
+
+Example::
+
+    from taglogger_sdk.analytics import (
+        condition_fixes,
+        detect_stops,
+        detect_trips,
+        fixes_from_location_points,
+    )
+
+    page = client.tags.history("tag-1")
+    fixes = fixes_from_location_points(page["data"])
+    clean = condition_fixes(fixes, max_accuracy_meters=100)
+    stops = detect_stops(clean, radius_meters=50, min_duration_ms=300000)
+    trips = detect_trips(clean, stops)
+"""
+
+from .battery import BatteryEstimate, estimate_battery_days_remaining
+from .conditioning import condition_fixes, dedupe_by_timestamp, sort_by_time
+from .geometry import (
+    EARTH_RADIUS_METERS,
+    bearing_degrees,
+    bounding_box,
+    centroid,
+    decode_polyline,
+    douglas_peucker,
+    encode_polyline,
+    haversine_meters,
+    is_within_radius,
+    path_length_meters,
+    point_in_polygon,
+)
+from .segmentation import (
+    cluster_fixes,
+    compute_dwell,
+    detect_stops,
+    detect_trips,
+)
+from .shaping import (
+    fixes_to_feature,
+    stop_to_feature,
+    to_feature_collection,
+    to_line_string,
+    to_point,
+    to_polyline,
+    trip_to_feature,
+)
+from .types import (
+    BatterySample,
+    BoundingBox,
+    Cluster,
+    DwellInterval,
+    Fix,
+    LatLng,
+    Stop,
+    Trip,
+    fix_from_location_point,
+    fixes_from_location_points,
+)
+
+__all__ = [
+    # types
+    "LatLng",
+    "Fix",
+    "Stop",
+    "Trip",
+    "Cluster",
+    "DwellInterval",
+    "BoundingBox",
+    "BatterySample",
+    "BatteryEstimate",
+    "fix_from_location_point",
+    "fixes_from_location_points",
+    # geometry
+    "EARTH_RADIUS_METERS",
+    "haversine_meters",
+    "bearing_degrees",
+    "centroid",
+    "bounding_box",
+    "path_length_meters",
+    "point_in_polygon",
+    "is_within_radius",
+    "douglas_peucker",
+    "encode_polyline",
+    "decode_polyline",
+    # conditioning
+    "sort_by_time",
+    "dedupe_by_timestamp",
+    "condition_fixes",
+    # segmentation
+    "detect_stops",
+    "detect_trips",
+    "compute_dwell",
+    "cluster_fixes",
+    # shaping
+    "to_line_string",
+    "to_point",
+    "to_polyline",
+    "trip_to_feature",
+    "stop_to_feature",
+    "to_feature_collection",
+    "fixes_to_feature",
+    # battery
+    "estimate_battery_days_remaining",
+]

taglogger_sdk/analytics/battery.py

@@ -0,0 +1,102 @@
+"""Battery trend estimation. Given a history of timestamped battery levels, fit
+a simple least-squares line and project when the level reaches zero.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from .types import BatterySample
+
+_MS_PER_DAY = 24 * 60 * 60 * 1000
+
+
+@dataclass(frozen=True)
+class BatteryEstimate:
+    """The outcome of a battery projection."""
+
+    #: Estimated days until the level reaches zero, or None if undetermined.
+    days_remaining: float | None
+    #: Modeled drain in level-units per day (positive means discharging).
+    drain_per_day: float | None
+    #: The most recent level the estimate is anchored to, normalized to [0, 1].
+    current_level: float | None
+    #: Why a projection could not be made, when days_remaining is None:
+    #: "insufficient_data", "not_discharging", or "degenerate_time".
+    reason: str | None = None
+
+
+def _normalize_level(level: float) -> float:
+    """Normalize a level given as a 0–1 fraction or a 0–100 percentage to [0, 1]."""
+    v = level / 100 if level > 1 else level
+    return max(0.0, min(1.0, v))
+
+
+def estimate_battery_days_remaining(
+    samples: Sequence[BatterySample],
+) -> BatteryEstimate:
+    """Estimate remaining battery life by least-squares fit of level against time.
+
+    Levels may be supplied as fractions (0–1) or percentages (0–100); the two
+    are detected per-sample and normalized. At least two readings at distinct
+    times are required. When the trend is flat or charging, ``days_remaining`` is
+    None with an explanatory ``reason``.
+    """
+    clean = sorted(
+        (
+            {"level": _normalize_level(s.level), "t": s.timestamp_ms}
+            for s in samples
+            if math.isfinite(s.level) and math.isfinite(s.timestamp_ms)
+        ),
+        key=lambda s: s["t"],
+    )
+
+    if len(clean) < 2:
+        return BatteryEstimate(
+            days_remaining=None,
+            drain_per_day=None,
+            current_level=clean[-1]["level"] if clean else None,
+            reason="insufficient_data",
+        )
+
+    t0 = clean[0]["t"]
+    # Regress level on elapsed days for numerically stable slope units.
+    xs: list[float] = [(s["t"] - t0) / _MS_PER_DAY for s in clean]
+    ys: list[float] = [s["level"] for s in clean]
+    n = len(clean)
+    mean_x = sum(xs) / n
+    mean_y = sum(ys) / n
+    sxx = 0.0
+    sxy = 0.0
+    for i in range(n):
+        dx = xs[i] - mean_x
+        sxx += dx * dx
+        sxy += dx * (ys[i] - mean_y)
+
+    current_level = ys[n - 1]
+    if sxx == 0:
+        return BatteryEstimate(
+            days_remaining=None,
+            drain_per_day=None,
+            current_level=current_level,
+            reason="degenerate_time",
+        )
+
+    slope_per_day = sxy / sxx  # level change per day; negative while draining
+    drain_per_day = -slope_per_day
+    if drain_per_day <= 0:
+        return BatteryEstimate(
+            days_remaining=None,
+            drain_per_day=drain_per_day,
+            current_level=current_level,
+            reason="not_discharging",
+        )
+
+    days_remaining = current_level / drain_per_day
+    return BatteryEstimate(
+        days_remaining=days_remaining,
+        drain_per_day=drain_per_day,
+        current_level=current_level,
+    )

taglogger_sdk/analytics/conditioning.py

@@ -0,0 +1,80 @@
+"""Conditioning: turn a raw series of reported positions into a clean, ordered
+series suitable for segmentation and clustering.
+
+Reported positions arrive on an irregular, roughly five-minute cadence and may
+be out of order, share timestamps, or carry coarse accuracy. Every other
+analytics function assumes its input has already passed through here.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+
+from .types import Fix
+
+
+def sort_by_time(fixes: Sequence[Fix]) -> list[Fix]:
+    """Stable sort of fixes by ascending timestamp. Does not mutate the input."""
+    # Python's sort is guaranteed stable, so equal timestamps keep input order.
+    return sorted(fixes, key=lambda fix: fix.timestamp_ms)
+
+
+def _accuracy_of(fix: Fix) -> float:
+    accuracy = fix.accuracy
+    if isinstance(accuracy, (int, float)) and math.isfinite(accuracy):
+        return float(accuracy)
+    return math.inf
+
+
+def dedupe_by_timestamp(fixes: Sequence[Fix]) -> list[Fix]:
+    """Collapse fixes that share a timestamp, keeping the most accurate one.
+
+    Ties resolve to the earliest in input order. Assumes the input is already
+    time-sorted.
+    """
+    out: list[Fix] = []
+    for fix in fixes:
+        last = out[-1] if out else None
+        if last is not None and last.timestamp_ms == fix.timestamp_ms:
+            if _accuracy_of(fix) < _accuracy_of(last):
+                out[-1] = fix
+            continue
+        out.append(fix)
+    return out
+
+
+def condition_fixes(
+    fixes: Sequence[Fix],
+    *,
+    max_accuracy_meters: float = math.inf,
+    drop_inaccurate: bool = False,
+    drop_old: bool = False,
+    dedupe: bool = True,
+) -> list[Fix]:
+    """Filter, dedupe, and time-order a raw series in one pass.
+
+    Coordinates that are not finite numbers are always dropped. Returns a fresh
+    list.
+
+    A fix whose ``accuracy`` is unknown (missing or non-finite) is treated as
+    infinitely coarse, so any finite ``max_accuracy_meters`` drops it. This is
+    intentional: the bound keeps only fixes known to be accurate enough. Leave
+    ``max_accuracy_meters`` at its default (no bound) to keep fixes regardless
+    of reported accuracy.
+    """
+    kept: list[Fix] = []
+    for fix in fixes:
+        if not math.isfinite(fix.lat) or not math.isfinite(fix.lng):
+            continue
+        if not math.isfinite(fix.timestamp_ms):
+            continue
+        if _accuracy_of(fix) > max_accuracy_meters:
+            continue
+        if drop_inaccurate and fix.is_inaccurate:
+            continue
+        if drop_old and fix.is_old:
+            continue
+        kept.append(fix)
+    ordered = sort_by_time(kept)
+    return dedupe_by_timestamp(ordered) if dedupe else ordered

taglogger_sdk/analytics/geometry.py

@@ -0,0 +1,260 @@
+"""Geographic primitives: distances, bearings, simplification, and the polyline
+codec. All distances are in meters on a spherical-earth model.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from typing import TypeVar
+
+from .types import BoundingBox, LatLng
+
+#: Mean earth radius in meters (spherical model).
+EARTH_RADIUS_METERS = 6371000
+
+_DEG_TO_RAD = math.pi / 180
+
+T = TypeVar("T", bound=LatLng)
+
+
+def _round_half_up(value: float) -> int:
+    """Round half away from +infinity, matching JavaScript ``Math.round``.
+
+    Python's built-in ``round`` uses banker's rounding, which would diverge from
+    the reference implementation on ``.5`` boundaries; ``floor(x + 0.5)`` matches.
+    """
+    return math.floor(value + 0.5)
+
+
+def haversine_meters(a: LatLng, b: LatLng) -> float:
+    """Great-circle distance between two coordinates, in meters."""
+    lat1 = a.lat * _DEG_TO_RAD
+    lat2 = b.lat * _DEG_TO_RAD
+    d_lat = (b.lat - a.lat) * _DEG_TO_RAD
+    d_lng = (b.lng - a.lng) * _DEG_TO_RAD
+    sin_lat = math.sin(d_lat / 2)
+    sin_lng = math.sin(d_lng / 2)
+    h = sin_lat * sin_lat + math.cos(lat1) * math.cos(lat2) * sin_lng * sin_lng
+    return 2 * EARTH_RADIUS_METERS * math.asin(min(1.0, math.sqrt(h)))
+
+
+def bearing_degrees(a: LatLng, b: LatLng) -> float:
+    """Initial bearing from ``a`` to ``b``, in degrees clockwise from north [0, 360)."""
+    lat1 = a.lat * _DEG_TO_RAD
+    lat2 = b.lat * _DEG_TO_RAD
+    d_lng = (b.lng - a.lng) * _DEG_TO_RAD
+    y = math.sin(d_lng) * math.cos(lat2)
+    x = math.cos(lat1) * math.sin(lat2) - math.sin(lat1) * math.cos(lat2) * math.cos(d_lng)
+    deg = math.atan2(y, x) / _DEG_TO_RAD
+    return (deg + 360) % 360
+
+
+def centroid(points: Sequence[LatLng]) -> LatLng:
+    """Component-wise mean of a set of coordinates. Raises on an empty input.
+
+    This is a plain arithmetic mean of latitude and longitude. For points within
+    a single region (the normal case for one tag's track) it is the expected
+    center; it is not the true spherical centroid for sets that straddle the
+    +/-180 degree antimeridian or sit at a pole.
+    """
+    if len(points) == 0:
+        raise ValueError("centroid requires at least one point")
+    sum_lat = 0.0
+    sum_lng = 0.0
+    for p in points:
+        sum_lat += p.lat
+        sum_lng += p.lng
+    return LatLng(lat=sum_lat / len(points), lng=sum_lng / len(points))
+
+
+def bounding_box(points: Sequence[LatLng]) -> BoundingBox:
+    """Smallest axis-aligned box containing every point. Raises on an empty input."""
+    if len(points) == 0:
+        raise ValueError("bounding_box requires at least one point")
+    min_lat = math.inf
+    min_lng = math.inf
+    max_lat = -math.inf
+    max_lng = -math.inf
+    for p in points:
+        if p.lat < min_lat:
+            min_lat = p.lat
+        if p.lat > max_lat:
+            max_lat = p.lat
+        if p.lng < min_lng:
+            min_lng = p.lng
+        if p.lng > max_lng:
+            max_lng = p.lng
+    return BoundingBox(min_lat=min_lat, min_lng=min_lng, max_lat=max_lat, max_lng=max_lng)
+
+
+def path_length_meters(points: Sequence[LatLng]) -> float:
+    """Cumulative great-circle length along an ordered path, in meters."""
+    total = 0.0
+    for i in range(1, len(points)):
+        total += haversine_meters(points[i - 1], points[i])
+    return total
+
+
+def point_in_polygon(point: LatLng, polygon: Sequence[LatLng]) -> bool:
+    """Even-odd ray-casting point-in-polygon test.
+
+    The polygon is a ring of coordinates; it need not repeat its first point.
+    Points exactly on an edge are reported deterministically but their
+    classification is not guaranteed.
+    """
+    if len(polygon) < 3:
+        return False
+    y = point.lat
+    x = point.lng
+    inside = False
+    j = len(polygon) - 1
+    for i in range(len(polygon)):
+        xi = polygon[i].lng
+        yi = polygon[i].lat
+        xj = polygon[j].lng
+        yj = polygon[j].lat
+        intersects = (yi > y) != (yj > y) and x < (xj - xi) * (y - yi) / (yj - yi) + xi
+        if intersects:
+            inside = not inside
+        j = i
+    return inside
+
+
+def is_within_radius(point: LatLng, center: LatLng, radius_meters: float) -> bool:
+    """Whether a coordinate lies within ``radius_meters`` of a center."""
+    return haversine_meters(point, center) <= radius_meters
+
+
+def _perpendicular_distance_meters(p: LatLng, a: LatLng, b: LatLng) -> float:
+    """Perpendicular distance from ``p`` to segment ``a``–``b``, in meters.
+
+    Uses a local equirectangular projection, accurate for the short segments
+    simplification works on.
+    """
+    lat_ref = (a.lat + b.lat) / 2 * _DEG_TO_RAD
+    m_per_deg_lat = (math.pi / 180) * EARTH_RADIUS_METERS
+    m_per_deg_lng = m_per_deg_lat * math.cos(lat_ref)
+    ax = a.lng * m_per_deg_lng
+    ay = a.lat * m_per_deg_lat
+    bx = b.lng * m_per_deg_lng
+    by = b.lat * m_per_deg_lat
+    px = p.lng * m_per_deg_lng
+    py = p.lat * m_per_deg_lat
+    dx = bx - ax
+    dy = by - ay
+    seg_len_sq = dx * dx + dy * dy
+    if seg_len_sq == 0:
+        return math.hypot(px - ax, py - ay)
+    t = ((px - ax) * dx + (py - ay) * dy) / seg_len_sq
+    clamped = max(0.0, min(1.0, t))
+    proj_x = ax + clamped * dx
+    proj_y = ay + clamped * dy
+    return math.hypot(px - proj_x, py - proj_y)
+
+
+def douglas_peucker(points: Sequence[T], epsilon_meters: float) -> list[T]:
+    """Ramer–Douglas–Peucker path simplification.
+
+    Keeps the endpoints and any vertex farther than ``epsilon_meters`` from the
+    running approximation. Returns the input unchanged when it has two or fewer
+    points.
+
+    Uses an explicit work stack rather than recursion, so a long path that
+    retains most of its vertices cannot exhaust Python's recursion limit.
+
+    Cost is ``O(n log n)`` on typical tracks but degrades to ``O(n**2)`` in the
+    worst case -- a path that keeps nearly every vertex, such as a dense zig-zag.
+    For very large inputs, down-sample first or raise ``epsilon_meters`` to bound
+    the work.
+    """
+    n = len(points)
+    if n <= 2:
+        return list(points)
+    keep = [False] * n
+    keep[0] = True
+    keep[n - 1] = True
+    # Each stack entry is an inclusive [lo, hi] index range whose interior is
+    # yet to be tested against the lo-hi chord.
+    stack: list[tuple[int, int]] = [(0, n - 1)]
+    while stack:
+        lo, hi = stack.pop()
+        max_dist = 0.0
+        index = -1
+        for i in range(lo + 1, hi):
+            dist = _perpendicular_distance_meters(points[i], points[lo], points[hi])
+            if dist > max_dist:
+                max_dist = dist
+                index = i
+        if index != -1 and max_dist > epsilon_meters:
+            keep[index] = True
+            stack.append((lo, index))
+            stack.append((index, hi))
+    return [points[i] for i in range(n) if keep[i]]
+
+
+def encode_polyline(points: Sequence[LatLng], precision: int = 5) -> str:
+    """Encode an ordered path using the standard polyline algorithm.
+
+    ``precision`` is the number of decimal digits preserved (5 is the common
+    default).
+
+    Raises ``ValueError`` if any coordinate is not finite (``nan``/``inf``),
+    since the codec cannot represent it and would otherwise emit corrupt output.
+    """
+    factor = 10**precision
+    last_lat = 0
+    last_lng = 0
+    out: list[str] = []
+
+    def encode(value: int) -> str:
+        v = ~(value << 1) if value < 0 else (value << 1)
+        chunk = ""
+        while v >= 0x20:
+            chunk += chr((0x20 | (v & 0x1F)) + 63)
+            v >>= 5
+        chunk += chr(v + 63)
+        return chunk
+
+    for p in points:
+        if not math.isfinite(p.lat) or not math.isfinite(p.lng):
+            raise ValueError("encode_polyline requires finite lat/lng coordinates")
+        lat = _round_half_up(p.lat * factor)
+        lng = _round_half_up(p.lng * factor)
+        out.append(encode(lat - last_lat))
+        out.append(encode(lng - last_lng))
+        last_lat = lat
+        last_lng = lng
+    return "".join(out)
+
+
+def decode_polyline(encoded: str, precision: int = 5) -> list[LatLng]:
+    """Decode a polyline string back into coordinates. Inverse of :func:`encode_polyline`."""
+    factor = 10**precision
+    points: list[LatLng] = []
+    index = 0
+    lat = 0
+    lng = 0
+    length = len(encoded)
+
+    def read(start: int) -> tuple[int, int]:
+        result = 0
+        shift = 0
+        i = start
+        while True:
+            byte = ord(encoded[i]) - 63
+            i += 1
+            result |= (byte & 0x1F) << shift
+            shift += 5
+            if byte < 0x20:
+                break
+        delta = ~(result >> 1) if (result & 1) else (result >> 1)
+        return delta, i
+
+    while index < length:
+        d_lat, index = read(index)
+        lat += d_lat
+        d_lng, index = read(index)
+        lng += d_lng
+        points.append(LatLng(lat=lat / factor, lng=lng / factor))
+    return points