Changes to Sleep Time Series endpoints

[AndrewFitbit]

The sleep endpoints have been updated with the introduction of sleep stages.

If your app currently uses the v1 Sleep Time Series endpoints, then you should switch to using the Get Sleep Logs endpoint.

Check out the Sleep section of the documentation to see what's new.

[Writestuff]

What has happened with the friendly, easily comprehendible and simple to enter amendments or adjustments and corrections? This new substitution certainly does not work for either me or my husband. HELP! 

[mistyper]

When will version 1 stop being available? We just completed development using version 1 sleep and have a tight timeline. We can't really switch to 1.2 and need to use version 1 at  least until 5/2018.

[hujaek]

Someone please help me I can't post a new topic in this forum. The submit button does nothing !

[Writestuff]

I have not determined a solution to this new unfriendly sleep format yet, but remain eager to do so.

[Masoud]

Hi, We're running into an issue with the semicolon separation of total sleep record since end of March 2017. Is this endpoints format change related to that issue?

[rMirage]

Thank you very much for the update.  For some reason, I didn't get a notification about it, but I see it now.  I've looked at the new 'Sleep Logs by Date' endpoint, and there's a couple things I'm confused about:

1) the documentation says both 'stages' and 'classic' are available.  Does that mean there's a way to get one or the other?  I don't mind getting both at once, as seems to be the case in the example, but I want to check

