How to use the SiteWorx Software API

Updated by Robert Winchester

Overview

SiteWorx offers a web-based REST API to authenticate, make requests, and retrieve the following data:

  • Sensor occupancy and lighting energy usage data (occupancy% and energy usage in Wh available in 15-minute buckets)

In the future, the SiteWorx API will also support environmental data based on deployed SiteWorx Sense devices (available data will vary based on deployed sensors and datasources).

All API requests must be made over HTTPS using an API key that will be provided by the SiteWorx Support team.

Process for using the SiteWorx API

  1. Get a SiteWorx Software API key

    Contact support@siteworx.io to request a key. Please include your full contact information and organization name.

  2. Once you have your key, you can access the API in the following manner:

    Header: X-Siteworx-Api-Key: <api-key>

    Base URL: https://<orgname>-backend.siteworx.io/api/v1

    Example: curl -H 'X-Siteworx-Api-Key: <api-key>' https://<orgname>-backend.siteworx.io/api/v1/version

    Response: {"api_rev":"1.83.0","commit_hash":"b2c430adca6c5959572c35d818c3a634d518e8a1"}

Terms

IDs

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

Organizations

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

Sites

An organization contains one or more Sites, each representing a single 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.

Nodes

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

Data Sources

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.

Tags

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.

field type description
id string Unique database id for the tag
name string Tag name
baseline_lighting_power float Watts

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.

Intervals

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

For "cumulative" sensors (things 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:

  • 15 minutes - aligned at :00, :15, :30 and :45 minutes past the hour;

  • 1 hour - aligned with the hour; and

  • 1 day - aligned with Site local midnight.

Interval Types

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

name value description
PowerFact 1 Energy/Power (Wh) consumed during the interval
OccupancyFact 5 Average 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).

Data Output

By default the API endpoints return data in JSON format. Most endpoints also support the option to return the data in CSV format. This is enabled by setting the Accept header to text/csv. This returns a URL pointing to a remote temporary file containing the result. You must then fetch this URL. Note that the temporary file expires after 24 hours.

Time Representation

The API uses "Unix Epoch Time" to represent all times as integers. Most programming languages and spreadsheet applications have functions to convert between other time formats and Unix Epoch Time.

https://www.epochconverter.com/ is a convenient utility if you need to convert times by hand.

API Endpoints

The following API endpoints are currently supported:

  • site_list
  • aggregate_site_interval_facts
  • aggregate_tag_interval_facts
  • aggregate_site_light_energy
  • aggregate_sensor_data

site_list

Returns an array of site_info structs with information about each Site in your Organization.

site_info

field type description
id string Unique database id for this site
name string Site name
address string Site address
tz_location string Site Time Zone
lat float Site Latitude
long float Site Longitude
baseline_lighting_power float Power usage by the site prior to SiteWorx installation (in KwH)
kwh_rate float Price per KwH
currency string Native currency for the Site
start_time int Unix DateTime when Site was initially commissioned
tags Tags[] Array of Tags associated with the Site (optional)
data_sources DataSources[] Array of Data Sources associated with the Site (optional)

Parameters:

field type description
include_tags boolean,optional Include all tags for the site
include_data_sources boolean,optional Include all data_sources for the site

Example Call:

GET https://example-backend.siteworx.io/api/v1/site_list?include_tags

Example Response:

[

            {

              "id": "486P8TBZpNE",

              "name": "Office Site",

              "address": "15 Main St, Boston, MA",

              "tz_location": "America/New_York",

              "lat": 42.3500206,

              "long": -71.0495288,

              "baseline_lighting_power": 12025,

              "kwh_rate": 0.15,

              "currency": "USD",

              "start_time": 1475294400,

              "tags": [

                {

                  "id": "5CBswh1EF7Z",

                  "site_id": "486P8TBZpNE",

                  "name": "Main Lights",

                  "baseline_lighting_power": 100

                },

                {

                  "id": "8cU2fepUA6z",

                  "site_id": "486P8TBZpNE",

                  "name": "Hall Lights",

                  "baseline_lighting_power": 1400

                }

              ]

            },

            {

              "id": "5iuMaEky88L",

              "name": "Factory Site",

              "address": "285 Industrial Way, Boston, MA",

              "tz_location": "America/New_York",

              "lat": 42.350021,

              "long": -71.049529,

              "baseline_lighting_power": 2000,

              "kwh_rate": 0.2,

              "currency": "USD",

              "start_time": 1514782800,

              "tags": null

            }

          ]

