People Count API
==========================

.. toctree::
    :hidden:

The People Count API is used to request either raw, aggregated or paginated patron login statistics

.. note::
    Aggregation collects similar statistics in automacially defined intervals.

The API supports pagination, meaning you can limit the size of the result set, and then API includes a token, which the API will then start the next result set from.

.. note::
   You cannot use pagination and aggregation at the same time, and aggregation is forced if the result set is larger than ``1MB``.

The only HTTP method allowed is ``GET``, and the basic request model looks like the following:

.. code-block:: http

    GET https://api.opnbibliotheca.com/v1/peoplecount HTTP/1.1
    Authorization: Bearer <access_token>
    Host: <host>

Optional Query Parameters
-------------------------

There are a range of additional optional query parameters, which you can use to either aggregate, filter or paginate the result with.

The parameters are:

``aggregation`` <string> - Aggregates the result of the request. 
The allowed values are ``branch``, ``client``, ``device``, ``day``, ``quarter`` and ``minute``.

``startToken`` <string> - Start next resultset from this token.

``limit`` <int> - Limit the result and enable pagination.

.. note::
    If ``limit`` is used then the ``startToken`` will be included in the response ``metadata`` if there are additional results.

.. warning::
    You cannot use both ``aggregation`` and ``pagination``.

``from`` <string> - Only query items from after this timestamp.

``to`` <string> - Only query items from before this timestamp. If using ``to`` then ``from`` is required. 

.. note::
    The formats of ``from`` and ``to`` should be in `ISO 8601`_.

.. _ISO 8601: https://en.wikipedia.org/wiki/ISO_8601

Responses
---------

Depending on if you use ``aggregation``, then the response will change.

The raw response without ``aggregation`` is of the following format (the metadata format is depending on which optional parameters are used):

.. code-block:: javascript

    {
        "metadata": {
            "from": string,
            "to": string,
            "count": int,
            "startToken": string,
            "limit": int
        },
        "result": [
            {
                "id": string,
                "amount": int,
                "name": "string",
                "localTime": string,
                "serverTime": string,
                "clientTime": string,
                "category": string,
                "libraryControllerState": string,
                "customerId": int,
                "branchId": int,
                "clientId": int,
                "deviceId": int
            }
        ]
    }

Where ``aggregation`` result will be of the following format:

.. code-block:: javascript

    {
        "metadata": {
            "from": string,
            "to": string,
            "count": int,
            "aggregation": string
        },
        "result": [
            {
                "key": string | int,
                "in": int,
                "out": int
            }
        ]
    }