Below are the supported method calls for the Data API to interact with each type of data stored in the system. You must be logged in with the correct permissions to use these queries. Your user account will define which studies and media are visible based on their user groups.
Eye tracking results
Media query
https://eyeapi.sticky.ai/experiments/EXPID/media/MEDIAID/analy
sis/alignedrawgaze
GET Outputs a list of all gaze points sorted by participants for a specific media. Important note: Can only be used when an experiment is in “Complete” state.
1. Aligns the time codes so that time = 0 is either the start or end of the display of the media for each participant, making it easy to aggregate the results together. Adds attributes for each gaze point of 'start_time' and 'end_time' in msecs with time aligned data. For videos, this takes into account buffering and jitters, returning which frame is visible at the time.
2. Normalizes the x and y locations from pixels on the user's display to a 0.0 to 1.0 percent in x any y relative to the media when it was actually displayed. If the user looks off the media, values greater than 1.0 and less than 0.0 are acceptable.
3. Optionally adds a 'aois' element for each gaze point which lists all AOIs which this gaze point falls within and a x, y value representing the position normalized to each gaze point based on a rectangle made up of the min x, y for the upper left point and max x and y for the lower right point.
If EXPID is not a valid experiment, the response will be 'HTTP 404. Not Found'. If MEDIAID is not in the media, the response will be 'HTTP 404. Not Found'.
Body JSON or URL formated attributes:
-
participants:A JSON array of sessionIDs or a string name for a participant group which has already been defined using the /experiments/EXPID/participantgroups query. -
gaze: , or raw. simple_fixation is the initial QA version using simple location clustering and filtering if the resulting fixation is below a threshold. Default is raw. -
alignment: start or end -
start_time: a number from -length of stimulus to +length of stimulus defining the first data points to use. -
end_time: a number from -length of stimulus to +length of stimulus defining the first data points to use. -
export: json or tab to identify the file export format. -
min quality: floating point between 0.0 and 1.0 inclusive which describes the percent of gaze points which must have a 'quality' of True. This is calculated on the raw gaze data and is not influenced by fixations or raw aggregation. If the percent of elements with good quality data is less than the defined threshold, the data is dropped from the data set.
Events query
https://eyeapi.sticky.ai/experiments/EXPID/sessions/SESSIONID/
events
GET Returns a JSON event list. Can be used to retrieve viewport. If EXPID is not a valid experiment, the response will be 'HTTP 404. Not Found'. If SESSIONID is not a valid session, the response will be 'HTTP 404. Not Found'. If the log has not yet been uploaded, it will return a 'HTTP 404. Not Found'.Events can be of 3 types:
-
EVENT - Event with duration.
name - {The name of the event}
data - {Event specific details time.start - Time in msecs since 1970 time.end - Time in msecs since 1970 type - "EVENT" -
POINT - A single point in time. name - {The name of the event} data - {Event specific details time - Time in msecs since 1970 type - "POINT"
-
ERROR - An event which could not be matched between start and stop. name - {The name of the event}
data - {Event specific details
type - "ERROR:*"
Example:
[
{
data: { x1: 0,
x2: 1366,
y1: 55,
y2: 468
},
name: "stimulus.viewport",
time.start: "1376740520197",
time.stop: "1376740524705",
type: "EVENT"
},
{
data: "C:\Users\...\video_1.wmv",
name: "system.recording.webcam",
time.start: "1376740520376",
time.stop: "1376740726893",
type: "EVENT"
},
{
data: "undefined",
name: "calibration.flash",
time.start: "1376740522382",
time.stop: "1376740524381",
type: "EVENT"
},
{
data: "1,137,96",
name: "system.calibration.point",
time.start: "1376740524381",
time.stop: "1376740525879",
type: "EVENT"
},
{
data: {
x1: 0,
x2: 1366,
y1: 55,
y2: 470
},
name: "stimulus.viewport",
time.start: "1376740524705",
time.stop: "1376740524951",
type: "EVENT"
},
... ]
Session query
https://eyeapi.sticky.ai/experiments/EXPID/sessions/SESSIONID/eyetrack
GET Returns eye tracking data for session. Can be used to retrieve gaze coordinates.
If EXPID is not a valid experiment, the response will be 'HTTP 404. Not Found'.
If SESSIONID is not a valid session, the response will be 'HTTP 404. Not Found'. If the eye tracking file has not yet been uploaded, it will return a 'HTTP 404. Not Found'.
This will happen when an experiment exists but the video has not yet been processed in to an eye track file and uploaded back to the system.
Minimum gaze data format:
[
{
"start_abs":12333245233,
"end_abs":123333353255,
"xpixel":312,
"ypixel":543,
"quality": false,
},
{
"start_abs":12333211233,
"end_abs":123333345555,
"xpixel":423,
"ypixel":523,
"quality":true,
},
...
]
Notes: xpixel and ypixel must be in screen coordinates from the upper left corner. quality must be a boolean true, not a string true. start_abs and end_abs must be the time codes in UTC since 1970 in msecs. For webcams, these must be parsed from the frame barcodes.