aggregate_site_interval_facts

Returns an array of interval facts for a site over a given span of time.

Parameters:

field type description
site_id string Unique id of site
start_time integer Start time for report (Unix Epoch format)
end_time integer End time for report (Unix Epoch format)
interval_type integer See interval_type above
interval string,optional 15min, hour, or day (defaults to 15min if not specified)
include_minute boolean,optional Annotate each record with the interval start minute-of-hour (0-59)
include_hour boolean,optional Annotate each record with the interval start hour-of-day (0-23)
include_dow boolean,optional Annotate each record with the interval start day-of-week (0-6)
include_all_on boolean,optional Include all_on_wh value (default false)
full_occ_data boolean,optional Include active, inactive and sensor time in occupancy (interval_type = 5) replies (default false)

Example Call (Energy Usage):

Return the daily (interval=day) energy usage (interval_type=1) for Office Site (site_id=486P8TBZpNE)
from 18 June 2018 (start_time=1560830400) through 21 June 2018 (end_time=1561435200). Both times are aligned with local midnight.

GET https://example-backend.siteworx.io/api/v1/aggregate_site_interval_facts?site_id=486P8TBZpNE&interval=day&interval_type=1&start_time=1560830400&end_time=1561089600

Example Response (Energy Usage):

{

            "data": [

              {

                "fact_count": 0,

                "interval_start": 1560830400,

                "interval_type": 1,

                "sum_data": 4648.345231999996,

                "updated_at": "0001-01-01T00:00:00Z"

              },

              {

                "fact_count": 0,

                "interval_start": 1560916800,

                "interval_type": 1,

                "sum_data": 7267.4056759999885,

                "updated_at": "0001-01-01T00:00:00Z"

              },

              {

                "fact_count": 0,

                "interval_start": 1561003200,

                "interval_type": 1,

                "sum_data": 5938.892697999994,

                "updated_at": "0001-01-01T00:00:00Z"

              }

            ],

            "meta": {

              "count": 3

            }

          }

sum_data is the energy usage in Watt-hours for each interval. The fact_count and updated_at fields can be ignored, they are used internally.

Example Call (Occupancy):

Return the 15 minute (interval=15min) occupancy (interval_type=5) for Office Site (site_id=486P8TBZpNE)
from 18 June 2018 9:00am (start_time=1560859200) through 18 June 2018 10:00am (end_time=1560866400). Both times are aligned with local midnight.

GET https://example-backend.siteworx.io/api/v1/aggregate_site_interval_facts?site_id=486P8TBZpNE&interval=15min&interval_type=5&start_time=1560859200&end_time=1560866400

Example Response (Energy Usage):

{

            "data": [

              {

                "fact_count": 6,

                "interval_start": 1560859200,

                "interval_type": 5,

                "sum_data": 0.1751828146654579,

                "updated_at": "0001-01-01T00:00:00Z"

              },

              {

                "fact_count": 6,

                "interval_start": 1560860100,

                "interval_type": 5,

                "sum_data": 0.1345009499267987,

                "updated_at": "0001-01-01T00:00:00Z"

              },

              ... 4 record omitted ...

              {

                "fact_count": 6,

                "interval_start": 1560864600,

                "interval_type": 5,

                "sum_data": 0.06800441630002019,

                "updated_at": "0001-01-01T00:00:00Z"

              },

              {

                "fact_count": 6,

                "interval_start": 1560865500,

                "interval_type": 5,

                "sum_data": 0.05482882373076407,

                "updated_at": "0001-01-01T00:00:00Z"

              }

            ],

            "meta": {

              "count": 8

            }

          }

