API Terms

API Terms

Overview

This article provides definitions of terms that are critical to understand when using the SiteWorx API.

Terms

ID

All resources in SiteWorx are identified by a unique ID. They are represented as alpha-numeric strings (e.g. 3EVHgjWw46E.)

Organization

An Organization is the collection of all of a one customer's SiteWorx components - lights, sensors, gateways, and software.

Site

An organization contains one or more Sites, each representing a single facility location. The Site is usually an entire facility at a specific address, but some organizations prefer to make different Sites for each separate building at an address.

Node

In SiteWorx, a Node represents a single wireless device; usually a Lighting Node or a Sensor.

Data Source

Each piece of light or sensor data collected by SiteWorx is associated with a DataSource, which in turn is associated with a Node. Some nodes can have more than one DataSource. For example, a Temperature/Humidty Sensor has two DataSources, one for temperature and one for relative humidity.

Tag

A Tag represents a user-defined collection of Nodes (lights or sensors). Tags are used to aggregate nodes into meaningful groups (e.g. "Hallway Lights") for reporting purposes.

FieldTypeDescription
idstringUnique database id for the tag
namestringTag name
baseline_lighting_powerfloatWatts
Baseline Lighting Power is an estimate of how much power was consumed in the Tagged area prior to installing SiteWorx, for comparison purposes. This number is provided by the customer when creating the Tag.

Interval

For reporting purposes Siteworx "aggregates" sensor data into fixed sized buckets of various durations called an interval.

For "cumulative" sensors (like energy usage or fluid flow) the reported data is the sum total during the interval.

For "instantaneous" sensors (like temperature or humidity) the reported data is the minimum, maximum and average during the interval.

The interval sizes can be:
  1. 15 minutes - aligned at :00, :15, :30 and :45 minutes past the hour
  2. 1 hour - aligned with the hour
  3. 1 day - aligned with Site local midnight

Interval Types

The SiteWorx public API currently reports on two types of intervals:

NameValueDescription
PowerFact1Energy/Power (Wh) consumed during the interval
OccupancyFact5Average occupancy during the interval
Occupancy is a measure of how much time the light's occupancy sensors have been triggered, averaged across the specified interval period, for all of the lights in the area (Site or Tag). It ranges from 0.0 (unoccupied) to 1.0 (all occupancy sensors triggered for the entire interval).

    • Related Articles

    • How to Use the API

      Overview SiteWorx offers a web-based REST API to authenticate, make requests, and retrieve data from both lighting nodes in SiteWorx Tune and sensor nodes in SiteWorx Sense. The following data types are available: Lighting nodes Lighting energy usage ...

    • CSV Example

      CSV Example By default, the API endpoints return data in JSON format. Example JSON queries can be found in the API Endpoints section. Most endpoints also support the option to return the data in CSV format. This is enabled by setting the Accept ...

    • API Endpoint: site_list

      site_list Returns an array of site_info structs with information about each Site in your Organization. Further information can be found in the API Endpoint: site_info article.

    • API Endpoint: site_info

      site_info Returns information about a Site in your Organization. Variables Parameters Example Call Example Response Variables Field Type Description id string Unique database id for this site name string Site name address string Site address ...

    • API Endpoint: aggregate_sensor_data

      aggregate_sensor_data Returns sensor data aggregated over time for a given data_source or sensor. The aggregate_sensor_data endpoint can be used to retrieve data from power meters and environmental sensors in SiteWorx Sense. Parameters Example Call ...