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, *, dynamic=False, tag_uid=None, **fields) Create a zone; for dynamic zones, bind a tag in the same call. Geometry (shape, points, radius_m) is passed through **fields.
client.zones.update(uid, *, tag_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(start, end) Time series of geometry changes in the window.
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,
    tag_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 tag_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, tag_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.
tag_uid str \| None The bound tag's uid (dynamic only).

Geometry inputs (points, radius_m) are accepted on create via **fields but are not surfaced as typed fields on the returned Zone.

Full field list.

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

See also

  • Error handling — PartialFailureError.failed_step strings: create_zone, set_tag_binding, load_zone, clear_old_binding, set_new_binding, update_zone.
  • Compound workflows — the dynamic-zone binding saga.