Space Utilization Analytics

This topic describes the APIs of heatmap analytics. Based on passive infrared (PIR) devices, you can get a panoramic view of a space with or without human presence. These APIs can only be used by assigned projects that have permissions on the value-added application.

Request method	API	Description
GET	/v1.0/illumination/addvalue/heatpower/realtime/get	Get real-time heatmap analytics of a room
GET	/v1.0/illumination/addvalue/heatpower/room/get	Show the space utilization
GET	/v1.0/illumination/addvalue/heatpower/compare/single	Compare utilization of a space
GET	/v1.0/illumination/addvalue/heatpower/compare/multi	Compare utilization of multiple spaces

Get real-time heatmap analytics of a room

API description

Get the real-time heatmap analytics of a specified room, and check if there is human presence in the space in the last hour.

API endpoint

GET /v1.0/illumination/addvalue/heatpower/realtime/get

Request parameter

Parameter	Type	Parameter type	Description	Required
roomId	String	body	The room ID.	true

Response parameter

Parameter	Type	Description
code	Integer	The error code. For more information, see the error code section. It is null when the request succeeded.
success	Boolean	Determine whether the request succeeded. true: success. false: failure.
msg	String	The message that is returned if the request fails. It will return null if the request succeeds.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

Parameter	Type	Description
roomId	String	The room ID.
spaceHeatPowerList	List	The list of heatmap distribution in a specified space.
spacePurposeId	String	The purpose ID of a specified space.
average	Double	The average value.
max	Double	The peak value.
happenTime	String	The time when the peak value occurs.
nextLevelRoomId	String	The ID of a specified subordinate room.
nextLevelRoomName	String	The name of a specified subordinate room.
spacePurposeName	String	The purpose name of a specified space.
mappingInfo	String	The information about layer coordinates.
deviceHeatPowerList	List	The list of heatmap distribution of devices.
deviceId	String	The device ID.
deviceName	String	The device name.
pointId	String	The location ID.
average	Double	The average popularity.
x	Double	The x-coordinate of a specified location.
y	Double	The y-coordinate of a specified location.

Sample request

{
  "roomId": "skd2221kkksds2"
}

Sample response

{
  "roomId": "skd2221kkksds2",
  "spaceHeatPowerList": [
    {
      "spacePurposeId": "sksjdsdsds1112",
      "average": 30.2,
      "max": 40.4,
      "happenTime": "2021-02-03",
      "nextLevelRoomId": "sdk23132232",
      "nextLevelRoomName": "This is a subspace name",
      "spacePurposeName": "Meeting Room",
      "mappingInfo": "{"x":223}"
    }
  ],
  "deviceHeatPowerList": [
    {
      "deviceId": "xxx232sx",
      "deviceName": "Sensor name",
      "pointId": "ss2232kkks2",
      "average": 34.3,
      "x": 20.3,
      "y": 34
    }
  ]
}

Show the space utilization

API description

Show the utilization of a single space by time. The returned result includes the utilization of associated subordinate spaces.

API endpoint

GET /v1.0/illumination/addvalue/heatpower/room/get

Request parameter

Parameter	Type	Parameter type	Description	Required
roomId	String	body	The room ID.	true
startTime	long	body	The start time.	true
endTime	long	body	The end time.	true
weekDay	int[]	body	The day of week, starting with 0.	true
startHour	String	body	The start hour. Valid values: 00 to 23.	true
endHour	String	body	The end hour. Valid values: 00 to 23.	true
projectId	String	body	The project ID.	true

Response parameter

Parameter	Type	Description
code	Integer	The error code. For more information, see the error code section. It is null when the request succeeded.
success	Boolean	Determine whether the request succeeded. true: success. false: failure.
msg	String	The message that is returned if the request fails. It will return null if the request succeeds.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

Parameter	Type	Description
roomId	String	The room ID.
spaceHeatPowerList	List	The list of heatmap distribution in a specified space.
spacePurposeId	String	The purpose ID of a specified space.
average	Double	The average value.
max	Double	The peak value.
happenTime	String	The time when the peak value occurs.
nextLevelRoomId	String	The ID of a specified subordinate room.
nextLevelRoomName	String	The name of a specified subordinate room.
spacePurposeName	String	The purpose name of a specified space.
mappingInfo	String	The information about layer coordinates.
deviceHeatPowerList	List	The list of heatmap distribution of devices.
deviceId	String	The device ID.
deviceName	String	The device name.
pointId	String	The location ID.
average	Double	The average popularity.
x	Double	The x-coordinate of a specified location.
y	Double	The y-coordinate of a specified location.

