Skip to main content

IDs, mapping, and coordinates

Most integrations join XY Sense data to an external system: a workplace app, a BMS, a digital twin, or a BI model. This page covers the identifier and coordinate semantics that make that join reliable.

Identifiers are stable, names are labels​

  • Every entity (building, floor, floor space, sensor, entry) has a GUID id. IDs are stable for the life of the entity, so they are the right key to store in your system.
  • Names, descriptions, and space types are display metadata and can be edited at any time. Treat them as labels to show, rather than keys to join on.
  • Reference data changes as workplaces change: spaces are added, renamed, recategorised, and retired. Refresh your cached reference data periodically (daily is a good default) and treat an unknown floorSpaceId in an event as a signal to refresh.

Mapping to your own system​

  1. Pull the portfolio once with a discovery query (see Building and floor discovery).
  2. Match each XY Sense space to your system's equivalent. A shared naming convention makes the first pass automatic, and names can then change freely afterwards because your stored link is by id.
  3. Store the XY Sense id against your entity and join all events, polling results, and analytics rows on it.

The floor plan coordinate system​

Every floor has a floorPlanUrl (the floor plan image) and a scale.

  • Coordinates are expressed in centimetres from the top-left corner of the floor plan, with x increasing to the right and y increasing downward.
  • Floor space shapes are polygons of points in this coordinate system.
  • Floor sightings are x/y points in the same system.
  • scale is the floor plan's resolution in centimetres per image pixel. To place a coordinate on the floor plan image, divide by scale:
pixelX = x / scale
pixelY = y / scale

The same conversion works in reverse (cm = pixels * scale) when translating a position picked on the image back to sensor coordinates.

Coordinates in analytics and heatmaps​

Historical heatmap cells use the same centimetre coordinate system, so a heatmap overlay and a live sightings overlay can share one rendering path. See Historical heatmap for a worked rendering example.