contact@realeye.io + 1 646 9803603 Sign Up Sign In
English
Home
➞
RealEye API Documentation

RealEye API Documentation

API Overview

RealEye provides an API accessed via HTTP protocol secured by TSLv2 (HTTPS).

Note:
‍This API follows Semantic Versioning guidelines.

Document last update: 2022-09-22.

HINT
‍If you are new to the eye-tracking you might find it useful to read our Eye-tracking Glossary.

RealEye API provides:

•
Study Flow
•
Eye-tracking Data Export
○
Gazes Data Export
○
Fixations Data Export
○
AOI Data Export
•
Eye-tracking Data Export
•
Facial Coding Data Export
•
Keyboard And Mouse Data Export
•
Survey Results Export
•
Studies Drop-rate Statistics Export

Example:

curl --header "X-AUTH-TOKEN: 7615d9a9-cda5-496b-b20b-b3ce8e38c87d" https://www.realeye.io/api2/studies-all/drop-rate

Study Data

Study Flow

Study Flow defines exactly how the whole test is performed.
E.g. what items (stimulis) are being shown, for how long, and any survey questions.

GET /studies/{studyId}/flow

Query Parameters:

  • string studyId UUID

Response:

Content-type: application/json

{
  "study": {
    "id": "7953ba6a-02b1-4a3d-b609-a0b3258add18"
  },
  "steps": [
    {
      "type": "message",
      "text": "Please look at the image. You can click and scroll the image.",
      "cta": {
        "text": "OK",
        "elementType": "button"
      }
    },
    {
      "type": "countdown",
      "durationMs": 3000
    },
    {
      "type": "stimuli",
      "stimuli": {
        "id": "4f6b3515-71f4-4fa3-b9ca-4fdfc1dee4ad",
        "type": "images",
        "durationMs": 20000,
        "isScrollingEnabled": true,
        "isFinishOnKeyEnabled": false,
        "isFinishOnClickEnabled": false,
        "watermarkOpacity": 0
      }
    },
    {
      "type": "question",
      "question": {
        "id": "106ea18a-4c1e-4122-8978-d6014e663694",
        "refItem": {
          "id": "4f6b3515-71f4-4fa3-b9ca-4fdfc1dee4ad"
        },
        "type": "choice",
        "text": "What is your choice?",
        "isAnswerRequired": false,
        "answerViewMode": "text",
        "sortingValue": 0,
        "answers": [
          {
            "id": "59175d4a-ddbf-41db-96e3-3b0002ebc699",
            "text": "Answer A",
            "sortingValue": 1,
            "imageUrl": null
          },
          {
            "id": "fa34d8d0-1baa-4b8d-85d1-a71c562f7de4",
            "text": "Answer B",
            "sortingValue": 2,
            "imageUrl": null
          }
        ],
        "hasRandomizedAnswers": false,
        "minAnswerCount": 1,
        "maxAnswerCount": 2
      }
    },
    {
      "type": "question",
      "question": {
        "id": "c727deea-9a89-4ead-be23-d703cf674672",
        "refItem": {
          "id": "4f6b3515-71f4-4fa3-b9ca-4fdfc1dee4ad"
        },
        "type": "form",
        "text": "N\/A",
        "isAnswerRequired": false,
        "answerViewMode": "textArea",
        "sortingValue": 0,
        "formType": "realEyeBasicSurvey"
      }
    }
  ],
  "isRealEyeBasicSurveyEnabled": true
}
Data Export API
RealEye provides an API to export data programmatically using an HTTP request.

It is also possible do download the data manually by using RealEye Dashboard.
See the Data export: CSV files on our Support page to learn more.
Eye-tracking Data Export
Common Query Parameters
General:
Fixation Filter Settings:
  • int movingMedianRangeMs (optional, default 200 ms) From 20 to 1000 ms.
  • float gazeVelocityThreshold (optional, default 150) From 1 to 400.
  • int minFixationDurationMs (optional, default 80) From 60 to maxFixationDurationMs ms.
  • int maxFixationDurationMs (optional, default 400) From minFixationDurationMs to 1000 ms.
  • int saccadeMaxDurationMs (optional, default 150) From 20 to 300.
Read more about Fixation Filter >
Gazes Data Export
Gazes - Raw
GET /studies/{studyId}/collected-data/eye-tracking/gazes/raw
Query Parameters:
  • string studyId UUID
  • int movingMedianRangeMs (optional, default 200 ms) From 20 to 1000 ms.
  • int participantQualityGradeItemMin (optional, default 1) From 1 to 6.
Response:
Content-type: text/csv
See Raw Gazes CSV Description >
Gazes - Normalized
GET /studies/{studyId}/collected-data/eye-tracking/gazes/raw
Query Parameters:
  • string studyId UUID
  • int movingMedianRangeMs (optional, default 200 ms) From 20 to 1000 ms.
  • int participantQualityGradeItemMin (optional, default 1) From 1 to 6.
