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.

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:

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 include infrastructure devices such as base stations, as well as 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):

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.