> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bespot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Visitor Retention Metrics

> This section describes endpoints available for People Counter Retention Metrics.

> New data are made available at 11:00 UTC on the following day.

***

## Retention metrics

This resource returns the following metrics in *day* granularity for the requested time interval:

| Metric                           | Description                                                                                                    |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Outside Traffic                  | The number of people who passed by the storefront area but did not end up visiting the store.                  |
| Turn in Coversion                | The number of people who passed by the storefront area and entered the store within the predefined time range. |
| Average Visit Duration           | The average duration that visitors spent within the store.                                                     |
| Returning Customers Last 14 Days | Visitors who had previously made a visit to the same store within the past 14 days.                            |
| New Customers Last 14 Days       | Visitors who did not make any visits to the store in the past 14 days.                                         |
| Returning Customers Last 60 Days | Visitors who had previously made a visit to the same store within the past 60 days.                            |
| New Customers Last 60 Days       | Visitors who did not make any visits to the store in the past 60 days.                                         |

**Notice: Deprecation of Metrics for GDPR Compliance**

Our provider has decided to discontinue the metrics Returning Customers Last 60 Days and New Customers Last 60 Days to align with GDPR regulations and uphold data privacy standards.

### Resource \[GET]

`[/bi/retention-metrics/]`

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*
* `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*
* `outside_traffic`  - *Integer*
* `turn_in_rate`  - *Float*
* `avg_visit_duration`  - *Float*
* `returning_cust_14`  - *Float*
* `new_cust_14`  - *Float*
* `returning_cust_60`  - *Float*
* `new_cust_60`  - *Float*
* `day` The day of measurement - *ISO 8601 Date and time with timezone*

```json theme={null}
{
    "count": 5,
    "next": "http://datamine.bespot.io/api/bi/retention-metrics/?datetime_gte=2023-11-13T00%3A00%3A00Z&datetime_lte=2023-11-18T23%3A59%3A00Z&page=2&page_size=3&store_code=116500",
    "previous": null,
    "results": [
        {
            "store_code": "116500",
            "outside_traffic": 101,
            "turn_in_rate": 0.7725,
            "avg_visit_duration": 14.0,
            "returning_cust_14": 0.84,
            "new_cust_14": 0.16000000000000003,
            "returning_cust_60": 0.92,
            "new_cust_60": 0.07999999999999996,
            "day": "2023-11-14T00:00:00+02:00"
        },
        {
            "store_code": "116500",
            "outside_traffic": 85,
            "turn_in_rate": 0.8337,
            "avg_visit_duration": 13.27,
            "returning_cust_14": 0.75,
            "new_cust_14": 0.25,
            "returning_cust_60": 0.7916666666666666,
            "new_cust_60": 0.20833333333333337,
            "day": "2023-11-15T00:00:00+02:00"
        },
        {
            "store_code": "116500",
            "outside_traffic": 125,
            "turn_in_rate": 0.7815000000000001,
            "avg_visit_duration": 12.38,
            "returning_cust_14": 0.5714285714285714,
            "new_cust_14": 0.4285714285714286,
            "returning_cust_60": 0.6285714285714286,
            "new_cust_60": 0.37142857142857144,
            "day": "2023-11-16T00:00:00+02:00"
        }
    ]
}
```

### Example cURL

```
curl --location 'https://datamine.bespot.io/api/bi/retention-metrics?datetime_gte=2023-11-13T00%3A00%3A00Z&datetime_lte=2023-11-18T23%3A59%3A00Z&store_code=116500&page_size=3' \
--header 'Authorization: Basic BASE64_ENCODED_CREDENTIALS'
```

***