Response:
Content-type: text/csv
See Raw Gazes CSV Description >
Gazes - Raw Denoised Normalized and Split
GET /studies/{studyId}/collected-data/eye-tracking/gazes/raw-denoises-normalized-split
  • string studyId UUID
  • int movingMedianRangeMs (optional, default 200 ms) From 20 to 1000 ms.
  • int participantQualityGradeItemMin (optional, default 1) From 1 to 6.
Response:
Content-type: text/csv
See Raw Gazes Denoised Normalized and Split CSV Description >
Fixations Data Export
GET /studies/{studyId}/collected-data/eye-tracking/fixations
Query Parameters:
  • string studyId UUID
  • string itemId (optional, default NULL) NULL means all study items will be included.
  • int movingMedianRangeMs (optional, default 200 ms) From 20 to 1000 ms.
  • float gazeVelocityThreshold (optional, default 150) From 1 to 400.
  • int minFixationDurationMs (optional, default 80) From 60 to maxFixationDurationMs ms.
  • int maxFixationDurationMs (optional, default 400) From minFixationDurationMs to 1000 ms.
  • int saccadeMaxDurationMs (optional, default 150) From 20 to 300.
Response:
Content-type: text/csv
See Fixations CSV Description >
AOI Data Export
AOI - Overall Stats
GET /studies/{studyId}/collected-data/eye-tracking/aois-all/overall-stats
Query Parameters:
  • string studyId UUID.
  • string itemId (optional, default NULL) UUID. NULL means all study items will be included.
  • int movingMedianRangeMs (optional, default 200 ms) From 20 to 1000 ms.
  • float gazeVelocityThreshold (optional, default 150) From 1 to 400.
  • int minFixationDurationMs (optional, default 80) From 60 to maxFixationDurationMs ms.
  • int maxFixationDurationMs (optional, default 400) From minFixationDurationMs to 1000 ms.
  • int saccadeMaxDurationMs (optional, default 150) From 20 to 300.
  • int participantQualityGradeItemMin (optional, default 1) From 1 to 6.
Response:
Content-type: text/csv
See AOI Overall Stats CSV Description >
AOI - Fixations - Stats per Participant
GET /studies/{studyId}/collected-data/eye-tracking/aois-all/fixations-stats
Query Parameters:
  • string studyId UUID.
  • string itemId (optional, default NULL) UUID. NULL means all study items will be included.
  • int movingMedianRangeMs (optional, default 200 ms) From 20 to 1000 ms.
  • float gazeVelocityThreshold (optional, default 150) From 1 to 400.
  • int minFixationDurationMs (optional, default 80) From 60 to maxFixationDurationMs ms.
  • int maxFixationDurationMs (optional, default 400) From minFixationDurationMs to 1000 ms.
  • int saccadeMaxDurationMs (optional, default 150) From 20 to 300.
Response:
Content-type: text/csv
See AOI Fixations Stats per Participant CSV Description >
AOI - Fixations - Order
GET /studies/{studyId}/collected-data/eye-tracking/aois-all/fixations-order
Query Parameters:
  • string studyId UUID.
  • string itemId (optional, default NULL) UUID. NULL means all study items will be included.
  • int movingMedianRangeMs (optional, default 200 ms) From 20 to 1000 ms.
  • float gazeVelocityThreshold (optional, default 150) From 1 to 400.
  • int minFixationDurationMs (optional, default 80) From 60 to maxFixationDurationMs ms.
  • int maxFixationDurationMs (optional, default 400) From minFixationDurationMs to 1000 ms.
  • int saccadeMaxDurationMs (optional, default 150) From 20 to 300.
Response:
Content-type: text/csv
See AOI Fixations Order CSV Description >
AOI - Clicks - Stats per Participant
GET /studies/{studyId}/collected-data/eye-tracking/aois-all/clicks-stats
Query Parameters:
  • string studyId UUID.
  • string itemId (optional, default NULL) UUID. NULL means all study items will be included.
  • int movingMedianRangeMs (optional, default 200 ms) From 20 to 1000 ms.
  • float gazeVelocityThreshold (optional, default 150) From 1 to 400.
  • int minFixationDurationMs (optional, default 80) From 60 to maxFixationDurationMs ms.
  • int maxFixationDurationMs (optional, default 400) From minFixationDurationMs to 1000 ms.
  • int saccadeMaxDurationMs (optional, default 150) From 20 to 300.
Response:
Content-type: text/csv
See AOI Click Stats CSV Description >
Keyboard And Mouse Data Export
Mouse Position and Clicks
GET /studies/{studyId}/collected-data/eye-tracking/gazes/raw
Query Parameters:
  • string studyId UUID.
  • int movingMedianRangeMs (optional, default 200 ms) From 20 to 1000 ms.
  • int participantQualityGradeItemMin (optional, default 1) From 1 to 6.
Response:
Content-type: text/csv
See Mouse Position and Clicks CSV Description >
Keyboard and Mouse Overall Stats - Per Participant
GET /studies/{studyId}/collected-data/keyboard-and-mouse/overall-per-participant
Query Parameters:
  • string studyId UUID.
  • string itemId (optional, default NULL) UUID
Response:
Content-type: text/csv


