> ## 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. # 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* ```json theme={null} { "next": "http://blueprint.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": "AHQ21000", "date": "2024-01-24T00:00:00+02:00", "granularity": "daily", "values": [ { "zone": "STOREFRONT (SIDEWALK)", "unique_users": 14 }, { "zone": "[10] POS", "unique_users": 5 }, { "zone": "[2] LOTTERY ZONE", "unique_users": 21 } ] }, { "store_code": "AHQ21000", "date": "2024-01-23T00:00:00+02:00", "granularity": "daily", "values": [ { "zone": "STOREFRONT (SIDEWALK)", "unique_users": 12 }, { "zone": "[10] POS", "unique_users": 5 }, { "zone": "[2] LOTTERY ZONE", "unique_users": 22 } ] }, { "store_code": "AHQ21000", "date": "2024-01-24T00:00:00+02:00", "granularity": "daily", "values": [ { "zone": "POS", "unique_users": 19 }, { "zone": "[7] COFFEE BAR", "unique_users": 24 }, { "zone": "[8] FAST SERVING ZONE", "unique_users": 6 } ] } ] } ``` ### Example cURL ``` curl --location 'https://blueprint.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* ```json theme={null} { "next": "http://blueprint.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": "AHQ21000", "date": "2024-01-24T00:00:00+02:00", "granularity": "daily", "values": [ { "zone": "STOREFRONT (SIDEWALK)", "avg_screen_time": "00:00:17" }, { "zone": "[10] POS", "avg_screen_time": "00:00:10" }, { "zone": "[2] LOTTERY ZONE", "avg_screen_time": "00:00:42" }, { "zone": "[4] CUSTOMER CARE", "avg_screen_time": "00:00:46" } ] }, { "store_code": "AHQ21000", "date": "2024-01-23T00:00:00+02:00", "granularity": "daily", "values": [ { "zone": "STOREFRONT (SIDEWALK)", "avg_screen_time": "00:00:07" }, { "zone": "[10] POS", "avg_screen_time": "00:00:06" }, { "zone": "[2] LOTTERY ZONE", "avg_screen_time": "00:00:42" }, { "zone": "[4] CUSTOMER CARE", "avg_screen_time": "00:00:46" } ] }, { "store_code": "AHQ21000", "date": "2024-01-24T00:00:00+02:00", "granularity": "daily", "values": [ { "zone": "STOREFRONT (SIDEWALK)", "avg_screen_time": "00:00:14" }, { "zone": "[2] LOTTERY ZONE", "avg_screen_time": "00:00:14" }, { "zone": "[7] COFFEE BAR", "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://blueprint.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* ```json theme={null} { "next": "http://blueprint.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": "AHQ21000", "date": "2024-01-24T00:00:00+02:00", "granularity": "daily", "values": [ { "zone": "STOREFRONT (SIDEWALK)", "traffic_pct": "0.09395" }, { "zone": "[10] POS", "traffic_pct": "0.00977" }, { "zone": "[2] LOTTERY ZONE", "traffic_pct": "0.89628" } ] }, { "store_code": "AHQ21000", "date": "2024-01-23T00:00:00+02:00", "granularity": "daily", "values": [ { "zone": "STOREFRONT (SIDEWALK)", "traffic_pct": "0.04140" }, { "zone": "[10] POS", "traffic_pct": "0.01084" }, { "zone": "[2] LOTTERY ZONE", "traffic_pct": "0.94776" } ] }, { "store_code": "AHQ21000", "date": "2024-01-24T00:00:00+02:00", "granularity": "daily", "values": [ { "zone": "STOREFRONT (SIDEWALK)", "traffic_pct": "0.08840" }, { "zone": "[7] COFFEE BAR", "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://blueprint.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' ```