Rest API¶
Overview¶
You can fetch the statistics from your devices by requesting the REST API to our server. Seemetrix REST API is a feature inherited from our LibAnalytics REST API.
All API’s methods placed at https://analytics.3divi.ru/api/* urls and requests to them are authenticated via a secret user_key.
Please visit https://my.seemetrix.net/profile/ (“REST API” section) to find your user_id and user_key.
Put user_key to url arguments for authentication:
https://analytics.3divi.ru/api/<path>?key=user_key_key
You are authorized to read data from your devices.
In case of a wrong key, you receive 401 HTTP Error.
In case of a wrong user_id or device_id in requests, you receive 403 HTTP Error.
Warning
Keep in mind that all of the API methods are defined without a host and “/api” prefix.
Please, note that the trailing slash is required. You will receive a 404 error if you drop it.
API methods only work on https protocol.
Devices management¶
Get a full list of devices owned by a user:
-
GET /user/(int:user_id)/devices/
Parameters:
- user_id (int) – id of user.
Response JSON Object:
- online_total (int) – number of online devices
- online (list[Device]) – list of online devices
- offline_total (int) – number of offline devices
- offline (list[Device]) – list of offline devices
- frozen_total (int) – number of frozen devices
- frozen (list[Device]) – list of frozen devices
Sample response:
GET https://analytics.3divi.ru/api/user/632/devices/?key=d482d4c3c4bd4dd796abccf726ae1266
{
"frozen": [
{
"acl": [ (list of ids of users who have access to the device)
436,
632
],
"created": "Fri, 08 Sep 2017 04:35:12 GMT",
"d": 3035, (device_id)
"f": 1,
"ip": "87.249.208.18",
"k": "9909e1d0933740f0811913647e3662e8", (device_key)
"modified": "Fri, 15 Sep 2017 07:36:38 GMT",
"n": "Device #1", (name of the device)
"o": 0,
"or": 0,
"s": "bc862d09e7cb682c0d7e923d8c751d16",
"sid": 2
}
],
"frozen_total": 1,
"offline": [
{
"acl": [
632,
436
],
"created": "Thu, 27 Jul 2017 04:29:20 GMT",
"d": 2899,
"f": 0,
"ip": "-",
"k": "a4424dad66f144cb818823f90a40f35b",
"modified": "Thu, 27 Jul 2017 04:29:20 GMT",
"n": "Device #5",
"o": 0,
"or": 0,
"sid": 0
}
],
"offline_total": 1,
"online": [
{
"acl": [
436,
632
],
"created": "Thu, 07 Sep 2017 10:40:21 GMT",
"d": 3024,
"f": 0,
"ip": "87.249.208.18",
"k": "23f69c44cd964dcc9caac2d08217705d",
"modified": "Fri, 15 Sep 2017 07:24:12 GMT",
"n": "Device #3",
"o": 1,
"or": 0,
"s": "ca514a44ddc4a77afff71541564fd958",
"sid": 2
}
],
"online_total": 1
}
Device statistics¶
GET statistics from a particular device:
-
GET /statistics/device/(int:device_id)/
Sample response:
GET https://analytics.3divi.ru/api/statistics/device/3024/?key=d482d4c3c4bd4dd796abccf726ae1266&tzo=1&last_week
{
"begin": "2017/09/08 11:00:00", (begin of datetime range of request)
"begin_iso": "2017-09-08T11:00:00+01:00", (begin of datetime range in ISO datetime format with displaying the time zone)
"end": "2017/09/15 11:00:00", (end of datetime range of request)
"end_iso": "2017-09-15T11:00:00+01:00", (end of datetimerange in ISO datetime format with displaying the time zone)
"max_date": "2017/09/15 10:00:00", (maximum date and time of data that were accessible for request)
"min_date": "2017/09/15 08:00:00", (minimum date and time of data that were accessible for request)
"objects": [ (array of time units sorted by datetime)
{
"i": { (time unit id)
"d": 15, (day of month 1-31)
"h": 8, (hour 0-23)
"m": 9, (month 1-12)
"y": 2017 (year)
},
"t": 7 (total counter)
},
{
"i": {
"d": 15,
"h": 9,
"m": 9,
"y": 2017
},
"t": 0
},
{
"i": {
"d": 15,
"h": 10,
"m": 9,
"y": 2017
},
"t": 1
}
],
"total": 3, (total number of objects in the array "objects")
"total_counters": {
"average_duration": 3.29, (average view duration for a period)
"female": 8, (number of females for a period)
"kid": 0, (number of kids for a period)
"male": 0, (number of males for a period)
"middle": 7, (number of young adults for a period)
"middle2": 1, (number of adults for a period)
"movies_num": 0, (movies watched for a period)
"old": 0, (number of seniors for a period)
"total": 8, (number of total visits for a period)
"undefined_age": 0, (number of views with an undefined age)
"undefined_gender": 0 (number of views with an undefined gender)
}
}
Get statistics from all devices:
-
GET /statistics/user/(int:user_id)/
Sample response:
GET https://analytics.3divi.ru/api/statistics/user/632/?key=d482d4c3c4bd4dd796abccf726ae1266&b=2017/09/12%2012:00:00&e=2017/09/14%2012:00:00&tzo=0
{
"begin": "2017/09/12 12:00:00", (begin of datetime range of request)
"begin_iso": "2017-09-12T12:00:00+00:00", (begin of datetime range in ISO datetime format with displaying the time zone)
"end": "2017/09/14 12:00:00", (end of datetime range of request)
"end_iso": "2017-09-14T12:00:00+00:00", (end of datetime range in ISO datetime format with displaying the time zone)
"max_date": "2017/09/15 09:00:00", (maximum date and time of data that were accessible for request)
"min_date": "2017/09/08 04:00:00", (minimum date and time of data that were accessible for request)
"objects": [ (array of time units sorted by datetime)
{
"i": { (time unit id)
"d": 12, (day of month 1-31)
"h": 12, (hour 0-23)
"m": 9, (month 1-12)
"y": 2017 (year)
},
"t": 3 (total counter)
},
{
"i": {
"d": 12,
"h": 16,
"m": 9,
"y": 2017
},
"t": 6
},
{
"i": {
"d": 12,
"h": 17,
"m": 9,
"y": 2017
},
"t": 6
},
{
"i": {
"d": 13,
"h": 2,
"m": 9,
"y": 2017
},
"t": 7
},
{
"i": {
"d": 13,
"h": 3,
"m": 9,
"y": 2017
},
"t": 12
},
{
"i": {
"d": 13,
"h": 4,
"m": 9,
"y": 2017
},
"t": 15
},
{
"i": {
"d": 13,
"h": 5,
"m": 9,
"y": 2017
},
"t": 18
},
{
"i": {
"d": 13,
"h": 6,
"m": 9,
"y": 2017
},
"t": 12
}
],
"total": 8, (total number of objects in the array "objects")
"total_counters": {
"average_duration": 7.81, (average duration for a period)
"female": 68, (number of females for a period)
"kid": 0, (number of kids for a period)
"male": 11, (number of males for a period)
"middle": 57, (number of young adults for a period)
"middle2": 22, (number of adults for a period)
"movies_num": 0, (movies watched for a period)
"old": 0, (number of seniors for a period)
"total": 79, (number of total views for a period)
"undefined_age": 0, (number of views with an undefined age)
"undefined_gender": 0 (number of total views for a period)
}
}
Required request parameters:
- b <string DateTime “YYYY/MM/DD HH:mm:ss”> – beginning of time span of the requested data (in local timezone), YYYY/MM/DD HH:mm:ss (can be replaced with the last_week argument);
- e <string DateTime “YYYY/MM/DD HH:mm:ss”> – end of time span of the requested data (in local timezone), YYYY/MM/DD HH:mm:ss (can be replaced with the last_week argument);
- tzo <int> – timezone offset. An important option, all datetimes are stored in GMT 0, in requests you set a timezone
Additional request parameters:
- year – if set, then the return statistics is arranged by years
- month – if set, then the return statistics is arranged by months (1-12). If this is the only specified parameter, then the requested statistics (if any) is arranged by 12 months
- day – if set, then the return statistics is arranged (1-31). If this is the only specified parameter, then the requested statistics is arranged by days of the week (1-7)
- hour – if set, then the return statistics is arranged by hours (0-23). If this is the only specified parameter, then the requested statistics is arranged by 24 hours
- last_week – if set, then the data collected for the last week is returned
- sex – if set, then gender statistics (
fl,ml,us) is returned- age – if set, then age statistics (
k,m,m2,o,u) is returned- movies – if set, then the statistics of movie views (
v,va) is returned- intervals – if set, then the view duration statistics (
ia) is returned
Unified device statistics request¶
Request format:
-
GET /v2/statistics/p1/p2/p3/p4/p5/p6
where pN can be devices/movies/dates/ages/genders/emotions;
Depending on the chosen structure of the unified request, all the statistics from the user’s devices will be returned in the response grouped by one or more parameters: devices/movies/dates/ages/genders/emotions.
Required request parameters:
- b <string DateTime “YYYY/MM/DD HH:mm:ss”> – beginning of time span of the requested data (in local timezone), YYYY/MM/DD HH:mm:ss (can be replaced with the last_week argument);
- e <string DateTime “YYYY/MM/DD HH:mm:ss”> – end of time span of the requested data (in local timezone), YYYY/MM/DD HH:mm:ss (can be replaced with the last_week argument);
- tzo <int> – timezone offset. An important option, all datetimes are stored in GMT 0, in requests you set a timezone
Additional request parameters:
d <int> - the identifier of the device ;
dt_format <string date format ”YYYY-MM-DD HH”> - format of grouping by date / time. It affects the “dates” type.
Supported formats:
- “YYYY-MM-DD HH” - calendar hours;
- “YYYY-MM-DD” - calendar day (the default format);
- ”YYYY-MM” - by months of years;
- ”YYYY” - by years;
- “MM” - by months of the year (1-12);
- “DD” - on days of the week (1-7);
- “HH” - by hours (24);
to_object <0/1> - returns a data array, if to_object = 0, or an aggregate object with a key set corresponding to the names of objects in the array, if to_object = 1;
Sample response when using the argument to_object = 0:
GET https://analytics.3divi.ru/api/v2/statistics/user/371/devices/?key=8b00aa55853f403186b5678fde019750&tzo=0&dt_format=MM&b=2016/12/01%2000:00:00&e=2017/06/01%2000:00:00&d=1842&to_object=0
{
"begin": "2016/12/01 00:00:00",
"data": {
"n": "root",
"o": [
{
"n": "1842",
"o": [],
"ots": 64.0,
"otsd": 1360572,
"t": "device",
"v": 64.0,
"vd": 1360572
}
],
"ots": 64.0,
"otsd": 1360572,
"t": "root",
"v": 64.0,
"vd": 1360572
},
"end": "2017/06/01 00:00:00",
"levels": [
"devices"
],
"obj_in_page": 10,
"ok": 1,
"page": 0,
"pages_total": 1,
"path": "devices",
"user_id": 371
}
Sample response when using the argument to_object = 1:
GET https://analytics.3divi.ru/api/v2/statistics/user/371/devices/?key=8b00aa55853f403186b5678fde019750&tzo=0&dt_format=MM&b=2016/12/01%2000:00:00&e=2017/06/01%2000:00:00&d=1842&to_object=1
{
"begin": "2016/12/01 00:00:00",
"data": {
"n": "root",
"o": {
"1842": {
"n": "1842",
"o": {},
"ots": 64.0,
"otsd": 1360572,
"t": "device",
"v": 64.0,
"vd": 1360572
}
},
"ots": 64.0,
"otsd": 1360572,
"t": "root",
"v": 64.0,
"vd": 1360572
},
"end": "2017/06/01 00:00:00",
"levels": [
"devices"
],
"obj_in_page": 10,
"ok": 1,
"page": 0,
"pages_total": 1,
"path": "devices",
"user_id": 371
}
- last_week <1> - can be an alternative for the required arguments b & e; if it is set, the search range for the current week is accepted;
- page <int:0-...> - the number of a current page during data pagination, applicable to the “devices” and “movies” types in the root levels (indexing from zero, default = 0);
- obj_in_page <int:1-...> - the number of objects on one page during data pagination, applicable to the “devices” and “movies” types in the root levels (default = 10);
Note
- Looping is prohibited (once the resource is specified, it cannot be requested later in the request path).
- Fields ots and otsd can belong only to the objects of types movie, device and date, which are at the beginning of the result’s objects. If objects of types movie, device, date in a result tree are the child objects of types age, gender, emotion, then they lose the ability to display ots, otsd because watchers were specifically identified as viewers at the previous level (all ots were filtered out).
- In objects with zero values v (total number of views) further decomposition of the hierarchy ceases because all subsequent objects will also be zero.
- The maximum datetime range of the request is 6 months.
Request structure:
{
begin <string>: the beginning of datetime range of request;
data <list of object>: list / object (depending on the request argument to_object)
{
n <string>: object ID / name (“name”),
o <list/object>: the list of subobjects in the hierarchy (“objects”),
t <string> [date/device/movie/gender/age/emotion/]: resource type (“type”),
v <int>: the counter of views (“views”),
vd <double>: total duration of views in ms. (“views duration”),
[ots <int>: the counter of OTS; only for types: date, device, movie],
[otsd <double>: total dwell time in ms.; only for types: date, device, movie].
}
end <string>: end of the request datetime range;
dt_format <string>: format of grouping by dates (level “date”),
levels <list of string>: the list of request levels;
ok <int>: the sign of a successful result if the value is 1
path <string>: levels in the request path format;
user_id <int>: user ID;
page <int>: page number for the types "devices", "movies" in the root level (0 by default),
obj_in_page <int>: number of objects on a page during the pagination (10 by default),
pages_total <int>: available number of pages for pagination,
}
Sample response:
/emotions/ - returns the statistics of views grouped by emotions: angry / happy / surprised / neutral.
"o": [
{
"n": "angry",
"o": [],
"t": "emotion",
"v": 0,
"vd": 0
},
{
"n": "happy",
"o": [],
"t": "emotion",
"v": 0,
"vd": 0
},
{
"n": "neutral",
"o": [],
"t": "emotion",
"v": 131,
"vd": 1722237
},
{
"n": "surprise",
"o": [],
"t": "emotion",
"v": 0,
"vd": 5250
},
{
"n": "undefined",
"o": [],
"t": "emotion",
"v": 2,
"vd": 8635
}
]
/ages/ - returns the statistics of views grouped by ages: old / adult / young / kid / undefined.
"o": [
{
"n": "adult",
"o": [],
"t": "age",
"v": 24,
"vd": 576918
},
{
"n": "kid",
"o": [],
"t": "age",
"v": 0,
"vd": 0
},
{
"n": "old",
"o": [],
"t": "age",
"v": 0,
"vd": 0
},
{
"n": "undefined",
"o": [],
"t": "age",
"v": 0,
"vd": 0
},
{
"n": "young",
"o": [],
"t": "age",
"v": 111,
"vd": 1164209
}
]
/genders/ - returns the statistics of views grouped by genders: male / female / undefined.
"o": [
{
"n": "female",
"o": [],
"t": "gender",
"v": 134,
"vd": 1734514
},
{
"n": "male",
"o": [],
"t": "gender",
"v": 1,
"vd": 6613
},
{
"n": "undefined",
"o": [],
"t": "gender",
"v": 0,
"vd": 0
}
],
/devices/ - returns the statistics of views grouped by devices.
"o": [
{
"n": "1888",
"o": [],
"ots": 5,
"otsd": 33959,
"t": "device",
"v": 5,
"vd": 33959
},
{
"n": "1891",
"o": [],
"ots": 2,
"otsd": 15155,
"t": "device",
"v": 2,
"vd": 15155
},
{
"n": "1892",
"o": [],
"ots": 1,
"otsd": 20922,
"t": "device",
"v": 1,
"vd": 20922
},
{
"n": "1893",
"o": [],
"ots": 19,
"otsd": 163903,
"t": "device",
"v": 19,
"vd": 163903
},
]
/movies/ - returns the statistics of views grouped by media files.
"o": [
{
"n": "1",
"o": [],
"ots": 5,
"otsd": 33959,
"t": "movie",
"v": 5,
"vd": 33959
},
{
"n": "2",
"o": [],
"ots": 2,
"otsd": 15155,
"t": "movie",
"v": 2,
"vd": 15155
},
{
"n": "3",
"o": [],
"ots": 1,
"otsd": 20922,
"t": "movie",
"v": 1,
"vd": 20922
},
{
"n": "4",
"o": [],
"ots": 19,
"otsd": 163903,
"t": "movie",
"v": 19,
"vd": 163903
},
]
/dates/ - returns the statistics of views grouped by dates.
Note
Should be accompanied by the request argument “format”, otherwise the default format will be selected (“YYYY-MM-DD”).
"o": [
{
"n": "2017-06-02",
"o": [],
"ots": 5,
"otsd": 33959,
"t": "date",
"v": 5,
"vd": 33959
},
{
"n": "2017-06-06",
"o": [],
"ots": 22,
"otsd": 199980,
"t": "date",
"v": 22,
"vd": 199980
},
{
"n": "2017-06-07",
"o": [],
"ots": 111,
"otsd": 1516682,
"t": "date",
"v": 109,
"vd": 1508488
}
]
Full sample response:
GET https://analytics.3divi.ru/api/v2/statistics/user/371/devices/dates/emotions/?key=8b00aa55853f403186b5678fde019750&tzo=0&dt_format=MM&b=2016/12/01%2000:00:00&e=2017/06/01%2000:00:00&d=1842
{
"begin": "2016/12/01 00:00:00",
"data": {
"n": "root",
"o": [
{
"n": "1842",
"o": [
{
"n": "05",
"o": [
{
"n": "angry",
"o": [],
"t": "emotion",
"v": 0,
"vd": 0
},
{
"n": "happy",
"o": [],
"t": "emotion",
"v": 0,
"vd": 0
},
{
"n": "neutral",
"o": [],
"t": "emotion",
"v": 63,
"vd": 1359042
},
{
"n": "surprise",
"o": [],
"t": "emotion",
"v": 0,
"vd": 0
},
{
"n": "undefined",
"o": [],
"t": "emotion",
"v": 0,
"vd": 0
}
],
"ots": 63,
"otsd": 1359042,
"t": "date",
"v": 63,
"vd": 1359042
}
],
"ots": 63,
"otsd": 1359042,
"t": "device",
"v": 63,
"vd": 1359042
}
],
"ots": 63,
"otsd": 1359042,
"t": "root",
"v": 63,
"vd": 1359042
},
"dt_format": "MM",
"end": "2017/06/01 00:00:00",
"levels": [
"devices",
"dates",
"emotions"
],
"obj_in_page": 10,
"ok": 1,
"page": 0,
"pages_total": 1,
"path": "devices/dates/emotions",
"user_id": 371
}
Raw data¶
Get views for a movie (if set in request) on a device (if set in request):
-
GET /statistics/user/(int: user_id)/raw/data/
Query Parameters:
- device_id – views only for a device with this id;
- movie_id – views only for a movie with this id;
- b – beginning of the requested data (in local timezone), YYYY/MM/DD HH:mm:ss;
- e – end of the requested data (in local timezone), YYYY/MM/DD HH:mm:ss;
- tzo – timezone.
Sample response:
GET https://analytics.3divi.ru/api/statistics/user/864/raw/data/?key=42208b8df38b4e97878ce00wa765bc38&4zo=0&last_week
{
"objects": [
{ //Session: time period from the moment the face is detected until the moment the face is lost.
"a": 1, //age (0 - kid, 1 - young, 2 - adult, 3 - old)
/* Block with attention intervals. Each interval is a pair, where "a" is an attention indicator (1 - a person is looking into the camera, 0 - a person is not looking), and "d" is the duration of the interval. */
"at": [
{
"a": 1, //indicator showing that a person is looking into the camera
"d": 19334 //duration of the interval
},
{
"a": 0, //indicator showing that a person is not looking into the camera
"d": 1044 //duration of the interval
},
{
"a": 1, //indicator showing that a person is looking into the camera
"d": 14853 //duration of the interval
}
],
"b": "2019-07-01T11:16:07.052000", //beginning of the session
"d": 5315, //device_id
"e": "2019-07-01T11:16:42.283000", //end of the session
/* Block with emotion intervals, "d" - duration of the interval, "e" - emotion: -1 - undefined(u), 0 - neutral(n), 1 - happy(h), 2 - angry(a), 3 - surprised(s) */
"em": [
{
"d": 1458,
"e": 3
},
{
"d": 3948,
"e": 1
},
{
"d": 1221,
"e": 0
},
{
"d": 1278,
"e": -1
},
{
"d": 8748,
"e": 0
},
{
"d": 1328,
"e": 3
},
{
"d": 2894,
"e": 0
},
{
"d": 1246,
"e": 3
},
{
"d": 6661,
"e": 0
},
{
"d": 2020,
"e": -1
},
{
"d": 4429,
"e": 0
}
],
"i": 35231, //total session time (result of addition of all the "d" values from the "at" block or all the "d" values from the "em" block)
"o": 1331, //session number of all time on this device
"s": 0, //gender (0 - female, 1 - male)
//
/* Block with the intervals of movies that are played in one session */
"v": [
{
"d": 35231, //duration of the interval during which the video was played
"i": 8482, //movie_id
"s": 0 //beginning of the interval relative to the beginning of the session
},
{
"d": 35231, //duration of the interval during which the video was played
"i": 9457, //movie_id
"s": 0 //beginning of the interval relative to the beginning of the session
}
]
}
]
}
Status counters¶
Get accumulated counter values for a dashboard:
-
GET /user/(int:user_id)/counters
GET https://analytics.3divi.ru/api/user/632/counters?key=d482d4c3c4bd4dd796abccf726ae1266
{
"avg_duration": 6.38, (average visit duration (for all devices)
"dev_num": 3, (number of registered devices)
"movies_num": 0, (number of registered movies)
"online_device_num": 1, (number of online devices)
"usr_cur_day": 8, (number of visits for the current day)
"usr_cur_hour": 1, (number of visits for the current hour)
"usr_cur_month": 324, (number of visits for the current month)
"usr_num": 324 (total number of visits)
}
Note
If sex and age are set, gender/age counters (ex: fk for a female-kid or mo for a male-old) are included.
year, month, day, hour parameters arrange the requested statistics by time in different ways. By combining year, month, day, hour parameters you can arrange an appropriate reply structure.
year, month, day, hour set as default if none of them is specified.
Empty groups that don’t have any data are not included in the reply. For example, if statistics for the requested period arranged “by days of the week” doesn’t have views on Thursdays, then the reply will have 6 groups in accordance with days of the week: 1,2,3,5,6,7. Day No.4 (Thursday) won’t be included in the reply.