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 susbscription 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"}]}

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.

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:

The channels section includes details of each data channel that is included in the graph

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}]}

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.

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:

The aggregation type refers to how the data is summarised over the chosen time period

The aggregation period refers to the length of time over which the data is summarised