Who is the API for
Authentication
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.
For examples of OAuth client implementation see Google’s Developer Guide on OAuth 2.0, especially the section Web Server Applications.
Methods
URL
https://sleep-cloud.appspot.com/fetchRecords?timestamp=STANDARD_TIMESTAMP_IN_MILLIES
Parameters
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)
sleeps:
[{
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.
labels: [
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.
},
{
fromTime: …..
….
},
…….
]
cursor: optional, returned only if there are more records that could be returned in a single query. See pagination comment below.
Pagination
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.
Event labels
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
4 thoughts on “SleepCloud Storage API”
Hello:
I’m trying to arrange that a Google Script program can get access to people’s FitBit data with their consent. I’ve been following directions and am now submitting my OAuth 2.0 id to be put on your white list. It is
196f4e1bde1a1f189d3a2d7845a30ec07fdff9d2
Dear James, could you please contact [email protected] with this request? Many thanks
Hello, I’m adding this for the next SleepCloud deploy..
HI
i have several question.
1.when will you deploy?
2.The “Bearer YOUR_TOKEN” is access_token or id_token?
Comments are closed.