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: aggregate_tag_interval_facts

      aggregate_tag_interval_facts Returns an array of interval facts for a specific Tag over a given span of time. Information on how to create assign nodes to tags within SiteWorx can be found here. Parameters Example Call Example Response Parameters ...

    • API Endpoint: aggregate_site_interval_facts

      aggregate_site_interval_facts Returns an array of interval facts for a site over a given span of time. Parameters Example Call (Energy Usage) Example Response (Energy Usage) Example Call (Occupancy) Example Response (Occupancy) Parameters Field Type ...

    • 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.