2) the example given in the 'Sleep Logs by Date' endpoint seems to be missing some minutes of data  (it jumps from 23:58:30.000 to 00:16:30.000 in the stages example and 12:06:00.000 to 12:13:00.000 in the classic one - which should probably be 00:06:00.000 to 00:13:00.000 if it's the same day of data in the example).  Are both of these examples supposed to be minute by minute and were just missing some data, maybe from the Fitbit slipping?  Or is the classic minute-by-minute and the stages every 30 seconds (since the endpoint says 30 second granularity), as long as the Fitbit is on properly?

[rMirage]

Well for those who are trying to upgrade to the new version 1.2 sleep logs, I think I can answer at least my second question...from a sample, it looks like version 1.2 is a new 'condensed' version, which uses up less text.  One entry gives a DateTime, a level, and a seconds value - that seconds value is key, it means that the same entry is repeated for that many seconds, as far as I can tell.  So an example:

{
    "datetime": "2017-04-01T23:58:30.000",
    "level": "wake",
    "seconds": 1080
},
{
    "datetime": "2017-04-02T00:16:30.000",
    "level": "rem",
    "seconds": 1500
},

Here, the user was in the 'wake' stage for 1080 seconds, essentially 18 minutes, which lines up with the next entry, since it starts 18 minutes later.

Now, as for my first question, that one still remains.  In fact, since I now have some sample version 1.2 files from my own data, I need to ask - where are the 'classic' type entries?  If I use the version 1 endpoint on a particular day of data, I get the minute-by-minute regular restless/awake/asleep values that I expect, but when I fetch from the 1.2 endpoint for the same day and same user, all I get back are the 'stages' type data.  How do I get 'classic' type data from the version 1.2 endpoint?  The example implies we would get them both as different array entries in the JSON.  I can provide an anonymized example if necessary.

[acoravos]

Two questions about this upgrade and one feedback/typo in the docs.

(1) How can I designate if whether I'll see classic or stages data in the JSON? Right now it's a random mix for even a given user -- and I don't see any identifiers in the JSON to show which one I'm going to get (e.g., they are both found under "summary"). 

My goal is to get the # times "awake" or "wake" per night. What is the best way to write the query for this given that I don't know which type of data the JSON is going to return?

(2) I've found a strange <HTTPInternalServerError 500 Internal Server Error> edge case for the API. I am looking to analyze the past 30 days of data for a user. If I use "today's" date and "today minus 30 days" in the Get Sleep Logs By Date Range... AND the person has owned their FitBit for less than 30 days, then I'll get a <HTTPInternalServerError 500 Internal Server Error> when I make the request.

For example if they have owned their device for the past 1 week out of this 30-day range request, I'll get the error.

GET https://api.fitbit.com/1.2/user/-/sleep/date/2017-03-09/2017-04-08.json

If I change the range to be within a range of their ownership of the device, then it works fine. 

Could you update the API to use the max date that a person has available if it's less than the requested one?

Or is there a way to identify the date that they purchased the FitBit? That way, if they've owned it for less than the desired date range I could triage those users separately.

***

Finally, there is a typo in the docs. Currently it says:

GET https://api.fitbit.com/1.2/user/[user-id]/sleep/[startDate]/[endDate].json

But it should say:

GET https://api.fitbit.com/1.2/user/[user-id]/sleep/date/[startDate]/[endDate].json

[acoravos]

I'd also like to know how to get only the "classic" data from the 1.2 endpoint. 

[rMirage]

@acoravos: I think the best way to determine whether the data is classic or stages is the 'type' entry in the dictionary on the same depth as levels.  In the example (and the sample files they I've looked at from my own data) it looks like this:

"levels": {
    ...
},
...
"timeInBed": <value in minutes>,
"type":"stages"

where 'type' can be either stages or classic.  Both have a levels hash, and the type identifier is part of the hash that levels belongs to.

I have also found a mix of stages and classic data, but there's always some missing data, usually classic...for example, if the user only had one sleep session, I found only stages data from the 1.2 endpoint (the classic data was present in the version 1 endpoint as usual).  If the user had more than one sleep session, however, (the example I found had regular sleep and a nap) then the version 1.2 endpoint returned two sessions, the first one being the main sleep session - in stages data only - and the nap being in classic data only.  Now probably Fitbit has decided not to calculate stages for short sleep like naps, and that's why there's no stages data for that, but the version 1.2 endpoint seems capable of returning classic data with stages, it seems. 

For now though, the version 1.2 endpoint appears to return either stages or classic for a given sleep session, not both.  I cannot upgrade to the new endpoint until I have a way to get both, so I hope this is fixed soon.

[ChronicMigraine]

Andrew,

My spouse suffers from a chronic omnipresent migraine. In short, he always has a migraine, but it is just a matter of degree in terms of pain and other effects.

I noticed the sleep measurement and analysis feature on the Fitbit Alta. This information is VERY IMPORTANT for people who suffer from chronic migraines. If, for example, the Fitbit Alta could synchronize with an app like Manage My Pain, an app the allows users to record pain and various other facts, integrating the sleeping information, including the patterns, would be great information to provide the litany of medical providers. For example, the pain specialist could use the data to adjust the various pain relievers.with a complete and synthesized data set. The neurologist could use the data to obtain pre-certifications for another round of Botox. The health data gives real hard data.

PMC 320 (Free, iPhone, Android) is a pain tracker developed by the Brigham and Women's Hospital. It synchronized with Fitbit, but it was pulled from iTunes.

I suspect that the Migraine Trust would be interested in assisting.

Just an idea for an enterprising app developer.

ChronicMigraine

[rMirage]

@AndrewFitbit  I haven't heard anything on this topic in awhile, but it is very important to our project.  As I mentioned before, our team cannot upgrade to the new Sleep endpoint until we have a way to get the 'classic' restless/awake/asleep values that the old endpoint has.  We don't mind if the data is in the new 1.2 format, we just need the restless/awake/asleep values, as they provide different information about user sleep than the stages data does.  We're a research group, and there's much more research supporting the accuracy of wrist-based restless/awake/asleep data than wrist-based sleep stages data, that's why the 'classic' data is so important.

So, to highlight my questions: Does Fitbit intend to provide the 'classic' data (for the whole day, not just naps) through the new 1.2 endpoint at some point?  Maybe a parameter in the URL, or just putting both classic and stages in the JSON, as done in the example in the API documentation?  If not, how long can we continue using the old version 1 endpoint?

[TeleSage]

@AndrewFitbit Has there been any update on this?

We're also a research company, and are hesitant on migrating to the new endpoint until we could at least guarantee that we're getting sleep data in one, consistent format.

[bpaluzzi]

Was this announced in any way, other than just in the forum? 

Were there emails sent? 

It appears that the old endpoint is no longer working as of this week -- is that the expected case?

[mistyper]

I just checked and we have data from 7/18 using the old sleep endpoints. What day did the endpoint stop working for you? Also could someone from fitbit weigh in on this topic?

Thanks!

[masterseo]

What has happened with the friendly, easily comprehendible and simple to enter amendments or adjustments and corrections? This new substitution jasa website certainly does not work for either me or my husband.

[rMirage]

I see that the documentation of the Sleep endpoint has now been updated a bit, with the new API overhaul.  For those who need version one, they have a new link with the old v1 documentation in the API for those whose app has a 'dependency' on the old version 1 API here.  So as we've seen, we can use API v1 for sleep for at least a bit longer.

The link says support for this version may end unexpectedly - it would be useful to know when, can someone from Fitbit provide an estimate?  Or if there will be an update to the new v1.2 endpoint that allows the 'classic' data to be retrieved for everything, not replaced by stages?  Our group doesn't mind updating, as long as we can get the 'classic' type data as well as the 'stages' type.  Right now v1.2 only returns 'classic' for naps, as I've documented above.

I realize things have been very busy at Fitbit with the new API and device additions, but I and probably the other users in this thread would sincerely appreciate any feedback from Fitbit on this matter.

[jasawebsite]

When will version 1 stop being available? We just completed development using version 1 sleep and have a tight timeline. We can't really jasa seo switch to 1.2 and need to use version 1 at  least until 5/2018.

[Cytotec]

Or if there will be an update to the new v1.2 endpoint that allows the 'classic' data to be retrieved for everything, not obat penggugur kandungan replaced by stages?  Our group doesn't mind updating, as long as we can get the 'classic' type data as well as the 'stages' type.  Right now v1.2 only returns 'classic' for naps, as I've documented above.