Analytics
In this section, all endpoints available for Analytics services are described.
Dwell Time
This resource returns the dwell time (the duration of stay/visit) of a user 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.
Resource [GET]
[/bi/dwelltime/]
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_codeThe store code - Optionaldatetime_gteAn date string (in UTC) to be used as greater than or equal for filtering - Requireddatetime_lteAn date string (in UTC) to be used as less than or equal for filtering - Requireddevice_idThe identifier of the user’s device - Optionalpage_sizeThe number of results in each page of the response - Optional Default value is used when param is not givenpageThe number of 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:
session_idThe session identifier - UUIDstore_codeThe store code - Stringdevice_idThe device identifier (filled by BespotSDK) - UUIDuser_idThe user identifier (provided by the BespotSDK consumer) - UUID or empty string ("") if not providedalt_user_idAn alternative user identifier (provided by the BespotSDK consumer) - String or empty string ("") if not providedvisit_startThe date and time the visit (or the session) started - ISO 8601 Date and time with timezonevisit_stopThe date and time the visit (or the session) ended - ISO 8601 Date and time with timezonevisit_durationThe duration of the visit (or the session) in seconds - Integer
{
"count": 6,
"next": "http://api.opap.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": "000000D",
"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": "000000D",
"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": "000000D",
"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://api.opap-dev.bespot.io/api/bi/dwelltime/?store_code=000000D&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_codeThe store code - Optionaldatetime_gteAn date string (in UTC) to be used as greater than or equal for filtering - Requireddatetime_lteAn date string (in UTC) to be used as less than or equal for filtering - Required
Response
[
{
"name": "DimitrosLab",
"store_code": "100000",
"count": 1
}
]
Example cURL
curl --location --request GET 'https://api.opap-dev.bespot.io/api/bi/dwelltime/?store_code=110225&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_codeThe store code - Optionaldatetime_gteAn date string (in UTC) to be used as greater than or equal for filtering - Requireddatetime_lteAn date string (in UTC) to be used as less than or equal for filtering - Required
Response
[
{
"name": "DimitrosLab",
"store_code": "100000",
"count": 3
}
]
Example cURL
curl --location --request GET 'https://api.opap-dev.bespot.io/api/bi/sessions-count/?store_code=100000&datetime_gte=2021-04-14T09:00:00Z&datetime_lte=2021-04-14T11:30:00Z' \
--header 'Authorization: Basic BASE64_ENCODED_CREDENTIALS'