Statistics
==========

El API soporta la obtención de diferentes métricas y estadísticas para que puedan ser
visualizadas en la interfaz de usuario. Por lo general, se intenta reutilizar las
mismas llamadas que ya existen en el API, para reutilizar las mismas capacidades
de filtrado, agregando los recursos y/o sub-recursos que sean necesarios para aquello
que no se pueda obtener de forma directa.

Definimos dos tipos de estadísticas:

* **Escalares**, aquellas que se representan con una única cifra o resultado.
* **Series Temporales**, aquellas que se tienen que representar en una gráfica temporal.

Scalars
-------

Como ejemplo de estadísticas *escalares* podemos encontrar los valores que aparecen en
esta imagen:

.. image:: /_static/generals.png

Aquí en concreto aparecen, en el mismo orden:

* Check-Ins realizados el día de hoy
* Compras completadas
* Bienes vendidos

Check-Ins today
^^^^^^^^^^^^^^^

Para obtener los check-ins en un día en concreto, podemos usar el filtro sobre el
campo ``created``, y, opcionalmente, limitar el tamaño de página para optimizar la
respuesta:

.. sourcecode:: http

    GET /api/v1/carts/?created_after=2020-03-27T00:00:00Z&created_before=2020-03-27T23:59:59&page_size=0 HTTP/1.1

.. sourcecode:: http

    HTTP/1.1 200 OK
    Content-Type: application/json

    {
        "count": 1,
        "next": null,
        "previous": null,
        "results": []
    }

En este caso, nos interesa únicamente el campo ``count`` para obtener el **total**.

.. note::

    Ver :ref:`referencia API de carritos <api-carts-list>`.

Complete purchases
^^^^^^^^^^^^^^^^^^

Cuando hablamos de *compras completadas* hacemos referencia al número de carritos que
han realizado check-out. En este caso, suponiendo que se buscan todas, bastaría con
usar el filtro de ``checkout``.

.. sourcecode:: http

    GET /api/v1/carts/?checkout=True&page_size=0 HTTP/1.1

.. sourcecode:: http

    HTTP/1.1 200 OK
    Content-Type: application/json

    {
        "count": 2,
        "next": null,
        "previous": null,
        "results": []
    }

Como en el resto de llamadas, todos los filtros se pueden aplicar para ajustar los
resultados, por lo que al combinar con ``created`` podríamos obtener el dato para
cualquier día que se necesite.

.. note::

    Ver :ref:`referencia API de carritos <api-carts-list>`.


Items sold
^^^^^^^^^^

Entendemos los bienes vendidos como el sumatorio del campo ``quantity`` de cada uno de
los carritos que queramos incluir en las estadísticas. Al no ser un campo directo, se
añade un *sub-recurso* especial que nos aprota este dato y que es compatible
**con los mismos filtros que los carritos**.

.. sourcecode:: http

    GET /api/v1/carts/stats/ HTTP/1.1

.. sourcecode:: http

    HTTP/1.1 200 OK
    Content-Type: application/json

    {
        "total_quantity": 3,
        "total_items": 2
    }

Donde:

* ``total_quantity``, el número total de productos que están en los carritos, equivalente al sumatorio de ``quantity``.
* ``total_items``, el número total de productos diferentes que están en los carritos, equivalente al sumatorio de ``items_count``.

Por lo que para este ejemplo, usaríamos ``total_quantity``.

.. note::

    Ver :ref:`referencia API de carritos <api-carts-stats>`.

Temporal Series
---------------

Como ejemplo de estadísticas *de series temporales* podemos encontrar los valores que
aparecen en las siguientes imágenes:

.. image:: /_static/checkins_in_time.png

Donde se muestra el número de **check-ins** a lo largo del tiempo.

.. image:: /_static/items_in_time.png

Donde se muestra la **cantidad de bienes vendidos** a lo largo del tiempo.

Esta información es en realidad una información derivada del registro de carritos
que mantiene la plataforma, por lo que se añade un *sub-recurso* nuevo para la
obtención de los datos agregados.

Check-Ins
^^^^^^^^^

Para obtener la agregación temporal por meses de chech-ins, es decir, carritos creados,
usamos el *sub-recurso* ``time-series``, y su parámetro ``interval`` con valor a ``M``.

.. sourcecode:: http

    GET /api/v1/carts/time-series/?interval=M HTTP/1.1

.. sourcecode:: http

    HTTP/1.1 200 OK
    Content-Type: application/json

    [
        {
            "interval": "2020-04-01T00:00:00Z",
            "total": 1
        }
    ]


Sólo hay elementos para aquellos periodos en los que hayan datos, si hay un
intervalo donde no hay datos, **no aparece**.

.. note::

    Ver :ref:`referencia API de carritos <api-carts-time-series>`.


Amount of items sold
^^^^^^^^^^^^^^^^^^^^

Para obtener la agregación temporal por meses de chech-ins,
usamos el *sub-recurso* ``time-series``, su parámetro ``interval`` con valor a ``M`` y
parámetro ``aggregate`` con valor a ``items``.

.. sourcecode:: http

    GET /api/v1/carts/time-series/?interval=M&aggregate=items HTTP/1.1

.. sourcecode:: http

    HTTP/1.1 200 OK
    Content-Type: application/json

    [
        {
            "interval": "2020-04-01T00:00:00Z",
            "total": 1
        }
    ]

Sólo hay elementos para aquellos periodos en los que hayan datos, si hay un
intervalo donde no hay datos, **no aparece**.

.. note::

    Ver :ref:`referencia API de carritos <api-carts-time-series>`.