Developer API
Developer APILibraries & ToolsPython

Python

The official TagLogger SDK for Python 3.9+

Install

The taglogger-sdk package is the official Python SDK for the TagLogger API. It is synchronous, fully type-hinted (ships py.typed), has zero runtime dependencies (standard library only), and supports Python 3.9 and up. A single client instance carries no mutable per-call state, so it is safe to share across threads.

pip install taglogger-sdk

The distribution installs as taglogger-sdk; you import it as taglogger_sdk.

Keep your API key on a server you control. Treat tl_live_ keys like passwords and load them from the environment, never from source.

Quick start

import os
from taglogger_sdk import TagLoggerClient

client = TagLoggerClient(api_key=os.environ["TAGLOGGER_API_KEY"])

# One page of tags (envelope: { "data": [...], "nextCursor": ... })
page = client.tags.list(
    limit=50,
    label="Coca-Cola",
)
for tag in page["data"]:
    print(tag["id"], tag.get("name"))

# Or stream every tag, paging transparently
for tag in client.tags.iterate():
    print(tag["id"])

# Latest location for one tag -> { "data": point | None, "recordingPaused": bool }
location = client.tags.location("tag-1")
print(location["data"], "recording paused:", location["recordingPaused"])

Returned tag and fleet objects include the read-only originalPhysicalLabel when TagLogger has a safely recorded label from original shipment or provisioning. It remains stable when name or a later sticker changes.

Get an API key from your dashboard under Settings → API Keys. Keys are scoped; each method documents the scope it needs in the package README.

Configuration

client = TagLoggerClient(
    api_key="tl_live_...",
    base_url="https://api.taglogger.com",  # override to target a staging deployment
    auth_header="bearer",                   # "bearer" (default) or "x-api-key"
    timeout_ms=30000,
    max_retries=2,                          # GET/DELETE retried on 5xx/network; any method retried on 429
)

Transient failures retry with randomized backoff: network errors and 5xx on idempotent methods (GET/DELETE), and 429 on any method (honoring Retry-After). Non-idempotent writes are never silently retried after a transport failure.

Reading tags and locations

# A single tag, its battery, and its current location
tag = client.tags.get("tag-1")             # read:tags
client.tags.update("tag-1", {              # manage:tags
    "name": "Main warehouse AED",
    "labels": ["Coca-Cola", "Seattle", "AED-0042"],
    "recordingPause": {"paused": True, "until": None, "reason": "Maintenance"},
})
battery = client.tags.battery("tag-1")     # read:tags
point = client.tags.location("tag-1")["data"]  # read:locations

# Location history (start/end accept ISO 8601 or epoch ms)
page = client.tags.history("tag-1", order="asc", limit=500)

# Incremental, whole-fleet sync — pass last sync's high-water mark as 'since'
cursor = None
while True:
    delta = client.fleet.delta(since=last_sync, cursor=cursor)
    handle(delta["data"])
    cursor = delta["nextCursor"]
    if not cursor:
        break

Every list endpoint has a matching iterate* helper that returns a Paginator — iterate it for items, call .pages() for a page at a time, or .all() to collect everything. Pages are fetched lazily, so a large collection never has to fit in memory.

Geofences, webhooks and share links

# Create a geofence (manage:geofences; recipient lists also need read:locations)
gf = client.geofences.create({
    "name": "Yard",
    "center": {"lat": 37.77, "lng": -122.42},
    "radiusMeters": 150,
    "targetTagIds": ["tag-1", "tag-2"],
    "alerts": {"onEntry": True, "emailEnabled": True,
               "emailAddresses": ["dispatch@example.com"]},
})

# Polygons and corridors (a band around a route); every geofence has a "type"
depot = {
    "name": "Depot",
    "type": "polygon",
    "vertices": [{"lat": 37.770, "lng": -122.420}, {"lat": 37.770, "lng": -122.410},
                 {"lat": 37.776, "lng": -122.415}],
    "targetTagIds": ["all"],
}
route = {
    "name": "Route 1",
    "type": "corridor",
    "path": [{"lat": 37.77, "lng": -122.42}, {"lat": 37.80, "lng": -122.27}],
    "widthMeters": 1000,  # full band width, 500-20000 m
    "targetTagIds": ["tag-1"],
}

# Up to 450 geofences in one all-or-nothing transaction (manage:geofences)
created = client.geofences.bulk_create([depot, route], idempotency_key="import-2026-10-01")

# Each tag's visits: entered, exited (None while still inside), duration, a page of tags at a time
# (read:geofences + read:locations; the workspace needs the geofence time report)
cursor = None
while True:
    visits = client.geofences.visits(
        gf["id"], from_="2026-10-01T00:00:00Z", to="2026-10-08T00:00:00Z", limit=50, cursor=cursor
    )
    for t in visits["tags"]:
        print(t["tagId"], t["visitCount"], t["totalMs"])
    cursor = visits["nextCursor"]
    if cursor is None:
        break

