Data model

All three APIs share one model. An account owns sites; each site has a layout of floors, layers and items, and a set of devices: tags, base stations and accessories. Positions are expressed in the site’s own coordinate system.

Glossary: API terms and website terms

The API was designed before some of today’s product names, so a few terms differ from the rest of this website.

API term	Meaning	Website term
Account	The owner of one or more sites, such as a company	Customer account
Site	A physical location with installed base stations and a layout, such as a factory or a warehouse	Site
Tag	A device that the system locates: badge, asset tag, call button	Tag
Beacon, sensor, anchor	A fixed device that ranges with tags	Base station
Device ID	The serial number printed on the device label, as text and barcode	Device ID
App	One set of API credentials	App
Client	A running instance of an app that holds a token	Client
External tag	A tag whose position is supplied through the API rather than measured	External tag

Accounts and sites

API requests name the site with two integers, Account and Site (in some request bodies account and site). A site ID is unique only within its account, so always send both. An app’s permissions are granted per site: GET /info lists the sites your app can reach.

Layout: floors, layers and items

A site’s layout is versioned. Each saved change creates a new layout version, identified by majorId/majorNumber and minorId/minorNumber; older versions can be listed and activated again. The layout can also carry the site’s latitude, longitude and azimuth angle.

Layout (version)
└── Floors[]          name, permanentId
    └── Layers[]      id, permanentId, name, type, visible
        └── Items[]   id, permanentId, type, coordinates, file or device reference

Floors are identified by permanentId. Tag positions and base station positions refer to a floor through floorId, which matches this ID.

Layers group items. The main kinds are:

• Infrastructure layers hold the base stations of the floor, one such layer per floor.
• Blueprint layers (type 2) hold floor-plan images. A floor can have none, one or several.
• Area layers hold rectangles, circles and polygons used as zones for events and alerts.

Items carry a type:

Type	Item	Type	Item
1	Scale grid	10	Power
2	Blueprint	11	Device
3	Anchor (base station)	12	Tag
4	Rectangle	13	Wall
5	Circle	14	Route detector
6	Polygon	16	Entrance point
8	Camera	17	Area group
9	Ethernet

Items have a bounding box (minX, maxX, minY, maxY, and for some minZ, maxZ), and depending on type an angle, a radius, polygonPoints, a fileId for images, or a deviceId for devices.

The area IDs that appear in tag states and Push API events refer to the area items of the layout, so fetch the layout to turn an area ID into a name and a shape.

Devices

Every device has a device ID, its serial number. Device types are infrastructure devices such as base stations, tags, charging docks and local servers. Each device also reports a deviceModel, an enumerated hardware model name; treat unknown values as “other” so that new models do not break your code.

Tag state

The full state of a tag, as returned by initialTagState and updated by tagDiffStream (which sends only the changed fields):

Field	Type	Meaning
deviceId	integer	Serial number of the tag
name	string	Name given to the tag
x, y, z	integer	Position in site coordinates; z is height above the floor
floorId	integer	Floor the tag is on (a floor permanentId)
uncertaintyDistance	integer	If present, the real position lies within this radius of x, y
timestamp	integer	Time of the state, in milliseconds since the Unix epoch
areas	integer array	IDs of the areas the tag is currently in
isOnline	boolean	Whether the state is current or the last known one
accelerometer	boolean	Whether the tag is moving
powerSave	boolean	Set just before the tag goes to sleep; cleared when it wakes
signalLost	boolean	The tag disappeared without going to sleep normally
batteryVoltage	integer	Battery voltage in millivolts
batteryStatus	enumeration	0 unknown, 1 OK, 2 low, 3 empty
batteryPercentage	integer	Charge level, on devices that report it
inCharger	boolean	Badge is in a charging dock
status	enumeration	Tag role, for example 7 assistance-request (call) tag, 8 badge
deviceModel	enumeration	Hardware model
fwVersion	string	Firmware version
strokeCount	integer	Counter for industrial use, only if enabled
wire, reed	boolean	State of wire and magnetic sensor inputs, on tags that have them

Coordinates and units

• Site-local, not geographic. Each site has its own Cartesian coordinate system with an origin chosen when the site was set up. Coordinates have no meaning outside their site. Use the layout’s latitude, longitude and azimuth if you need to place a site on a map.
• Integers. x, y and z are integers. In site coordinates y grows upwards, so flip it when you draw on an image, where y grows downwards.
• Same system everywhere. Tag positions, base station positions, layout items and blueprint extents all use the same coordinates. To draw positions on a floor plan, scale them by the blueprint item’s minX…maxX and minY…maxY (see the quickstart).
• Height. z is measured from the current floor, not from the ground.
• Distances in streams. Peer-to-peer and tag-to-base-station distance streams report millimetres; proximity (contact) events report the closest distance in centimetres.
• Time. Timestamps are Unix time. Positions, states and events use milliseconds; the tokenExpiration and tokenIssued fields of authentication messages use seconds.

The length unit of x, y and z is not part of the published API description. Confirm it for your site before you compute speeds or distances from positions; you do not need it to draw positions on the floor plan.

History

Position history is filtered: a new row is stored only when a tag has moved more than 0.5 m from its previous stored position. For every update, use the real-time API; for analysis over hours and days, use GET /history.