Skip to content

Zones

A zone is a geofence — polygon, circle, or rectangle — used by the RTLS to fire entry/exit events when tags move in or out. Zones come in two flavors: static (a fixed shape on the floorplan) and dynamic (the shape follows a tag's position).

Quick reference

Method What it does
client.zones.list() All zones in scope.
client.zones.get(uid) Fetch one zone by uid.
client.zones.create(name, shape, *, points=None, radius_m=None, dynamic=False, trackable_uid=None, **fields) Create a zone; for dynamic zones, bind a tag in the same call.
client.zones.update(uid, *, trackable_uid=None, **fields) Update; reconciles the dynamic-zone binding if it changed.
client.zones.delete(uid) Delete; clears any dynamic-zone reference on the bound tag.
client.zones.history(uid, *, start, end) Time series of geometry changes.
client.zones.list_custom_prototypes() Server-defined zone-type prototypes available in this deployment.
client.zones.create_raw / update_raw / delete_raw Single-call REST escape hatches.

Static vs dynamic zones

A static zone has a fixed shape (polygon points, circle radius). A dynamic zone is bound to a tag — the shape follows that tag's last known position. Useful for "exclusion bubble around the forklift" or "follow-the-operator" workflows.

# Static polygon
static = client.zones.create(
    name="Loading dock",
    shape="polygon",
    points=[(0, 0), (100, 0), (100, 50), (0, 50)],
)

# Dynamic: 5 m bubble that follows tag t-1
dynamic = client.zones.create(
    name="Forklift bubble",
    shape="circle",
    radius_m=5.0,
    dynamic=True,
    trackable_uid="t-1",
)

For a dynamic zone, create performs the zone-create + tags.update (setting self_zone_uid) in one compound call. Rollback on partial failure raises PartialFailureError.

Update — dynamic-zone re-binding

If trackable_uid changes on a dynamic zone, update clears the old binding and sets the new one — also a compound, also with rollback. The partial-failure case "old binding cleared but new binding failed" leaves completed_steps=["clear_old_binding"] so a retry knows where to resume.

client.zones.update(dynamic.uid, trackable_uid="t-2")

Delete

client.zones.delete(zone.uid)

For dynamic zones, delete also clears the tag's self_zone_uid reference. The *_raw variant deletes only the zone row — leaves a stale reference on the tag.

Model — Zone

Field Type Notes
uid str Server-assigned.
name str Required.
shape str \| None "polygon", "circle", etc.
dynamic bool True if the zone follows a tag.
trackable_object_uid str \| None The bound tag's uid (dynamic only).
points list \| None Polygon vertices.
radius_m float \| None Circle radius.

Full field list.

  • Tags: a dynamic zone's trackable_object_uid points at a Tag. tags.create(attached_zone=...) is the inverse helper.
  • Areas: zones live inside an Area (sublocation) via the sublocation_uid field.
  • Events: zone entry/exit fire as ZoneEvents — see Events.

See also

  • Error handling — PartialFailureError.step strings: create_zone, attach_tag, clear_old_binding, set_new_binding.
  • Compound workflows — the dynamic-zone binding saga.