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:
breakEvery 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 "", 200verify_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 mapThe 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.