Who is the API for
In order to get access to user’s data, a 3rd party service needs to gets user’s permission first. This is achieved using standard OAuth 2.0 protocol. The OAuth authentication is done against Google servers, please see Google documentation for more details and recommendations. The requested authentication scope should behttps://www.googleapis.com/auth/userinfo.email.
Authorization: Bearer YOUR_TOKEN
CAUTION: Currently SleepCloud only supports white-listed Client IDs. In order to make the connection running please provide us with your generated Client ID and we will white-list you ASAP.
timestamp – standard timestamp (in milliseconds) of the oldest record we are interested in. The intention is 3rd party services will remember the last timestamp used (per-user) and will always ask only for new records. Alternatively a timestamp of latest known record can be used. This argument can be left empty to fetch all records.
IMPORTANT: such a requests can be throttled and allowed only once in a time
- actigraph – set true to retrieve actigraphs – recording of user activity during the night
- labels – set true to retrieve hypnogram data and other labelled events, such as sleep phases, alarms, snoring etc.
- tags – set true to retrieve lifestyle tagging such as: caffeine, alcohol, love, medication, sport…
- comments – set true to retrieve user custom comments about the record
- sample – set true to get static testing data for easier integration
- cursor – optional starting point of a query, see pagination section below.
Return format (JSON)
fromTime: Unix timestamp of sleep start time
toTime: Unix timestamp of end of sleep
lenghtMinutes: Duration of the sleep in minutes (does not need to match to – from time, due to pausing, delayed tracking, etc..).
rating: A floating point number about user perceived quality rating of the sleep. Range from 0.0 to 5.0, where 5.0 is the best.
deepSleep: A floating point number, representing a percentage of night spent in deep sleep. Range from 0.0 to 1.0.
cycles: An integer representing a number of sleep cycle phases, see here.
timezone: in the GMT sign hours : minutes format (example GMT+03:00)
noiseLevel: Average level of noise during the night. The higher number the more noisy the night was. snoringSeconds: A total number of seconds when snoring was detected.
tags: [“home”, “alcohol”]: An array of lifestyle tags assigned to the sleep by the user or automatically
comment: An optional string entered by a user. Returned only if “comments=true” is passed in the request.
actigraph: [….]: An array of integers, containing levels of movement. The values themselves are floating point numbers, the higher number the more movement was detected. The timestamps of values are not present, but the values are uniformly spread throughout all night. The values are present only if “actigraph=true” is passed in the request.
timestamp: timestamp of an event (in milliseconds)
label: label of a specific event. See labels for events descriptions
]: Returned only in case labels=true argument was passed. The labels are sorting in time ascending order.
cursor: optional, returned only if there are more records that could be returned in a single query. See pagination comment below.
If you need to read more records than we can return (currently 500), you may need to page through the result set. You can detect this by seeing a special “cursor” node in your JSON response. If you see this, you should send a second query with exactly the same parameters as before, but in addition append a URL parameter “cursor=YOUR_CURSOR_VALUE”. This process may need to be repeated a couple of times till you get all the records you want.
ALARM_LATEST: The latest time, when alarm could have possibly ring.
ALARM_SNOOZE: User snoozed an alarm.
ALARM_SNOOZE_AFTER_KILL: Alarm was automatically snoozed due to alarm timeout
ALARM_DISMISS: User successfully dismissed alarm.
TRACKING_PAUSED: Start of a wake up time
TRACKING_RESUMED: End of the wake up time
TRACKING_STOPPED_BY_USER: User stopped tracking
ALARM_STARTED: Alarm started ringing
SNORING: Snoring detected
LOW_BATTERY: Battery is low, tracking won’t work correctly
DEEP_START: Deep sleep phase started
DEEP_END: Deep sleep phase finished
LIGHT_START: Light sleep phase started
LIGHT_END: Light sleep phase finished
REM_START: REM sleep phase started
REM_END: REM sleep phase finished
BROKEN_END: No data from sensors finished
WALKING_END: End of a walking period (imported from Google Fit)
AWAKE_START: Awake period started (from awake detection algorithm)
AWAKE_END: Awake period ended (from awake detection algorithm)
HR(true): Heart rate value
LUCID_CUE: REM sleep detected and playing a lucid dreaming cue
SPO2(true): SpO2 value
APNEA: Apnea episode detected
RR(true): Respiratory rate value