Cumulus MX Local API: Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search
No edit summary
(Add graph data)
Line 1: Line 1:
There are two methods of calling the Cumulus MX local API (note the web tag names are case sensitive just like normal):
There are two methods of calling the Cumulus MX local API (note the web tag names are case sensitive just like normal):


== HTTP GET ==  
== 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.
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.
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.
Line 16: Line 16:




 
== General API - HTTP POST ==
== 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.
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.
So you could send a simple comma separated list, or some JSON text, or XML, whatever.
Line 40: Line 39:
     "OutsideTemp":15.7,
     "OutsideTemp":15.7,
     "FeelsLikeYest":18.4
     "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...
<pre>http://localhost:8998:/api/graphdata/xxxxx</pre>
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}
  }
  }

Revision as of 14:08, 18 October 2020

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