# [DRAFT] People Counter API Endpoints
This section describes all endpoints available for People Counter Metrics.

*Note: New data are available to these endpoints every 15 minutes.*

---

## In, Out and Difference Metrics
This resource returns the number of visits at a store, the number of visits out of the store (exits) and the difference between these two numbers in *minute* granularity for the requested time interval.

### Resource [GET]
`[/bi/acquisition-metrics/visits/]`

This resource supports pagination. Due to increased data volume, adding pagination to this resource allows fetching data in batches (pages) for a specific time interval.

### URL Parameters

- `store_code` The store code - *Optional*
- `datetime_gte` A date string (in **UTC**) to be used as greater than or equal for filtering - *Required*
- `datetime_lte` A date string (in **UTC**) to be used as less than or equal for filtering - *Required*
- `device_id` The identifier of the user's device - *Optional*
- `page_size` The number of results in each page of the response - *Optional* Default value is used when param is not given
- `page` The number of the page of the response - *Optional* Needed only when response is paginated

*Note : Default `page_size` = 1000. Maximum `page_size` = 10000*

### Response
The response is paginated. The `count` property shows the total results of the query. The `next` property contains the link of the subsequent page in case there is any - otherwise it has `null` value. Likewise with `previous` property. Finally, the `results` property contains the array of sessions either for a page or for the entire result.
If `page_size` (default or set by the client) > `count` then only one page of results is returned and `next` and `previous` properties are `null`. In order to consume all pages, the client needs to continue fetching page-by-page using link provided within the `next` property until `null` value is found (last page - all sessions fetched).

In each result object, the following data are available:

- `store_code` The store code - *String*
- `in` Visits In the store - *Integer*
- `out` Visits Out of the store (exits) - *Integer*
- `diff` Difference. Visits In minus Visits Out - *Integer*
- `minute` The minute of measurement - *ISO 8601 Date and time with timezone*

{
    "count": 6,
    "next": "http://api.opap.bespot.io/api/bi/acquisition-metrics/visits/?datetime_gte=2023-10-26T12%3A05%3A00Z&datetime_lte=2023-10-26T12%3A30%3A00Z&page=2&page_size=4&store_code=116500",
    "previous": null,
    "results": [
        {
            "store_code": "116500",
            "in_metric": 3,
            "out_metric": 0,
            "diff_metric": 3,
            "minute": "2023-10-26T15:06:00+03:00"
        },
        {
            "store_code": "116500",
            "in_metric": 0,
            "out_metric": 1,
            "diff_metric": -1,
            "minute": "2023-10-26T15:08:00+03:00"
        },
        {
            "store_code": "116500",
            "in_metric": 1,
            "out_metric": 2,
            "diff_metric": -1,
            "minute": "2023-10-26T15:09:00+03:00"
        },
        {
            "store_code": "116500",
            "in_metric": 0,
            "out_metric": 2,
            "diff_metric": -2,
            "minute": "2023-10-26T15:10:00+03:00"
        }
    ]
}

### Example cURL

curl --location 'https://api.opap.bespot.io/api/bi/acquisition-metrics/visits/?datetime_gte=2023-10-26T12%3A05%3A00Z&datetime_lte=2023-10-26T12%3A30%3A00Z&store_code=116500&page_size=4' \
--header 'Authorization: Basic BASE64_ENCODED_CREDENTIALS'

---

## Occupancy Metric
This resource returns the number of visitors which are inside a store for a specific time interval in minute granularity.

### Resource [GET]
`[/bi/acquisition-metrics/occupancy/]`

### URL Parameters

- `store_code` The store code - *Optional*
- `datetime_gte` A date string (in **UTC**) to be used as greater than or equal for filtering - *Required*
- `datetime_lte` A date string (in **UTC**) to be used as less than or equal for filtering - *Required*
- `page_size` The number of results in each page of the response - *Optional* Default value is used when param is not given
- `page` The number of page of the response - *Optional* Needed only when response is paginated

*Note : Default `page_size` = 1000. Maximum `page_size` = 10000*

### Response

In each result object, the following data are available:

- `store_code` The store code - *String*
- `occupancy_metric` Occupancy - *Integer*
- `minute` The minute of measurement - *ISO 8601 Date and time with timezone*

{
    "count": 5,
    "next": null,
    "previous": null,
    "results": [
        {
            "store_code": "116500",
            "occupancy_metric": 7,
            "minute": "2021-05-12T12:41:00+03:00",
        },
        {
            "store_code": "116500",
            "occupancy_metric": 9,
            "minute": "2021-05-12T12:44:00+03:00",
        },
        {
            "store_code": "116500",
            "occupancy_metric": 12,
            "minute": "2021-05-12T12:50:00+03:00",
        },
        {
            "store_code": "116500",
            "occupancy_metric": 11,
            "minute": "2021-05-12T12:53:00+03:00",
        },
        {
            "store_code": "116500",
            "occupancy_metric": 11,
            "minute": "2021-05-12T12:56:00+03:00",
        }
    ]
}

### Example cURL

curl --location --request GET 'https://api.opap.bespot.io/api/bi/acquisition-metrics/occupancy?store_code=116500&datetime_gte=2023-10-02T09:40:00Z&datetime_lte=2023-10-02T10:05:00Z' \
--header 'Authorization: Basic BASE64_ENCODED_CREDENTIALS'

---

## Errors
Bespot API uses HTTP status codes to communicate errors. A `code`, `detail`, `error_id` JSON structure is used. See below.

### 404 Not Found

{
    "detail": "Store with this store_code not found.",
    "code": "store_code_not_found",
    "error_id": "2ac759de3d9b62d4"
}

### 401 Unauthorized

{
    "detail": "Invalid username/password.",
    "code": "authentication_failed",
    "error_id": "6ebbc397d56be8e3"
}