Sleep Data Rarely Contains "levels.summary" Data

[Jeff_New_Ocean]

Regarding the sleep endpoint

https://api.fitbit.com/1.2/user/-/sleep/date/{date}.json

When I had first implemented our integration, I was retrieving the sleep values from the "levels" property of the sleep[] array, and this seemed to be consistently available. For example:

sleep[*].levels.summary.deep.minutes

However, it seems that lately these nodes aren't available but in a very small percentage of responses.

Can you give some guidance on the best method to retrieve the total values for that will always work?:

• Wake Count
• Wake Minutes
• Deep Minutes
• Light Minutes
• REM Minutes
• Total Sleep Minutes

For example, the $.summary.stages node seems to be there more often, but not always.

Is it a case of I have to check multiple places?

Thanks,
Jeff

[Jeff_New_Ocean]

Update: Reviewed the information about message types at https://dev.fitbit.com/build/reference/web-api/sleep/get-sleep-log-by-date, it seems that the response payload example is shortened. Or I am not reading it correctly. Do you have examples of the classic and new sleep payloads?

[Gordon-C]

Hi @Jeff_New_Ocean 

Fitbit will return 2 types of sleep logs based on the amount of data we are able to collect throughout the night.

• Stages - the stages sleep log will return more granular data demonstrating when a user is in wake, deep, rem or light sleep stage.  Typically we need about 3 hours of sleep data to create the sleep stage log.
• Classic - the classic sleep log returns more generalized sleep data demonstrating when a user is awake, restless and asleep.  These sleep logs are generated when we have less than 3 hours of sleep data, the user moved around too much while sleep, do not have enough heart rate data, etc.

The 2 sleep logs are similar in the structure of the response.   The Get Sleep Log by Date Range endpoint has an example response contain both a classic and stages sleep log.

Also, the infoCode element response will try to give some reason why the particular sleep log was created.   And, the logType element response will let you know if the sleep log was created by the device, or manually created or edited by the user.

[Jeff_New_Ocean]

Hi @Gordon-C,

Thanks for the response. I do remember the blurb about the stages vs. classic from a couple years ago, but I'm almost positive from our original testing that I was consistently getting the deep/light/REM values form the sleep[*].levels.summary node a couple years back.

Regardless, I've reconfigured as follows, if you would have any comments, that would be great.

(Note that we process each sleep entry in the sleep[] array as a separate entry, so the root level $.summary node isn't useful for our purposes.)

Sleep Measure (Id)	Configuration (in $.sleep[*] array)
Total Sleep (42)	Stages / Classic: $.minutesAsleep
Deep Sleep (73)	Stages: $.levels.summary.deep.minutes Classic: Not Available
Light Sleep (74)	Stages: $.levels.summary.light.minutes Classic: Not Available
REM Sleep (75)	Stages: $.levels.summary.rem.minutes Classic: Not Available
Wake Time (72)	Stages: $.levels.summary.wake.minutes Classic: $.levels.summary.awake.minutes
Wake Count (76)	Stages: $.levels.summary.wake.count Classic: $.levels.summary.awake.count

We don't have a corresponding measure for restless sleep.

I have tested this and found it to be working. However, I did notice that the numbers for Stage's wake count seem to be a lot higher (typically double digits) than the Classic's awake count (usually single digits). Not sure if they have a different interpretation. 

Thanks,
Jeff

[Gordon-C · Accepted solution]

Yes, I think what you have there is fine.  The Stages logs are going to track short wake periods in 30 second intervals.  While, I think, the classic sleep logs show awake periods in 60 seconds.   Also, the stages logs will have some overlap between the "shortData" and the sleep stage "data".  The "shortData" will take precedence by overriding any of the sleep stages in the "Data" section.  We have more information in the section Interpreting the Sleep Stage and Short Data.

[Jeff_New_Ocean]

Thanks @Gordon-C.