# Create a multi-tag Customer Page (manage:customer-pages)
page = client.customer_pages.create({
    "pageName": "Operations",
    "tagIds": ["tag-1", "tag-2"],
    "expiresAt": None,
    "features": {"liveMap": True, "zones": True,
                 "statusTable": True, "zoneActivity": True,
                 "locationHistory": False,  # opt-in per-tag trail; needs liveMap
                 "labels": False},
})

# Subscribe to a webhook (manage:webhooks)
webhook = client.webhooks.create({
    "url": "https://example.com/hooks/taglogger",
    "events": ["geofence.entry", "geofence.exit", "tag.offline"],
})
secret = webhook["signingSecret"]  # shown ONCE — store it now to verify deliveries

# Verify your endpoint right away
client.webhooks.send_test(webhook["id"])

The seven event types are geofence.entry, geofence.exit, geofence.dwell, tag.moved, tag.battery_low, tag.offline and security.event (company sign-in events; needs read:security-events). See Set up Webhooks for the full event catalog and delivery details.

Geofence shapes and saving pauses

A circle is center plus radiusMeters (10 to 100,000 m), a polygon is 3 to 500 vertices in order, and a corridor is a path of 2 to 1,000 points plus widthMeters. A polygon or corridor comes back with center as its label point and radiusMeters set to None. Visits default to the 7 days before to (default now) and can span at most 400 days.

Visits work the same for circles, polygons and corridors and come a page of tags at a time (limit default 10, at most 100). While nextCursor is not None, call again with it as cursor and the same from_, to and tag_ids (the window the first page returned, if you left it out); another window or tag_ids fails with status 400 and code invalid_cursor. Tags come in tag id order, and a page can hold fewer than limit tags and still have a next page. A page whose window holds too many recorded locations fails with status 422 and code window_too_large: choose a shorter window or a smaller limit. The API answers a page within 75 seconds (503 service_unavailable after that), so visits waits at least 90 seconds per attempt whatever timeout_ms is. bulk_create waits as long, since the API can take up to 75 seconds to save a bulk.

An update without type edits the current shape and must fit it: center and/or radiusMeters on a circle, vertices on a polygon, path and widthMeters together on a corridor. An update with type and that shape's fields replaces the shape whole. Anything else is 400 invalid_geofence.

A geofence write can fail with status 503 service_unavailable: the store did not answer and the write may have landed. Wait err.retry_after_seconds and send the request again. With an idempotency_key, retrying a create or bulk create after service_unavailable is safe: send the same key and body, and the retry returns the same geofences and never writes them twice. Without a key, list geofences before retrying a create. If a geofence the key created was edited since, or the key comes back with a different body after 24 hours, the create fails with 409 conflict, so send a new key with each new request. A bulk create is one transaction, all or nothing. The client retries a delete that fails with a 5xx by itself, but never a create or an update.

Verifying incoming webhooks

Every delivery carries an X-TagLogger-Signature header (sha256=<hex>, an HMAC-SHA256 of the raw request body). Verify against the raw bytes before trusting the payload — re-serializing the JSON changes the bytes and fails the check.

from taglogger_sdk import construct_webhook_event, SIGNATURE_HEADER, TagLoggerError

# Flask example
@app.post("/hooks/taglogger")
def handle():
    raw = request.get_data()  # raw bytes, not request.json
    try:
        event = construct_webhook_event(raw, request.headers.get(SIGNATURE_HEADER), WEBHOOK_SECRET)
    except TagLoggerError:
        return "", 400  # invalid_signature or invalid_body
    # event is the parsed payload, e.g. {"event": "geofence.entry", ...}
    return "", 200

verify_webhook_signature(raw_body, signature, secret) is the lower-level check; it returns False (never raises) on a missing header or mismatch.

Analytics toolkit

The package bundles taglogger_sdk.analytics, a dependency-free, pure-math toolkit that turns the location data the API returns into stops, trips, dwell intervals, clusters and map-ready shapes. Everything runs locally, in-process — nothing is sent anywhere.

from taglogger_sdk.analytics import (
    fixes_from_location_points,
    condition_fixes,
    detect_stops,
    detect_trips,
    to_feature_collection,
)

# Pull a tag's history, then analyze it in-process
page = client.tags.history("tag-1", order="asc", limit=500)
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=300_000)  # 5 min
trips = detect_trips(clean, stops)

geojson = to_feature_collection(trips=trips, stops=stops)  # ready for any map

The toolkit also exposes conditioning (sort_by_time, dedupe_by_timestamp), DBSCAN cluster_fixes, geometry primitives (haversine_meters, point_in_polygon, douglas_peucker, encode_polyline), and estimate_battery_days_remaining for battery projection from a series of readings.

is_inside_geofence(point, geofence) takes a geofence dict as the API returns it and follows the same rules TagLogger alerts use: polygon edges are straight lines on the map, and a corridor covers widthMeters / 2 on each side of its route. compute_dwell(fixes, geofence) accepts any geofence shape.

Error handling

Any non-2xx response, or a transport failure, raises TagLoggerError with a stable code, status (0 for transport failures), request_id, is_rate_limit and retry_after_seconds.

See also