> For the complete documentation index, see [llms.txt](https://docs.butlr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.butlr.io/integrations-api-third-party-sensors/spots.md).

# Spots & Sensor Placement

## Spots

A **spot** is a single, named location on a floor that a sensor measures, for example one desk. Rooms and floors describe areas; a spot describes a point, so you can report on each desk and not only on the room it is in.

```
Site
└── Building
    └── Floor
        ├── Room
        │   └── Spot   ← e.g. "Desk 3A"
        └── Spot       ← a spot outside any room
```

* **Floor:** every spot belongs to one floor.
* **Room:** a spot's room is set automatically from where the spot sits on the floor plan. A spot outside every room has no room.
* **Spot type:** each spot has a type, such as `desk`.
* **IDs:** spot IDs start with `spot_`. They appear as the keys of spot-level results, and you can use them as [items](/integrations-api-third-party-sensors/reporting-api/items-and-fields.md#items).

To list the spots on a floor or in a room, query the `spots` field of a floor or room through the [GraphQL API](/asset-management/graphql-api-overview.md). The field is not yet shown on the Floors and Rooms pages, but it is available:

```graphql
query {
  floor(id: "space_XXXX") {
    spots { id name spotType roomID customID }
  }
}
```

## How sensors map to your spaces

Each third-party sensor is placed on a **floor**. Its **room** is determined by where it sits on the floor plan. A sensor can also be attached to a **spot**.

That placement determines where its data appears:

* **Spot-level** measurements (`spot_*`) include only sensors attached to a spot.
* **Room-level** measurements (`room_*`) include only sensors that fall inside a room.
* **Floor-level** measurements (`floor_*`) include every sensor on the floor.

Butlr installers manage placement. If a sensor's data is missing at a level, check its placement with your Butlr contact.

## IDs

| Entity   | ID prefix   | Example         |
| -------- | ----------- | --------------- |
| Site     | `site_`     | `site_XXXX`     |
| Building | `building_` | `building_XXXX` |
| Floor    | `space_`    | `space_XXXX`    |
| Room     | `room_`     | `room_XXXX`     |
| Spot     | `spot_`     | `spot_XXXX`     |

Site, building, floor, and room IDs are the same IDs used everywhere else in the Butlr API.

Per-sensor measurements ([temperature](/integrations-api-third-party-sensors/reporting-api/temperature.md) and [heartbeat](/integrations-api-third-party-sensors/reporting-api/device-heartbeat.md)) are keyed by the sensor's **device ID**, for example `abc123def456ghi789jk`.

Sensor IDs starting with `sensor3p_` appear in some responses (for example [touch events](/integrations-api-third-party-sensors/reporting-api/touch-events.md)) but cannot be used as `items`.