How to Use the API

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
  1. Lighting energy usage data (energy usage in Wh, available in 15-minute buckets)
  2. Motion sensor occupancy data (occupancy percentage)
Sensor nodes
  1. For power meters, energy usage data in Wh as well as other electrical parameters reported by the meter.
  2. For other sensor types, the API will return the environmental data (temperature, relative humidity, pressure, flow rate, etc.) that the deployed sensor is measuring.
All API requests must be made over HTTPS using an API key that will be provided by the SiteWorx Operations team.

How to Use the API

  1. Get a SiteWorx Software API key
    1. Contact siteworxops@siteworx.io to request a key. Please include your full contact information and Organization Name or URL.
  2. Once you have your key, you can access the API in the following manner:
    1. Header: X-Siteworx-Api-Key: <api-key> 
    2. Base URL: https://<orgname>-backend.siteworx.io/api/v1
    3. Example: curl -H 'X-Siteworx-Api-Key: <api-key>' https://<orgname>-backend.siteworx.io/api/v1/version
    4. Response: {"api_rev":"1.83.0","commit_hash":"b2c430adca6c5959572c35d818c3a634d518e8a1"}

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 to convert times by hand.

    • Related Articles

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

    • Use Case: Data Reporting

      Identify and report on energy-saving achievements SiteWorx Analyze helps customers examine and understand data and insights from their facilities. The easy-to-use data visualization tools lets customers interact with various types of data gathered ...

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

    • Use Case: Occupancy-Based Load Control

      Reduce energy consumption and maintenance of ancillary equipment with SiteWorx Sense Today more than ever, energy efficiency is critical to running a successful operation. Installing intelligent lighting and controls is a great first step to reducing ...

    • Use Case: Alarms

      SiteWorx Sense continuously monitors — so you don't have to SiteWorx Sense is an advanced facility, utility, and process monitoring and management application that starts delivering results immediately. It brings new efficiency and significant ...