Area Metrics

This section describes endpoints available for Store Area Metrics. The following table briefly presents the categories while the following paragraphs describe in detail all available resources.

Area Metric	Description
Unique Users	Unique Device IDs per store area
Average Screen Time	The average time spent per user per zone.
Area Traffic	Benchmark of traffic distribution (%) across the store’s areas/zones

Availability (granularity)

All area metrics are available in daily granularity. It is proposed to fetch area metrics in daily increments. For example, an import flow can be run once daily and fetch all metrics available for the previous day (using the appropriate time filters).

Pagination

All area metrics resources support pagination. Due to increased data volume, adding pagination to these resources allows fetching data in batches (pages) for a specific time interval. In each paginated response you will find the following properties:

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
the previous property operated similarly to the next property
the results property contains the array of sessions either for a page or for the entire result

Key takeways: 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. To consume all pages, the client needs to continue fetching page-by-page using the link provided within the next property until null value is found (last page - all sessions fetched).

Unique Users

This resource returns the unique users (Unique Device IDs) per zone for a specific store and time interval. The response contains a list of results grouped by store and date.

Resource [GET]

[/bi/area-metrics/unique-users/]

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 the parameter is not provided
page The page number of the response - Optional Only required when the 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
date The day for which the metric was generated - ISO 8601 Date and time with timezone
granularity The time granularity for the metric - currently available: daily - String
values An array containing the unique user values per zone - Array
- zone_name The name of the zone - String
- unique_users The number of unique users for this zone - Int

{
    "next": "http://api.opap.bespot.io/api/bi/area-metrics/unique-users/?datetime_gte=2024-01-22T00%3A00%3A00Z&datetime_lte=2024-01-24T00%3A00%3A00Z&page=2&page_size=3",
    "previous": null,
    "count": 497,
    "results": [
        {
            "store_code": "113409",
            "date": "2024-01-24T00:00:00+02:00",
            "granularity": "daily",
            "values": [
                {
                    "zone": "OUT",
                    "unique_users": 14
                },
                {
                    "zone": "[10] BACK, NEAR TO VLT'S",
                    "unique_users": 5
                },
                {
                    "zone": "[2] STOIXIMA ZONE",
                    "unique_users": 21
                }
            ]
        },
        {
            "store_code": "113409",
            "date": "2024-01-23T00:00:00+02:00",
            "granularity": "daily",
            "values": [
                {
                    "zone": "OUT",
                    "unique_users": 12
                },
                {
                    "zone": "[10] BACK, NEAR TO VLT'S",
                    "unique_users": 5
                },
                {
                    "zone": "[2] STOIXIMA ZONE",
                    "unique_users": 22
                }
            ]
        },
        {
            "store_code": "124301",
            "date": "2024-01-24T00:00:00+02:00",
            "granularity": "daily",
            "values": [
                {
                    "zone": "OUT",
                    "unique_users": 19
                },
                {
                    "zone": "[7] MIXED STOIXIMA KINO ZONE",
                    "unique_users": 24
                },
                {
                    "zone": "[8] FAST SERVING ZONE",
                    "unique_users": 6
                }
            ]
        }
    ]
}

Example cURL

curl --location 'https://api.opap.bespot.io/api/bi/area-metrics/unique-users?datetime_gte=2024-01-22T00%3A00%3A00Z&datetime_lte=2024-01-24T00%3A00%3A00Z&page_size=3' \
--header 'Authorization: Basic BASE64_ENCODED_CREDENTIALS'

Average Screen Time

This resource returns the average time a user interacts with the app in a specific zone of a specific store and time interval. The response contains a list of results grouped by store and date.

Resource [GET]

[/bi/area-metrics/avg-screen-time/]

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 the parameter is not provided
page The page number of the response - Optional Only required when the 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
date The day for which the metric was generated - ISO 8601 Date and time with timezone
granularity The time granularity for the metric - currently available: daily - String
values An array containing the average screen time per zone - Array
- zone_name The name of the zone - String
- avg_screen_time average screen time users spend in this zone - String