sum_data is the site average occupancy for each interval, in the range 0.0 to 1.0. The fact_count and updated_at fields can be ignored, they are used internally.

aggregate_tag_interval_facts

Returns an array of interval facts for a specific Tag over a given span of time.

Parameters:

field type description
tag_id string Unique id of Tag
start_time integer Start time for report (Unix Epoch format)
end_time integer Start time for report (Unix Epoch format)
interval_type integer See interval_type above
interval string,optional 15min, hour, or day (defaults to 15min if not specified)
include_minute boolean,optional Annotate each record with the interval start minute-of-hour (0-59)
include_hour boolean,optional Annotate each record with the interval start hour-of-day (0-23)
include_dow boolean,optional Annotate each record with the interval start day-of-week (0-6)
include_all_on boolean,optional Include all_on_wh value (default false)
full_occ_data boolean,optional Include active, inactive and sensor time in occupancy (interval_type = 5) replies (default false)

Example Call:

Return the hourly (interval=hour) energy usage (interval_type=1) for the Main Lights tag (tag_id=5CBswh1EF7Z)
for 17 Feb 2023 9:00am (start_time=1676642400) through 17 Feb 2023 5:00pm (end_time=1676671200).

GET https://example-backend.siteworx.io/api/v1/aggregate_tag_interval_facts?tag_id=5CBswh1EF7Z&interval=hour&interval_type=1&start_time=1676642400&end_time=1676671200

Example Response:

{

            "data": [

              {

                "fact_count": 4,

                "interval_start": 1676642400,

                "interval_type": 1,

                "sum_data": 13.852433281004709,

                "updated_at": "0001-01-01T00:00:00Z"

              },

              {

                "fact_count": 4,

                "interval_start": 1676646000,

                "interval_type": 1,

                "sum_data": 41.778335949764525,

                "updated_at": "0001-01-01T00:00:00Z"

              },

              ... 4 records omitted ...

              {

                "fact_count": 4,

                "interval_start": 1676664000,

                "interval_type": 1,

                "sum_data": 42.225641025641025,

                "updated_at": "0001-01-01T00:00:00Z"

              },

              {

                "fact_count": 4,

                "interval_start": 1676667600,

                "interval_type": 1,

                "sum_data": 41.68205128205128,

                "updated_at": "0001-01-01T00:00:00Z"

              }

            ],

            "meta": {

              "count": 8

            }

          }

aggregate_site_light_energy

Returns the total energy used (in Watt-hours) by all of the light nodes in the site over the specified time period.

Similar to aggregate_site_interval_facts with interval=day and interval_type=1, but sums the total energy for the
entire specified time span.

field type description
site_id string Unique id of site
start_time integer Start time for report (Unix Epoch format)
end_time integer End time for report (Unix Epoch format)

Example Call:

Return total energy used by site's lights from 18 June 2018 through 21 June 2018.

GET https://example-backend.siteworx.io/api/v1/aggregate_site_light_energy?site_id=486P8TBZpNE&start_time=1560830400&end_time=1561089600

Example Response:

{

            "total_energy": 17854.643605999976

          }

aggregate_sensor_data

Returns sensor data aggregated over time for a given data_source or sensor.

Parameters:

field type description
data_source_id string Unique id of DataSource
sensor_id string Unique id of Sensor
start_time integer Start time for report (Unix Epoch format)
end_time integer End time for report (Unix Epoch format)
interval string,optional 15min, hour, or day (defaults to 15min if not specified)
include_minute boolean,optional Annotate each record with the interval start minute-of-hour (0-59)
include_hour boolean,optional Annotate each record with the interval start hour-of-day (0-23)
include_dow boolean,optional Annotate each record with the interval start day-of-week (0-6)

