Skip to main content

​
Dwell Time

This resource returns the dwell time (the duration of a user’s stay or visit) for a specific store and time interval. The response contains a list of results. Each result item represents a session.
Session: A session starts (is created) at the moment the SDK consumer subscribes for InOut updates and closes when the SDK consumer unsubscribes. Typically, this occurs at application launch. In case the app goes to background, the session closes. When the app comes to foreground again, a new session starts. Finally, when the application is terminated abruptly, the session is never closed.
The following image depicts the different cases of filtering sessions by datetime. Dwelltime datetime filtering

​
Resource [GET]

[/bi/dwelltime/] This resource supports pagination. Due to the increased data volume, adding pagination to this resource enables fetching data in batches (pages) over a specific time interval.

​
URL Parameters

  • store_code The store code - Optional
  • datetime_gte An date string (in UTC) to be used as greater than or equal for filtering - Required
  • datetime_lte An 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 the 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. 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:
  • session_id The session identifier - UUID
  • store_code The store code - String
  • device_id The device identifier (filled by BespotSDK) - UUID
  • user_id The user identifier (provided by the BespotSDK consumer) - UUID or empty string ("") if not provided
  • alt_user_id An alternative user identifier (provided by the BespotSDK consumer) - String or empty string ("") if not provided
  • visit_start The date and time the visit (or the session) started - ISO 8601 Date and time with timezone
  • visit_stop The date and time the visit (or the session) ended - ISO 8601 Date and time with timezone
  • visit_duration The duration of the visit (or the session) in seconds - Integer
{
    "count": 6,
    "next": "http://blueprint.bespot.io/api/bi/dwelltime/?datetime_gte=2021-04-14T09%3A00%3A00Z&datetime_lte=2021-04-14T11%3A30%3A00Z&page=2&page_size=3",
    "previous": null,
    "results": [
        {
            "session_id": "59a6c715-f934-4f62-84f7-1e987eb5d5ba",
            "store_code": "AHQ21000",
            "device_id": "4a1a5c0f-1523-4194-afbf-0d17cbc9257a",
            "user_id": "31b3b029-0014-4702-bd65-d3323608f867",
            "alt_user_id": "123456789",
            "visit_start": "2021-05-12T12:40:53.570366+03:00",
            "visit_stop": "2021-05-12T12:41:43.244950+03:00",
            "visit_duration": 49
        },
        {
            "session_id": "6f4ca126-df4f-428a-a205-e533c020d6a7",
            "store_code": "AHQ21000",
            "device_id": "4a1a5c0f-1523-4194-afbf-0d17cbc9257a",
            "user_id": "31b3b029-0014-4702-bd65-d3323608f867",
            "alt_user_id": "123456789",
            "visit_start": "2021-05-12T12:42:34.167341+03:00",
            "visit_stop": "2021-05-12T12:43:21.180259+03:00",
            "visit_duration": 47
        },
        {
            "session_id": "02dbc6bb-e50a-4220-84eb-00ad02864eda",
            "store_code": "AHQ21000",
            "device_id": "4a1a5c0f-1523-4194-afbf-0d17cbc9257a",
            "user_id": "31b3b029-0014-4702-bd65-d3323608f867",
            "alt_user_id": "123456789",
            "visit_start": "2021-05-12T13:01:26.693398+03:00",
            "visit_stop": null,
            "visit_duration": null
        }
    ]
}
Note 1: Regarding the device_id value. In BespotSDK for Android it is created in every new application installation. In BespotSDK for iOS the identifierForVendor value is used - see more details here. Note 2: Last item in the array above shows an active session - not ended yet. Values in the visit_stop and visit_duration fields is null

​
Example cURL

curl --location --request GET 'https://blueprint.bespot.io/api/bi/dwelltime/?store_code=AHQ21000&datetime_gte=2021-05-12T09:40:00Z&datetime_lte=2021-05-12T10:05:00Z' \
--header 'Authorization: Basic BASE64_ENCODED_CREDENTIALS'

​
Unique users’ count

This resource returns the unique users’ count for a specific store and time interval.

​
Resource [GET]

[/bi/unique-users-count/]

​
URL Parameters

  • store_code The store code - Optional
  • datetime_gte An date string (in UTC) to be used as greater than or equal for filtering - Required
  • datetime_lte An date string (in UTC) to be used as less than or equal for filtering - Required

​
Response

[
    {
        "name": "AthensHQ",
        "store_code": "AHQ21000",
        "count": 1
    }
]

​
Example cURL

curl --location --request GET 'https://blueprint.bespot.io/api/bi/dwelltime/?store_code=AHQ21000&datetime_gte=2021-03-18T09:00:00Z&datetime_lte=2021-03-18T12:00:00Z' \
--header 'Authorization: Basic BASE64_ENCODED_CREDENTIALS'

​
Sessions’ count

This resource returns the session count for a specific store and time interval.

​
Resource [GET]

[/bi/sessions-count/]

​
URL Parameters

  • store_code The store code - Optional
  • datetime_gte An date string (in UTC) to be used as greater than or equal for filtering - Required
  • datetime_lte An date string (in UTC) to be used as less than or equal for filtering - Required

​
Response

[
    {
        "name": "AthensHQ",
        "store_code": "AHQ21000",
        "count": 3
    }
]

​
Example cURL

curl --location --request GET 'https://blueprint.bespot.io/api/bi/sessions-count/?store_code=AHQ21000&datetime_gte=2021-04-14T09:00:00Z&datetime_lte=2021-04-14T11:30:00Z' \
--header 'Authorization: Basic BASE64_ENCODED_CREDENTIALS'