Sample request

{
  "roomId": "ssk223132323"
}

Sample response

{
  "roomId": "skd2221kk****",
  "spaceHeatPowerList": [
    {
      "spacePurposeId": "sksjdsdsd****",
      "average": 30.2,
      "max": 40.4,
      "happenTime": "2021-02-03",
      "nextLevelRoomId": "sdk2313****",
      "nextLevelRoomName": "This is a subspace name",
      "spacePurposeName": "Meeting Room",
      "mappingInfo": "{"x":223}"
    }
  ],
  "deviceHeatPowerList": [
    {
      "deviceId": "*****",
      "deviceName": "Sensor name",
      "pointId": "ss2232k****",
      "average": 34.3,
      "x": 20.3,
      "y": 34
    }
  ]
}

Compare utilization of a space

API description

Compare the utilization states of a single space under a project.

API endpoint

GET /v1.0/illumination/addvalue/heatpower/compare/single

Request parameter

Parameter	Type	Parameter type	Description	Required
roomId	String[]	body	The room ID.	true
queryType	int	body	The query type. Valid values: 1: daily report. 2: monthly report. 3: annual report.	true
queryTime	long	body	The query time.	true
projectId	String	body	The project ID.	true

Response parameter

Parameter	Type	Description
code	Integer	The error code. For more information, see the error code section. It is null when the request succeeded.
success	Boolean	Determine whether the request succeeded. true: success. false: failure.
msg	String	The message that is returned if the request fails. It will return null if the request succeeds.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

Parameter	Type	Description
roomId	String	The room ID.
roomName	String	The name of a room.
average	Double	The average utilization.
max	Double	The peak utilization.
averageValues	List	The list of average utilizations.
ts	String	The x-coordinate.
value	Double	The value of average utilization.
maxValues	List	The list of peak utilizations.
ts	String	The x-coordinate.
value	Double	The peak value.

Sample request

{
  "queryTime": "2023132302",
  "projectId": "xsj32skj***",
  "queryType": 1
}

Sample response

{
  "roomId": "ssda****",
  "roomName": "This is a room",
  "average": 33.3,
  "max": 44.4,
  "averageValues": [
    {
      "ts": "00",
      "value": 22.2
    },
    {
      "ts": "01",
      "value": 21.2
    }
  ],
  "maxValues": [
   {
      "ts": "00",
      "value": 32.2
    },
    {
      "ts": "01",
      "value": 41.2
    }
  ]
}

Compare utilization of multiple spaces

API description

Compare the utilizations of multiple spaces under a project.

API endpoint

GET /v1.0/illumination/addvalue/heatpower/compare/multi

Request parameter

Parameter	Type	Parameter type	Description	Required
roomId	String[]	body	The room ID.	true
queryType	int	body	The query type. Valid values: 1: daily report. 2: monthly report. 3: annual report.	true
queryTime	long	body	The query time.	true
projectId	String	body	The project ID.	true

Response parameter

Parameter	Type	Description
code	Integer	The error code. For more information, see the error code section. It is null when the request succeeded.
success	Boolean	Determine whether the request succeeded. true: success. false: failure.
msg	String	The message that is returned if the request fails. It will return null if the request succeeds.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

Parameter	Type	Description
roomId	String	The room ID.
roomName	String	The name of a room.
average	Double	The average utilization.
max	Double	The peak utilization.
averageValues	List	The list of average utilizations.
ts	String	The x-coordinate.
value	Double	The value of average utilization.
maxValues	List	The list of peak utilizations.
ts	String	The x-coordinate.
value	Double	The peak value.

Sample request

{
  "queryTime": "2020223112323",
  "projectId": "00232sks****",
  "queryType": "1"
}

Sample response

{
    "This is a space ABC": {
        "roomId": "ssda****",
        "roomName": "This is a space ABC",
        "average": 33.3,
        "max": 44.4,
        "averageValues": [
            {
                "ts": "00",
                "value": 22.2
            },
            {
                "ts": "01",
                "value": 21.2
            }
        ],
        "maxValues": [
            {
                "ts": "00",
                "value": 32.2
            },
            {
                "ts": "01",
                "value": 41.2
            }
        ]
    }
}

Error code

The following table lists common error codes returned in the API calls. For more error codes, see Global Error Codes.

Error code	Description
500	A system error has occurred while processing your request.