{
    "next": "http://api.opap.bespot.io/api/bi/area-metrics/avg-screen-time/?datetime_gte=2024-01-22T00%3A00%3A00Z&datetime_lte=2024-01-24T00%3A00%3A00Z&page=2&page_size=3",
    "previous": null,
    "count": 497,
    "results": [
        {
            "store_code": "113409",
            "date": "2024-01-24T00:00:00+02:00",
            "granularity": "daily",
            "values": [
                {
                    "zone": "OUT",
                    "avg_screen_time": "00:00:17"
                },
                {
                    "zone": "[10] BACK, NEAR TO VLT'S",
                    "avg_screen_time": "00:00:10"
                },
                {
                    "zone": "[2] STOIXIMA ZONE",
                    "avg_screen_time": "00:00:42"
                },
                {
                    "zone": "[4] AGENT BENCH",
                    "avg_screen_time": "00:00:46"
                }
            ]
        },
        {
            "store_code": "113409",
            "date": "2024-01-23T00:00:00+02:00",
            "granularity": "daily",
            "values": [
                {
                    "zone": "OUT",
                    "avg_screen_time": "00:00:07"
                },
                {
                    "zone": "[10] BACK, NEAR TO VLT'S",
                    "avg_screen_time": "00:00:06"
                },
                {
                    "zone": "[2] STOIXIMA ZONE",
                    "avg_screen_time": "00:00:42"
                },
                {
                    "zone": "[4] AGENT BENCH",
                    "avg_screen_time": "00:00:46"
                }
            ]
        },
        {
            "store_code": "124301",
            "date": "2024-01-24T00:00:00+02:00",
            "granularity": "daily",
            "values": [
                {
                    "zone": "OUT",
                    "avg_screen_time": "00:00:14"
                },
                {
                    "zone": "[2] STOIXIMA ZONE",
                    "avg_screen_time": "00:00:14"
                },
                {
                    "zone": "[7] MIXED STOIXIMA KINO ZONE",
                    "avg_screen_time": "00:00:50"
                },
                {
                    "zone": "[8] FAST SERVING ZONE",
                    "avg_screen_time": "00:00:46"
                }
            ]
        }
    ]
}

Note: The avg_screen_time metric value is represented in the following string format: “HH:MM:SS”. Hours, minutes and seconds.

Example cURL

curl --location 'https://api.opap.bespot.io/api/bi/area-metrics/avg-screen-time?datetime_gte=2024-01-22T00%3A00%3A00Z&datetime_lte=2024-01-24T00%3A00%3A00Z&page_size=3' \
--header 'Authorization: Basic BASE64_ENCODED_CREDENTIALS'

Area Traffic

This resource returns the percentage of a user’s total time spent in each zone for a specific store and time interval. The sum of all area percentages should be 1 (meaning 100%). The response contains a list of results grouped by store and date. The area traffic metric serves as a benchmark for a store’s zones.

Resource [GET]

[/bi/area-metrics/traffic/]

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 the parameter is not provided
page The page number of the response - Optional Only required when the 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
date The day for which the metric was generated - ISO 8601 Date and time with timezone
granularity The time granularity for the metric - currently available: daily - String
values An array containing traffic percentage values per zone - Array
- zone_name The name of the zone/area - String
- traffic_pct The percentage of the time spent by users in this zone (in comparison with the rest of the zones) - String

{
    "next": "http://api.opap.bespot.io/api/bi/area-metrics/traffic/?datetime_gte=2024-01-22T00%3A00%3A00Z&datetime_lte=2024-01-24T00%3A00%3A00Z&page=2&page_size=3",
    "previous": null,
    "count": 497,
    "results": [
        {
            "store_code": "113409",
            "date": "2024-01-24T00:00:00+02:00",
            "granularity": "daily",
            "values": [
                {
                    "zone": "OUT",
                    "traffic_pct": "0.09395"
                },
                {
                    "zone": "[10] BACK, NEAR TO VLT'S",
                    "traffic_pct": "0.00977"
                },
                {
                    "zone": "[2] STOIXIMA ZONE",
                    "traffic_pct": "0.89628"
                }
            ]
        },
        {
            "store_code": "113409",
            "date": "2024-01-23T00:00:00+02:00",
            "granularity": "daily",
            "values": [
                {
                    "zone": "OUT",
                    "traffic_pct": "0.04140"
                },
                {
                    "zone": "[10] BACK, NEAR TO VLT'S",
                    "traffic_pct": "0.01084"
                },
                {
                    "zone": "[2] STOIXIMA ZONE",
                    "traffic_pct": "0.94776"
                }
            ]
        },
        {
            "store_code": "124301",
            "date": "2024-01-24T00:00:00+02:00",
            "granularity": "daily",
            "values": [
                {
                    "zone": "OUT",
                    "traffic_pct": "0.08840"
                },
                {
                    "zone": "[7] MIXED STOIXIMA KINO ZONE",
                    "traffic_pct": "0.90860"
                },
                {
                    "zone": "[8] FAST SERVING ZONE",
                    "traffic_pct": "0.00300"
                }
            ]
        }
    ]
}

Note: The traffic_pct metric value is represented by a string in the following format: “X.XXXXX” indicating a numeric value between 0 and 1 with a precision of 5 decimal points.

Example cURL

curl --location 'https://api.opap.bespot.io/api/bi/area-metrics/traffic?datetime_gte=2024-01-22T00%3A00%3A00Z&datetime_lte=2024-01-24T00%3A00%3A00Z&page_size=3' \
--header 'Authorization: Basic BASE64_ENCODED_CREDENTIALS'