Cumulus MX Local API

Revision as of 14:08, 18 October 2020 by Mcrossley (talk | contribs) (Add graph data)

There are two methods of calling the Cumulus MX local API (note the web tag names are case sensitive just like normal):

General API - HTTP GET

This provides a quick and simple method of getting data, you just provide the web tag names in the GET URL and MX returns a simple JSON string with the tag-name:tag-value pairs. The tags are always returned with the default format. You can specify a special parameter "rc" (which must be the first URL parameter) to apply the usual remove commas format to all the tags.

eg.

http://localhost:8998/api/tags/process.json?temp&hum&dew

or

http://localhost:8998/api/tags/process.json?rc&temp&hum&dew

Which will return the following format string in the body...

{"temp":"15.8","hum":"73","dew":"10.5"}

Note, ALL values are quoted as strings as it is difficult to know which are numeric and which are not.


General API - HTTP POST

The POST method allows you to put whatever text you like in the request body - and include any web tags plus formatting you wish. The string returned will be exactly the same text with the tags substituted with data. So you could send a simple comma separated list, or some JSON text, or XML, whatever.

eg.

http://localhost:8998/api/tags/process.txt

With a POST body text of..

<#time format="yy/MM/dd hh:mm:ss">,<#temp>,<#RecentFeelsLike d=1>

would return...

20/07/14 01:48:11,15.7,18.4

or

{
   "DateTime:"<#time format="yy/MM/dd hh:mm:ss">",
   "OutsideTemp":<#temp>,
   "FeelsLikeYest":<#RecentFeelsLike d=1>
}

would return...

{
   "DateTime:"20/07/14 01:50:56",
   "OutsideTemp":15.7,
   "FeelsLikeYest":18.4
}


Predetermined Data

Graph Data

Cumulus MX will return graph data on request, it is formatted as JSON

The general format of the request is as follows...

http://localhost:8998:/api/graphdata/xxxxx

Where xxxx is the specific request as below:

tempdata.json

Returns inside temp, dew point, apparent temp, feels like, wind chill, heat index, outdoor temp as a JSON object, each value is an array of timestamp (JavaScript number) and value pairs...

{
   "intemp": [[timestamp1,value1],[timestamp2,value2]...],
   "dew": [[timestamp1,value1],[timestamp2,value2]...],
   "apptemp": [[timestamp1,value1],[timestamp2,value2]...],
   "feelslike": [[timestamp1,value1],[timestamp2,value2]...],
   "wchill": [[timestamp1,value1],[timestamp2,value2]...],
   "heatindex": [[timestamp1,value1],[timestamp2,value2]...],
   "temp": [[timestamp1,value1],[timestamp2,value2]...]
}

winddata.json

Same as temp data...

{
   "wgust": [[,],[,]...],
   "wspeed": [[,],[,]...]
}

raindata.json

Same as temp...

{
   "rfall": [[,],[,]...],
   "rrate": [[,],[,]...]
}

pressdata.json

Same as temp...

{
   "press": [[,],[,]...]
}

wdirdata.json

Same as temp...

{
   "bearing": [[,],[,]...],
   "avgbearing": [[,],[,]...]
}

humdata.json

Same as temp...

{
   "hum": [[,],[,]...],
   "inhum": [[,],[,]...]
}

solardata.json

Same as temp...

{
   "UV": [[,],[,]...],
   "SolarRad": [[,],[,]...],
   "CurrentSolarMax": [[,],[,]...]
}

sunhours.json

Same as temp...

{
   "sunshours": [[,],[,]...]
}

dailyrain.json

Same as temp...

{
   "dailyrain": [[,],[,]...]
}

dailytemp.json

{
   "mintemp": [[,],[,]...],
   "maxtemp": [[,],[,]...],
   "avgtemp": [[,],[,]...]
}

units.json or graphconfig.json

Returns the units of measurement used for the graph values above.

{
   "temp": {"units": "C|F", "decimals": 0|1|2},
   "wind": {"units": "windunit", "decimals": N},
   "rain": {"units": "rainunit", "decimals": N},
   "press": {"units": "pressunit", "decimals": N},
   "hum": {decimals": N},
   "UV": {decimals": N}
}