Example Call (Energy Usage):

Return the daily (interval=day) energy usage (interval_type=1) for sensor (data_source_id=4Wkcm4CW8cJ)
from 18 June 2018 (start_time=1560830400) through 21 June 2018 (end_time=1561435200). Both times are aligned with local midnight.

GET https://example-backend.siteworx.io/api/v1/aggregate_sensor_data?data_source_id=4Wkcm4CW8cJ&interval=day&interval_type=1&start_time=1560830400&end_time=1561089600

Example Response:

{

            "data": [

              {

                "data_source_id": "4Wkcm4CW8cJ",

                "data_type": 7,

                "interval_start": 1538366400,

                "max_adj_value": 609.5796934962273,

                "max_value": 1451,

                "mean_adj_value": 604.0453392913786,

                "mean_value": 1443.7627118644068,

                "min_adj_value": 601.1679935455322,

                "min_value": 1440,

                "sample_count": 59

              },

              {

                "data_source_id": "4Wkcm4CW8cJ",

                "data_type": 7,

                "interval_start": 1538370000,

                "max_adj_value": 606.5208935141563,

                "max_value": 1447,

                "mean_adj_value": 602.9954969246509,

                "mean_value": 1442.3898305084747,

                "min_adj_value": 600.4032935500145,

                "min_value": 1439,

                "sample_count": 59

              },

              "NOTE: 21 records removed...",

              {

                "data_source_id": "4Wkcm4CW8cJ",

                "data_type": 7,

                "interval_start": 1538449200,

                "max_adj_value": 589.6974936127663,

                "max_value": 1425,

                "mean_adj_value": 586.0684088882754,

                "mean_value": 1420.2542372881355,

                "min_adj_value": 583.5798936486244,

                "min_value": 1417,

                "sample_count": 59

              }

            ],

            "meta": {

              "count": 24

            }

          }

CSV Example

Perform the same aggregate_site_interval_fact occupancy query as above, with a resulting CSV file

Example Call (part 1 - prepare data)

curl -s -H  'X-Siteworx-Api-Key: <api-key>' \

              -H 'Accept: text/csv' \

              'https://example-backend.siteworx.io/api/v1/aggregate_site_interval_facts?site_id=486P8TBZpNE&interval=15min&interval_type=5&start_time=1560859200&end_time=1560866400'

Example Response (part 1)

{

            "url": "https://s3.amazonaws.com/reports-dev.siteworx.io/siteworx-export-20230516-162404-Z-Upcj4hxIw%3D.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA5O3CPGLQYZ4AZLUZ%2F20230516%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230516T202404Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=ce6a18e91d8cd05dd086b37b5f104ad75e743113624eed9e8a6e335478f955c2"

          }

Example Call (part 2 - fetch CSV data)

curl -s "https://s3.amazonaws.com/reports-dev.siteworx.io/siteworx-export-20230516-162404-Z-Upcj4hxIw%3D.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA5O3CPGLQYZ4AZLUZ%2F20230516%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230516T202404Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=ce6a18e91d8cd05dd086b37b5f104ad75e743113624eed9e8a6e335478f955c2"

Example Response (part 2)

Site ID,Interval Start,Occupancy

          486P8TBZpNE,2019-06-18T08:00:00-04:00,0.18

          486P8TBZpNE,2019-06-18T08:15:00-04:00,0.13

          486P8TBZpNE,2019-06-18T08:30:00-04:00,0.20

          486P8TBZpNE,2019-06-18T08:45:00-04:00,0.15

          486P8TBZpNE,2019-06-18T09:00:00-04:00,0.10

          486P8TBZpNE,2019-06-18T09:15:00-04:00,0.07

          486P8TBZpNE,2019-06-18T09:30:00-04:00,0.07

          486P8TBZpNE,2019-06-18T09:45:00-04:00,0.05

How did we do?