The Occupancy API allows the submission of occupancy events to Calven. Occupancy events are reports on anonymous attendance for specific locations in Calven.

Examples of this are

A meeting room video camera counts 4 people in the room

An occupancy sensor for a phone booth reports that it is occupied

A desk sensor indicates that nobody is sitting at a desk

Occupancy Event Example

A presence event indicates:

That a particular location has a number of people in that location at a specific time

That a particular location is occupied/unoccupied at a specific time

The occupancy event API can be used to send historical events or current/real-time updates.

The first event below counts 3 people in a meeting room. The second reports that a desk is occupied.

{
  "sourceId": "My System",
  "occupancyEvents": [
    {
      "timestamp": "2023-05-15T10:22:45Z",
      "locationId": "D0FA9F18-6E7F-449A-8C50-30276AA9B63F",
      "locationType": "space",
      "eventId": "42FA8F0D-DBB6-42AC-8618-1865DD476769",
      "occupancy": 3
    },
    {
      "timestamp": "2023-05-15T10:23:45Z",
      "locationId": "D0FA9F18-6E7F-449A-8C50-30276AA9B63F",
      "locationType": "place",
      "eventId": "71FA8F0D-DBB6-42AC-8618-1865DD476769",
      "occupied": true
    }
  ]
}

Specific field descriptions

sourceId is an identifier for your presence source. It is only sent once for each API call. It can be any text string and is not validated. It is useful in troubleshooting presence events when looking at the audit log of presence.

timestamp Each presence event has a timestamp that indicates when the presence was detected (this can be in the past).

eventId is a unique ID value for the presence event. If errors are detected when sending the presence event, the problematic eventId will be returned in the response.

locationId specifies the point in the Calven location hierarchy where the presence is being reported.

locationType specifies the type of location represeneted by locationId - Valid values are level, location, place, space or zone.

Programmatically retrieving details

locationId can be retieved via the /v1/analytics/locations endpoint

levelId, zoneId and deskId can be retrieved via the /v1/analytics/desks endpoint

spaceId information cannot be programmatically retrieved currently

Handling errors

There are 2 primary types of errors that can occur when sending data via the occupancy endpoint.

Formatting errors - If the structure of the API call is not formatted correctly, such as missing fields from some events, no data will be loaded from the API call and a 4xx response will be returned.

Data errors - Specific occupancy events may be rejected by the Calven API if the event cannot be processed correctly. For example, a spaceId for one of the events may not link to a space in Calven. In these cases, the specific event will be rejected and reported in the response, but all other events will be loaded.

Occupancy Overview

Occupancy Event Example#

Specific field descriptions#

Programmatically retrieving details#

Handling errors#

Occupancy Event Example

Specific field descriptions

Programmatically retrieving details

Handling errors