Official Z3Score API documentation with sample Python and MATLAB code
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is even with amiyapatanaik:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Z3Score Sleep Scoring API

Z3score provides an easy to use RESTful API to carry out sleep scoring. Associated paper will be made available soon. Sample code in MATLAB and Python are included. You will need an API key to be able to access the server. To request an API key, send in your requests to:

The included sample code requires cfslib to be able to create and stream CFS files. Download cfslib from:

GUI for the API

You can use GUI based on FASST to quickly do scoring via an user interface. The GUI is Matlab based and can be downloaded from here:

Sample Run

Clone/Download this package. In enter your email address and API key in the appropriate location.

serverURL = ''
email = ''
key = 'yourAPIKey'

Now run:


Sample Output:

License valid till: 28-February-2017 UTC.
API Call limit (hourly): 300, Epoch limit (daily): 100000
Here are the channel labels:
1. C3-M2
2. C4-M1
3. O1-M2
4. O2-M1
5. F3-M2
6. F4-M1
7. Chin1-Chin2
8. EKG
9. PG1-M2
10. PG2-M1
Enter channel C3-A1 number: 1
Enter channel C4-A2 number: 2
Enter channel EoGleft-A1 number: 9
Enter channel EoGright-A2 number: 10
Reading EDF file...
Time taken: 2.964
Converting to CFS and saving in test.cfs...
Time taken: 4.365
Now scoring
Time taken: 12.950
Auto scoring agreement with expert scorer: 85.14%, Kappa: 0.809

You can try the MATLAB sample similarly.

Score CFS file/stream

Sleep scores CFS file.

  • URL

  • Method:


  • URL Params



  • Success Response:

    • Code: 200
      Content: { status : 1 or 0, message : N epochs x 2 array, calls_left = C, epochs_left = E}
      status is 1 for success or 0 for failure.
      Sleep stages are encoded as: Wake - 0, Stage1 - 1, Stage2 - 2, Stage3 - 3, REM - 5.
      Confidence varies between 0 and 10. 0 very low confidence, 10 very high confidence.
      calls_left is the number of hourly API calls left, returned only if successful.
      epochs_left is the number of daily epochs left, returned only if successful.
  • Sample Call using CURL:

      curl  -F file=@cfsfile.cfs -F -F key=yourAPIkey

    Response (sample cfs had 6 epochs):

    "calls_left": 18, 
    "epochs_left": 57031, 
    "message": [ [0.0,8.34], [0.0,10.0], [0.0,10.0], [1.0,10.0], [1.0,10.0], [2.0,10.0]  ],
    "status": 1


  **Check API key**
 Validate API key and also check API call limits. 

* **URL**

* **Method:**

  `POST` or `GET`
*  **URL Params**

   `email=[string]`<br />
   `key=[string]`<br />

* **Success Response:**

  * **Code:** 200 <br />
    **Content:** `{ status : 1 or 0, message : validity of the license or error message, call_limit = C, epoch_limit = E}` <br />
    status is 1 for success or 0 for failure.<br />
    call_limit is the allowed number of API calls in any given hour, returned only if successful.<br />
    epoch_limit is the allowed number of epochs that can be scored in any given 24 hour period, returned only if successful.<br />

* **Sample Call using CURL:**

    curl -F -F key=yourAPIkey


"call_limit": 20, 
"epoch_limit": 60000, 
"message": "License valid till: 28-February-2017 UTC.", 
"status": 1