api v1 datasets - nsrr/sleepdata.org GitHub Wiki

Datasets API

Get All Datasets

This endpoint retrieves datasets.

HTTP Request

GET https://sleepdata.org/api/v1/datasets.json

Query Parameters

Parameter Default Description
auth_token null (Optional) Include to access private datasets, using token found at https://sleepdata.org/token.
page 1 Increment over successive requests to retrieve all datasets. A request that return [] or a number of datasets less than 18 indicates the last page.

Curl Examples

Get the first page of public datasets.

curl -i https://sleepdata.org/api/v1/datasets.json

Get the second page of public datasets.

curl -i https://sleepdata.org/api/v1/datasets.json?page=2

Get public and private datasets.

curl -i https://sleepdata.org/api/v1/datasets.json?auth_token=<AUTH_TOKEN>

The above commands return JSON structured like this:

[  
   {  
      "name":"Sleep Heart Health Study",
      "slug":"shhs",
      "created_at":"2013-10-23T13:40:01.590-04:00",
      "updated_at":"2018-10-16T10:29:30.916-04:00",
      "path":"/datasets/shhs.json"
   },
   {  
      "name":"Study of Osteoporotic Fractures",
      "slug":"sof",
      "created_at":"2014-07-11T16:54:42.819-04:00",
      "updated_at":"2018-10-16T10:31:06.912-04:00",
      "path":"/datasets/sof.json"
   },
   ...
]

Get Dataset

This endpoint retrieves a specific dataset.

HTTP Request

GET https://sleepdata.org/api/v1/datasets/<SLUG>.json

Query Parameters

Parameter Default Description
auth_token null (Optional) Include to access private datasets, using token found at https://sleepdata.org/token.
SLUG 1 The SLUG of the dataset to retrieve.

Curl Example

Get the SHHS dataset.

curl -i https://sleepdata.org/api/v1/datasets/shhs.json

The above command returns JSON structured like this:

{  
   "name":"Sleep Heart Health Study",
   "slug":"shhs",
   "created_at":"2013-10-23T13:40:01.590-04:00",
   "updated_at":"2018-10-16T10:29:30.916-04:00"
}

List Files in Folder

This endpoint retrieves dataset files in a folder. NOTE: This endpoint does not recursively retrieve files, it only gets files that are immediate children in the specified folder.

HTTP Request

GET https://sleepdata.org/api/v1/datasets/<SLUG>/files.json

Query Parameters

Parameter Default Description
auth_token null (Optional) Include to access private datasets, using token found at https://sleepdata.org/token.
path null Specify the folder to list current dataset files and folders.
SLUG 1 The SLUG of the dataset to retrieve.

Curl Example

List files and folders in the SHHS dataset root folder.

curl -i https://sleepdata.org/datasets/shhs/files.json

The above command returns JSON structured like this:

[  
   {  
      "dataset":"shhs",
      "full_path":"biostatistics-with-r",
      "folder":"",
      "file_name":"biostatistics-with-r",
      "is_file":false,
      "file_size":0,
      "file_checksum_md5":null,
      "archived":false
   },
   {  
      "dataset":"shhs",
      "full_path":"datasets",
      "folder":"",
      "file_name":"datasets",
      "is_file":false,
      "file_size":0,
      "file_checksum_md5":null,
      "archived":false
   },
   {  
      "dataset":"shhs",
      "full_path":"documentation",
      "folder":"",
      "file_name":"documentation",
      "is_file":false,
      "file_size":0,
      "file_checksum_md5":null,
      "archived":false
   },
   {  
      "dataset":"shhs",
      "full_path":"forms",
      "folder":"",
      "file_name":"forms",
      "is_file":false,
      "file_size":0,
      "file_checksum_md5":null,
      "archived":false
   },
   {  
      "dataset":"shhs",
      "full_path":"polysomnography",
      "folder":"",
      "file_name":"polysomnography",
      "is_file":false,
      "file_size":4096,
      "file_checksum_md5":null,
      "archived":false
   }
]

List files and folder in the SHHS datasets folder.

curl -i https://sleepdata.org/api/v1/datasets/shhs/files.json?path=datasets

The above command returns JSON structured like this:

[  
   {  
      "dataset":"shhs",
      "full_path":"datasets/hrv-analysis",
      "folder":"datasets/",
      "file_name":"hrv-analysis",
      "is_file":false,
      "file_size":0,
      "file_checksum_md5":null,
      "archived":false
   },
   {  
      "dataset":"shhs",
      "full_path":"datasets/CHANGELOG.md",
      "folder":"datasets/",
      "file_name":"CHANGELOG.md",
      "is_file":true,
      "file_size":10175,
      "file_checksum_md5":"1432504de974e712e1cd7d99038bdfd5",
      "archived":false
   },
   {  
      "dataset":"shhs",
      "full_path":"datasets/KNOWNISSUES.md",
      "folder":"datasets/",
      "file_name":"KNOWNISSUES.md",
      "is_file":true,
      "file_size":11284,
      "file_checksum_md5":"c53ea822afa2e78ba601da508562775d",
      "archived":false
   },
   {  
      "dataset":"shhs",
      "full_path":"datasets/shhs1-dataset-0.13.0.csv",
      "folder":"datasets/",
      "file_name":"shhs1-dataset-0.13.0.csv",
      "is_file":true,
      "file_size":24305606,
      "file_checksum_md5":"212cf854c1e04ce6d75cb6580917e3a9",
      "archived":false
   },
   ...
]

Download a File

This endpoint downloads a specific file.

HTTP Request

GET https://sleepdata.org/datasets/<SLUG>/files/((a/<AUTH_TOKEN>)/m/<MEDIUM>)/<PATH>

Query Parameters

Parameter Default Description
auth_token null (Optional) Include to access private datasets, using token found at https://sleepdata.org/token.
medium null Specify the tool being used to download the file.
slug null The dataset slug.
path null The path to the file to download.

Curl Example

Download the publicly available CHANGELOG.md.

curl -O https://sleepdata.org/datasets/shhs/files/m/curl/datasets/CHANGELOG.md

md5 CHANGELOG.md
MD5 (CHANGELOG.md) = 1432504de974e712e1cd7d99038bdfd5

The above command downloads CHANGELOG.md to the present working directory.

Download a file that requires an approved data request.

curl -O https://sleepdata.org/datasets/shhs/files/a/<AUTH_TOKEN>/m/curl/datasets/archive/0.13.1/shhs1-dataset-0.13.0.csv

md5 shhs1-dataset-0.13.0.csv
MD5 (shhs1-dataset-0.13.0.csv) = 212cf854c1e04ce6d75cb6580917e3a9
⚠️ **GitHub.com Fallback** ⚠️