Skip to main content
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:
MetricDescription
Outside TrafficThe number of people who passed by the storefront area but did not end up visiting the store.
Turn in CoversionThe number of people who passed by the storefront area and entered the store within the predefined time range.
Average Visit DurationThe average duration that visitors spent within the store.
Returning Customers Last 14 DaysVisitors who had previously made a visit to the same store within the past 14 days.
New Customers Last 14 DaysVisitors who did not make any visits to the store in the past 14 days.
Returning Customers Last 60 DaysVisitors who had previously made a visit to the same store within the past 60 days.
New Customers Last 60 DaysVisitors 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
{
    "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'