study_id,item_id,item_filename,item_cdn_url,item_stimuli_duration_ms,participant_id,participant_external_id,participant_created_at,participant_display_name,participant_age,participant_display_gender,participant_quality_grade,participant_quality_grade_item,test_item_display_order,test_duration_ms,test_finished_on_key,test_has_finished_on_click,test_click_count,notes
1db036e6-e59f-4298-b43d-c1dca649f70c,99c2beba-df06-494b-b18c-32c6104d0d1d,k_r_d1.jpg,https://cdn.realeye.io/experiments/experiment_1db036e6-e59f-4298-b43d-c1dca649f70c/project_project_lg_99c2beba-df06-494b-b18c-32c6104d0d1d.jpg,10000,65ad8647-8f6f-4e23-a87b-2bea146317ab,,2021-10-05T15:14:07+00:00,Anonymous,0,unknown,5,5,18,1533,Space,false,0,"RealEye v8.6.3; 2021-10-24T18:51:51+02:00"
1db036e6-e59f-4298-b43d-c1dca649f70c,99c2beba-df06-494b-b18c-32c6104d0d1d,k_r_d1.jpg,https://cdn.realeye.io/experiments/experiment_1db036e6-e59f-4298-b43d-c1dca649f70c/project_project_lg_99c2beba-df06-494b-b18c-32c6104d0d1d.jpg,10000,513a1c58-1555-412f-bbb2-78486397b19d,,2021-10-07T14:09:04+00:00,"Pablo, Male, 48",48,male,6,4,32,1583,Space,false,0,
1db036e6-e59f-4298-b43d-c1dca649f70c,99c2beba-df06-494b-b18c-32c6104d0d1d,k_r_d1.jpg,https://cdn.realeye.io/experiments/experiment_1db036e6-e59f-4298-b43d-c1dca649f70c/project_project_lg_99c2beba-df06-494b-b18c-32c6104d0d1d.jpg,10000,2e26dfac-fd12-49f9-bbef-334c68f2ab6f,,2021-10-08T13:42:28+00:00,"Adam, Male, 34",34,male,5,5,27,2182,Space,false,0,
1db036e6-e59f-4298-b43d-c1dca649f70c,99c2beba-df06-494b-b18c-32c6104d0d1d,k_r_d1.jpg,https://cdn.realeye.io/experiments/experiment_1db036e6-e59f-4298-b43d-c1dca649f70c/project_project_lg_99c2beba-df06-494b-b18c-32c6104d0d1d.jpg,10000,fd9b2d1f-e8dd-44e0-beb1-2f4fad1b1704,,2021-10-11T12:52:24+00:00,"Pablo right this time, Male, 48",48,male,5,6,7,1822,Space,false,0,
1db036e6-e59f-4298-b43d-c1dca649f70c,99c2beba-df06-494b-b18c-32c6104d0d1d,k_r_d1.jpg,https://cdn.realeye.io/experiments/experiment_1db036e6-e59f-4298-b43d-c1dca649f70c/project_project_lg_99c2beba-df06-494b-b18c-32c6104d0d1d.jpg,10000,c1dee728-a356-43ba-ab10-1c42d5f7f834,,2021-10-12T16:31:51+00:00,"Silvia, Female, 47",47,female,5,6,26,10191,,true,3,
1db036e6-e59f-4298-b43d-c1dca649f70c,99c2beba-df06-494b-b18c-32c6104d0d1d,k_r_d1.jpg,https://cdn.realeye.io/experiments/experiment_1db036e6-e59f-4298-b43d-c1dca649f70c/project_project_lg_99c2beba-df06-494b-b18c-32c6104d0d1d.jpg,10000,7ebb09af-65e6-4045-ba83-c46dfdc71a62,,2021-10-12T16:32:28+00:00,"Naut, Male, 38",38,male,5,5,26,10170,,true,1,
1db036e6-e59f-4298-b43d-c1dca649f70c,99c2beba-df06-494b-b18c-32c6104d0d1d,k_r_d1.jpg,https://cdn.realeye.io/experiments/experiment_1db036e6-e59f-4298-b43d-c1dca649f70c/project_project_lg_99c2beba-df06-494b-b18c-32c6104d0d1d.jpg,10000,cd8acbcc-d696-4df0-9e1e-8a40dc84c8f8,,2021-10-12T17:34:44+00:00,"sebastian, Male, 30",30,male,3,5,30,1788,Space,
1db036e6-e59f-4298-b43d-c1dca649f70c,99c2beba-df06-494b-b18c-32c6104d0d1d,k_r_d1.jpg,https://cdn.realeye.io/experiments/experiment_1db036e6-e59f-4298-b43d-c1dca649f70c/project_project_lg_99c2beba-df06-494b-b18c-32c6104d0d1d.jpg,10000,0bf6af10-02c6-443e-b9bb-0903b80d6c0d,,2021-10-13T09:57:04+00:00,"Siphiwe, Male, 19",19,male,2,3,12,4369,Space,
...
  


      





  

    
Point your smartphone camera at this QR code and confirm opening the website.

    

      QR Code
      

        
Help

        
Close

      

    

  






  

    EU Support