It is possible to connect to other data sources that are not yet directly supported by using the Application Programming Interface (API). The data API provides a way to send data to ConstantGraph using a set of URL calls combined with an API key which is entered as part of the request. By this mechanism any third party data source can be connected via a small amount of code.
API calls are accessed using a POST method to the base URL using a JSON encoded request body and returning a JSON encoded response. The base URL is:
https://api.constantgraph.com/
Note that the old base url https://data.mongodb-api.com/app/constantgraph-iwfeg/endpoint/http/ is now deprecated and will be switched off in August 2025. Any applications that use the old base url must be converted to use the new one above.
Authentication
ConstantGraph uses API keys to autheticate requests. You can create and view API keys in the API Keys and Access Tokens section of the account page . The API key is applied to the request using the X-Api-Key header.
curl https://api.constantgraph.com/data/data
-H X-Api-Key:0123456789ABCDEF
-H 'Content-Type: application/json'
-d '{"app":"my app name", "version":"1.2.3", "channels": [
{"id":888, "v":100, "Name":"channel name" },{"id":36,"v":17.4}]}'
If a bad url endpoint is called then a NotFound error code will be returned
{"error_code":"NotFound", "error":"Function not found"}
If the API key is incorrect the response will contain an error code of InvalidSession:
{"error_code": "InvalidSession", "error": "user not found" }
If the request body is incorrectly formed, the response will contain an error code of FunctionExecutionError:
{"error_code": "FunctionExecutionError","error": {"message":
"invalid character 'u' looking for beginning of value"}", "link": "..."}
Depending on your subscription level, the requests may be limited with an error code of RateLimit. Basic subscriptions are limited to 100 channel updates per 10 minutes, enhanced subscriptions are limited to 200 channel updates per 10 minutes and premium subscriptions allow many times more than this.
{"error_code":"RateLimit","error": "too many requests for this subscription",
"lastRequest": time of last request, "product": product code}
Every request must contain an app name and version; if they are missing an error code of BadRequest is returned
{"error_code": "BadRequest", "error": "App name or version missing"}
If there is no data to process in the request then this also returns a BadRequest error code
{"error_code":"BadRequest",
"error":"No channels in request - nothing to processes"}
Note that non-numeric values can be sent through the data and timedata calls as long as the data type of the channel it is being sent to accepts non-numeric data. For example sending the value "off" to a channel set as an on/off switch will work, custom data types can be created to handle other values.
Send current data
The data command is available for all subscriptions. It sends data which will be logged at the current time. The id is the channel number that uniquely identifies the channel and is mandatory, v is the numeric value being sent. Any number of channels (up to the maximum in your subscription) can be specified. The channel name and device number are optional but will show in the Graphs configuration page if they are supplied. Once supplied they will remain set until they are changed.
curl https://api.constantgraph.com/data/data
-H X-Api-Key:0123456789ABCDEF
-H 'Content-Type: application/json'
-d {"app":"my app name", "version":"my app version",
"channels": [{"id":id, "v":value, "Name":"channel name"},{"id":36,"v":17.4}]}
If successful, the following result will be returned:
{"status":"success","user":internal user id,
"inserted":number of data points inserted,
"ignored":number of data points ignored,"message":"helpful information"}
Data points may be ignored if they are non-numeric or they have been filtered out using the basic filtering function. If the channel id had not been used before, it will be created automatically.
Send timestamp data
The timedata call is only available on the Premium subscription and takes the following form:
curl https://api.constantgraph.com/data/timedata
-H X-Api-Key:0123456789ABCDEF
-H 'Content-Type: application/json'
-d {"app":"my app name", "version":"my app version",
"channels": [{"id":id, "values":[{"t":timestamp, "v":value},{"t":1605711317,"v":195}]}]}
The timestamp is the time of the data as a Unix epoch in seconds and value is the numeric value being sent. By this mechanism historic data may be added to the system.
Attempting to use the timedata call without a Premium subscription will return:
{"error":"timedata requests are not allowed on this subscription",
"error_code":"AccessDenied", "product":product code}
Data points may be ignored if they are non-numeric or they have been filtered out as per the filtering options provided in the config call. Successful calls will result in:
{"status":"success", "user":internal user id,
"inserted":number of data points inserted,
"ignored":number of data points ignored,
"message":"helpful information"}
Variable, graph and device configuration
The config call takes three main sections: Variables, Graphs, and Devices with each being optional. Variables describe the channels used to record data and Graphs decribes the graphs shown on the dashboard and Devices describe the devices the channels belong to.
Attempting to use the config call without the correct subscription will return:
{"error":"config requests are not allowed on this subscription",
"error_code":"AccessDenied", "product": product code}
Variables
The Variables section relates to channels that you can graph and the channel configuration .
curl https://api.constantgraph.com/data/config
-H X-Api-Key:0123456789ABCDEF
-H 'Content-Type: application/json'
-d {"Variables": [{"Service": "urn:upnp-org:serviceId:Dimming1", "Units":"0", "FilterMaximum":1000, "FilterEnable":0, "Id":22, "FilterMinimum":0, "Device":3, "Name":"Rope Light - LoadLevelStatus", "Logging":1, "Variable":"LoadLevelStatus"}]}
|
Item |
Description |
|---|---|
|
Id |
the unique channel number for the data |
|
Name |
the display name for the channel |
|
Units |
the units of the channel |
|
DataType |
the type of data for the channel from the data type table below |
|
FilterEnable |
true if filtering of channel data is enabled |
|
FilterMaximum |
absolute maximum value for filtering |
|
FilterMinimum |
absolute minimum value for filtering. Set to zero to ignore negative values. |
|
FilterRateMax |
maximum rate of change for filtering (number of units per second) |
|
FilterRateMin |
minimum rate of change for filtering (number of units per second). Set to zero to ignore decreasing values. |
|
Device |
device number id shown in Graph config |
|
Service |
string data about the device |
|
Variable |
string data about the device |
|
Logging |
true if logging is enabled. |
Here are the data type ids that can be used. Note that data types refer to the individual items that are being monitored such as temperature or whether something is on or off.
|
Type id |
Data type description |
|---|---|
|
0 |
node (none or other) |
|
1 |
door lock |
|
2 |
brightness |
|
3 |
energy meter (KWh) |
|
4 |
energy (Watts) |
|
5 |
HVAC mode status |
|
6 |
battery charge |
|
7 |
humidity |
|
8 |
security sensor |
|
9 |
dimming bulb |
|
10 |
on/off switch |
|
11 |
temperature |
|
12 |
high setpoint |
|
13 |
low setpoint |
|
14 |
sensor armed |
|
15 |
generic sensor level |
|
16 |
HVAC operating state |
|
103 |
Siren on/off |
|
109 |
Window Covering |
|
111 |
TVOC |
|
112 |
Voltage |
|
113 |
Contact Sensor (on/off) |
|
114 |
Presence Sensor (on/off) |
|
115 |
Button (on/off) |
Graphs
curl https://api.constantgraph.com/data/config
-H X-Api-Key:0123456789ABCDEF
-H 'Content-Type: application/json'
-d {"Graphs":[{"Channels": [{"AggregateBy":4, "AggregationType":6, "yAxis": 1, "Id":22 } ],"Name": "Heating Hours per Week","Night": 0,"Reference": "weeklyheating","Period": 31536000}]}
The Graphs section is used to describe a graph can can be displayed in ConstanGraph or embedded in a separate application. It can include the following items:
|
Item |
Description |
|---|---|
|
Name |
a descriptive name for the graph |
|
Night |
whether to display night time bands on the graph (0 = off, 1 = on) |
|
Reference |
A short name that is used as a unique reference for the graph |
|
Period |
the time period of the graph in seconds |
|
Channels |
an array of channel data that will be included in the graph as described below: |
The channels section includes details of each data channel that is included in the graph
|
Item |
Description |
|---|---|
|
Id |
the channel Id of the channel to be graphed |
|
AggregateBy |
number id of the aggregation period from the following list (0 - 5): Auto, None (Raw Data), Hour, Day, Week, Month. |
|
AggregationType |
number id of the aggregation function from the following list (0 - 8): Sample, Change (Max - Min), Sum, Weighted Average, Minimum, Maximum, On Duration, On Count, Sample Count |
|
Type |
number id of the graph type from the following list (0 - 5): Spline, Line, Scatter, Area, Column, AreaRange |
|
yAxis |
the yAxis of the channel |
|
DataMultiplier |
number to multiply the data by, if scaling is required (defaults to 1) |
|
DataOffset |
number to add to the data, if scaling is required (defaults to 0) |
Devices
curl https://api.constantgraph.com/data/config
-H X-Api-Key:0123456789ABCDEF
-H 'Content-Type: application/json'
-d {"Devices":[{"Name": "Kitchen Light", "Number": 3, "Parent": 1, "Room": "Kitchen", "Type": 2}]}
|
Item |
Description |
|---|---|
|
Name |
the display name of the device. |
|
Number |
the number id of the Device which matches the number id given in the Variables section |
|
Parent |
the number id of any parent device |
|
Room |
the name of the room the the device is in |
|
Type |
the type id of the device from the list below |
Here are the device data type ids that can be used. Note that devices typically refer to physical devices such as a light switch. A single device can have many channels and each channel can have its own data type.
|
Type id |
Device type description |
|---|---|
|
666 |
Virtual Plug-in Device |
|
1 |
Interface |
|
2 |
Dimmable Light |
|
3 |
Switch |
|
4 |
Security Sensor |
|
5 |
HVAC |
|
6 |
Camera |
|
7 |
Door Lock |
|
8 |
Window Covering |
|
9 |
Remote Control |
|
10 |
IR Transmitter |
|
11 |
Generic IO |
|
12 |
Generic Sensor |
|
13 |
Serial Port |
|
14 |
Scene Controller |
|
15 |
AV |
|
16 |
Humidity Sensor |
|
17 |
Temperature Sensor |
|
18 |
Light Sensor |
|
19 |
Z-wave |
|
20 |
Insteon |
|
21 |
Power Meter |
|
22 |
Alarm Panel |
|
23 |
Alarm Partition |
|
24 |
Siren |
|
25 |
Weather |
|
26 |
Phillips Controller |
|
27 |
Appliance |
|
28 |
UV Sensor |
|
29 |
Mouse Trap |
|
30 |
Doorbell |
|
31 |
Keypad |
|
32 |
Garage Door |
|
33 |
Flow Meter |
|
34 |
Voltage Sensor |
|
35 |
Contact Sensor |
|
36 |
Mobile Prescence |
|
37 |
Button |
Read aggregated graph data
To read data from the API you need to create a read only key from the account page. The graph data GET request returns the aggregated data that is used to create the graphs.
curl https://api.constantgraph.com/graph/graphdata?channel=129&node=1&start=2024-10-15T00:00&stop=2023-10-16T23:59&aggType=1&aggBy=3&compare=1
-H X-Api-Key:0123456789ABCDEF
If successful, a result similar to the following will be returned:
{
"time": "2024-10-15T00:00:00.000Z",
"value": 15.3,
"min": 12307.011,
"max": 12322.312,
"energyRate": 0.310,
"pLow": 15.927,
"pMid": 17.818,
"pHigh": 21.212
},{
"time": "2024-10-16T00:00:00.000Z",
"value": 14.871,
"min": 12322.312,
"max": 12337.184,
"energyRate": 0.306,
"pLow": 14.024,
"pMid": 14.957,
"pHigh": 16.376
}
The parameters that can be passed to the graphdata request are summarised below:
|
parameter |
Description |
|---|---|
|
channel |
the channel number of the data channel to be displayed, as can be found of the Data > Channel Config menu |
|
node |
the number id the location the channel belongs to as seen on the list of locations in the account page |
|
start |
the start date and time of the graph data in ISO 8601 format e.g. YYYY-MM-DDT00:00 |
|
stop |
the stop date and time of the graph data in ISO 8601 format e.g. YYYY-MM-DDT23:59 |
|
aggType |
the aggregation type of the data as described in the table below |
|
aggBy |
the aggregation period of the data as described in the table below |
|
compare |
0 = 1 comparison and 1 = compare with historical norms for this channel |
The aggregation type refers to how the data is summarised over the chosen time period
|
aggType |
Aggregation Type |
|---|---|
|
0 |
Sample - the value of the first data point |
|
1 |
Difference - the difference between data points |
|
2 |
Sum - the sum of data points |
|
3 |
Average - the weighted mean average |
|
4 |
Minimum - the minimum value |
|
5 |
Maximum - the maximum value |
|
6 |
Time On - the number of hours the value remained at 1 or above |
|
7 |
On Count - the number of times the value switched from zero to non-zero |
|
8 |
Sample Count - the number of samples taken |
The aggregation period refers to the length of time over which the data is summarised
|
aggBy |
Aggregation Period |
|---|---|
|
0 |
Auto - period chosen based on the date range |
|
1 |
None - the data is not aggregated and the raw data is returned |
|
2 |
Hour - aggregated by hour |
|
3 |
Day - aggregated by day where the day starts according to the timezone configured in the admin settings |
|
4 |
Week - calendar week starting on Monday |
|
5 |
Month - calendar month |
|
6 |
Not used |
|
7 |
Not used |
|
8 |
7 days - last 7 days - not used by Time Series data |
|
9 |
30 days - last 30 days - not used by Time Series data |