===========
REST /stats
===========

**/stats** entry allows to get statistics stored in database (table sensor_history).

Getting data with /stats
========================

Parameters description
----------------------
* sensor id : a sensor id
* start time (optionnal)
* end time (optionnal : none = now)

.. note::
    Usage is not yet implemented

/stats/<sensor id>/<key>/all
----------------------------

.. warning ::
    Using this feature can be risky : it can took some time to return all the values and often there is no need to do so.

Result: ::

    {
        "status" : "OK",
        "code" : 0,
        "description" : "None",
        "stats" : [
            {
                "timestamp" : 1286226868,
                "value" : "HIGH",
                "date" : "2010-07-21 16:02:14",
                "sensor_id" : 3
            },
            ...
        ]
    }

Wildcard usage
**************

You can use the '*' to get the values for all sensors

Example : 

* Get all stattistics (don''t use it until it is for test purpore) : ``/stat/*/all``


/stats/<sensor id>/latest
-------------------------------
Get latest value

Result : same than /all but with only one value

Wildcard usage
**************
* Return the last value for all the devices : ``/stat/*/lastest``

/stats/<sensor id>/last/<number of item to get>
-----------------------------------------------------
Get the N last values

Result : same than /all but with only N values

Wildcard usage
**************

* Return the last 10 values for all the sensors : ``/stat/*/last/10``

/stats/<sensor id>/from/<start time> {/to/<end time>}
-----------------------------------------------------------

.. note::
    CSV export allowed

Get values from <start time> to ...
<start time> and <end time> need to be timestamps

Result : same than /all but with values between start and end time

Example
*******
**/stats/5/from/1286226613/to/1286500000**

.. code-block:: python

    {
        "status" : "OK",
        "code" : 0,
        "description" : "None",
        "stats" : [
            {
                "device_stats" : [
                    {
                        "timestamp" : 1286226868,
                        "value" : "22.6875",
                        "date" : "2010-10-04 23:14:28",
                        "sensor_id" : 4
                    },
                    {
                        "timestamp" : 1286226884,
                        "value" : "22.6875",
                        "date" : "2010-10-04 23:14:44",
                        "sensor_id" : 4
                    },
                    {
                        "timestamp" : 1286226899,
                        "value" : "22.6875",
                        "date" : "2010-10-04 23:14:59",
                        "sensor_id" : 4
                    },
                    ...
                ],
                "sensor_id" : "4"
            }
        ]
    }

/stats/<sensor id>/from/<start time> {/to/<end time>}/interval/<year, month, week, day, hour, minute, second>/selector/<min(number only), max(number only), avg(number only), first, last, x>
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
.. note::
    CSV export allowed

Result : for performance issue, the return format is different from /all. Following data are returned:

* sensor_id
* values : a list of tuples

Tuples format
*************
.. code-block:: none

    # Minutes
    # Format : (year, month, week, day, hour, min, value)
    [(2010, 2, 7, 21, 15, 57, 56.5), (2010, 2, 7, 21, 15, 58, 62.5), (2010, 2, 7, 21, 15, 59, 68.5),
    (2010, 2, 7, 21, 16, 0, 74.5), (2010, 2, 7, 21, 16, 1, 80.5), (2010, 2, 7, 21, 16, 2, 86.5)]
    
    # Hours
    # Format : (year, month, week, day, hour, value)
    [(2010, 6, 25, 22, 19, 38.5), (2010, 6, 25, 22, 20, 40.0), (2010, 6, 25, 22, 21, 41.5),
     (2010, 6, 25, 22, 22, 43.0), (2010, 6, 25, 22, 23, 44.0), (2010, 6, 25, 23, 0, 45.5),
     (2010, 6, 25, 23, 1, 47.0), (2010, 6, 25, 23, 2, 48.0)]
    
    # Days
    # Format : (year, month, week, day, value)
    [(2010, 6, 25, 22, 4.0), (2010, 6, 25, 23, 6.0), (2010, 6, 25, 24, 9.0), (2010, 6, 25, 25, 12.0),
     (2010, 6, 25, 26, 15.0), (2010, 6, 25, 27, 18.0), (2010, 6, 26, 28, 21.0)]
    
    # Weeks
    # Format : (year, week, value)
    [(2010, 29, 25.0), (2010, 30, 35.5), (2010, 31, 49.5), (2010, 32, 63.5),
     (2010, 33, 77.5), (2010, 34, 88.0)]
    {CODE}

Example 
^^^^^^^
**/stats/4/from/1286226613/to/1286500000/interval/hour/selector/avg**

.. code-block:: python

    {
        "status" : "OK",
        "code" : 0,
        "description" : "None",
        "stats" : [
            {
                "values" : [
                    [
                        2010,
                        10,
                        40,
                        4,
                        23,
                        22.753251445086704
                    ],
                    [
                        2010,
                        10,
                        40,
                        5,
                        0,
                        22.559444444444445
                    ],
                    [
                        2010,
                        10,
                        40,
                        5,
                        1,
                        22.12887168141593
                    ],
                    ...
                ],
                "sensor_id" : "4"
            }
        ]
    }

/stats/multi/<id1>/<id2>
--------------------------------------
Get last values for multiple sensors in one request

Example json response: ::

    {
        "status" : "OK",
        "code" : 0,
        "description" : "None",
        "stats" : [
            {
                "timestamp" : 1286226868,
                "value" : "HIGH",
                "date" : "2010-07-21 16:02:14",
                "sensor_id" : 3,
                "exists" : "True"
            },       
            {
                "timestamp" : 1286566868,
                "value" : "LOG",
                "date" : "2010-07-22 16:02:14",
                "sensor_id" : 5
                "exists" : "True"
            },
            ...
        ]
    }

Example json response with a device which not exists: ::

    {
        "status" : "OK",
        "code" : 0,
        "description" : "None",
        "stats" : [
            {
                "timestamp" : 1286226868,
                "value" : "HIGH",
                "date" : "2010-07-21 16:02:14",
                "sensor_id" : 3,
                "exists" : "True"
            },
            {
                "sensor_id" : 666,
                "exists" : "False"
            },
            ...
        ]
    }