Different Response Behaviors for Dates Without Data

[davidfifer]

I'm currently looking at requesting several FitBit resources over some monthly window.  I purchased an Inspire HR to start building up some data that I could use for testing.  I've noticed a few things when manipulating the date window:

• For many activities, I see some default value come back when I request data from a point prior to the date I obtained my Inspire HR.  Calories in particular has been interesting as I have seen this "default value" change.
• In a different case of missing data, the Inspire HR does not include the altimeter and will not provide metrics such as floors climbed.  That endpoint, however, returns a 400 error.

While I am still working on building out the rest of my integration with the FitBit API, I'm wondering what best practices should be taken to handle data from "invalid" dates or gracefully handling errors returned from non-supported endpoints.

[JohnFitbit]

Hi @davidfifer,

Welcome to the forums!

Seeing calorie data from before your Inspire HR's pair date is normal behavior. According to our help article "How does Fitbit estimate how many calories I've burned?", the calorie burn data you see before you set up your Inspire HR is your basal metabolic rate (BMR).

This is the rate at which you burn calories at rest, just to maintain vital body functions like breathing, heartbeat, and brain activity. Your BMR usually accounts for at least half of the calories you burn in a day (without activities) and is estimated based on the physical data you entered when you set up your account: sex, age, height, and weight. This data is typically the same every day as it does not include your activity calories tracked by your device.

In regard to the endpoint returning a 400, can you please provide me with the endpoint you are querying as I am not able to reproduce the issue? Also, can you provide the full API response you are receiving?

I look forward to hearing from you.

[davidfifer]

Thanks for the welcome!

That doesn't quite address at my concern.  Looking at the default values for the endpoints I've mapped so far, everything seems to be 0 except for minutes sedentary (1440) and calories (either 1513 or 1517).  I notice calories changed over time prior to my account's creation, but I don't have the dates on-hand to provide.

While I can request the user details through the user endpoint, the "memberSince" property should only tell me when that user created the FitBit account, correct?  That doesn't guarantee that the user would have activated a device on that date.  Any date requested between the memberSince data and this "device activation" date would result in the default values I mentioned earlier being returned in the response.  This means that instead of receiving no data, I am receiving data that I have to ignore.  When the default values match actual data, this means I could be throwing away valid data points because they match up with default values.  It is this ambiguity that I am trying to find out how to (nicely) avoid.

As for the 400 response from the floors endpoint, the behavior I noticed was the same as in this thread.

[JohnFitbit]

Hi @davidfifer,

Thanks for the additional info.

Can you provide me with the default values that you are seeing, along with the endpoints you are querying, and JSON responses you are receiving?

As for the calories you've noticed have changed over time, do you have any screenshots so that I can get a better understanding of where you are looking?

You are correct in the "memberSince" property telling you when the account has been created. Most often than not, a tracker may also be paired that same day. I don't believe any of our endpoints return the date of which a device was paired to an account.

As for the 400 error, I attempted to reproduce the endpoint mentioned in the thread you provided with an Inspire HR, and I was still able to get a response. See below:

GET "https://api.fitbit.com/1/user/-/activities/floors/date/2019-07-30/2019-08-06.json"

{
  "activities-floors": [
    {
      "dateTime": "2019-07-30",
      "value": "0"
    },
    {
      "dateTime": "2019-07-31",
      "value": "0"
    },
    {
      "dateTime": "2019-08-01",
      "value": "0"
    },
    {
      "dateTime": "2019-08-02",
      "value": "0"
    },
    {
      "dateTime": "2019-08-03",
      "value": "0"
    },
    {
      "dateTime": "2019-08-04",
      "value": "0"
    },
    {
      "dateTime": "2019-08-05",
      "value": "0"
    },
    {
      "dateTime": "2019-08-06",
      "value": "0"
    }
  ]
}

Can you please provide me with the full URL endpoint you queried as I believe there may be an issue with how it was formatted?

I look forward to hearing from you. 

[davidfifer]

I created my account mid-July, so all requests will be made prior to the date I joined.  I will list all requests below, but for the sake of space, I will just list the returned value; every response followed the same expected format of:

{
    "activities-<ACTIVITY>": [
        {
            "dateTime": "2019-07-05",
            "value": <VALUE>
        }
    ]
}

• Calories

  • GET https://api.fitbit.com/1/user/-/activities/calories/date/2019-05-05/2019-05-05.json

    Returns 1517

  • GET https://api.fitbit.com/1/user/-/activities/calories/date/2019-07-05/2019-07-05.json

    Returns 1513 
• Calories BMR

  • GET https://api.fitbit.com/1/user/-/activities/caloriesBMR/date/2019-05-05/2019-05-05.json

    Returns 1517

  • GET https://api.fitbit.com/1/user/-/activities/caloriesBMR/date/2019-07-05/2019-07-05.json

    Returns 1513
• Steps

  • GET https://api.fitbit.com/1/user/-/activities/steps/date/2019-07-05/2019-07-05.json

    Returns 0
• Distance

  • GET https://api.fitbit.com/1/user/-/activities/distance/date/2019-07-05/2019-07-05.json

    Returns 0.0
• Minutes Sedentary

  • GET https://api.fitbit.com/1/user/-/activities/minutesSedentary/date/2019-07-05/2019-07-05.json

    Returns 1440
• Minutes Lightly Active

  • GET https://api.fitbit.com/1/user/-/activities/minutesLightlyActive/date/2019-07-05/2019-07-05.json

    Returns 0
• Minutes Fairly Active

  • GET https://api.fitbit.com/1/user/-/activities/minutesFairlyActive/date/2019-07-05/2019-07-05.json

    Returns 0
• Minutes Very Active

  • GET https://api.fitbit.com/1/user/-/activities/minutesVeryActive/date/2019-07-05/2019-07-05.json

    Returns 0
• Activity Calories

  • GET https://api.fitbit.com/1/user/-/activities/activityCalories/date/2019-07-05/2019-07-05.json

    Returns 0

For the floors activity, I made the same request as you:

GET https://api.fitbit.com/1/user/-/activities/floors/date/2019-07-30/2019-08-06.json

With the only user-added header being the required Authorization header.  This request resulted in the following response:

{
    "errors": [
        {
            "errorType": "validation",
            "fieldName": "resource path",
            "message": "Invalid time series resource path: /activities/floors"
        }
    ]
}

[JohnFitbit]

Hi @davidfifer,

Thanks for the thorough information you provided.

After some digging, I can confirm that your account does show fluctuations in your calorie burn data (before your Inspire HR pair date). It looks like every month, your calorie burn is bouncing between 1513 per day to 1518 per day. With that in mind, this appears to be a bug. This number should typically be the same until the pairing of your device, and activity levels above sedentary begin to be recorded. 

Steps and distance are expected to be 0 since you did not have a device paired at those times. Minutes for lightly active, fairly active, very active, and activity calories are also expected to be 0 because these are calories burned during activities. Since you did not have a device paired at this time, this data cannot be recorded and will return 0s.

However, the 1440 minutesSedentary that you see, is also expected behavior. Sedentary minutes are known as inactive minutes and help determine your base BMR when you're not active. The 1513/1518 calories you're seeing are your calories burned from sedentary minutes when you're sitting or not doing anything at all. 

To avoid querying and seeing this data, I would suggest not querying dates prior to the date you paired your Inspire HR to your account, which according to our logs is 7/9, as you will be returned with BMR data based on the information you provided during account creation. Alternatively, if you want to ensure that you extract data collected by a device when it was worn vs when it wasn't worn/paired to the account, I recommend using the /activities/tracker/ resource path when using the Activity Time Series endpoints:

activities/tracker/calories
activities/tracker/steps
activities/tracker/distance
activities/tracker/floors
activities/tracker/elevation
activities/tracker/minutesSedentary
activities/tracker/minutesLightlyActive
activities/tracker/minutesFairlyActive
activities/tracker/minutesVeryActive
activities/tracker/activityCalories

This resource represents the daily activity values logged by the tracker device only, excluding manual activity log entries.

In regard to the GET activities/floors/date endpoint, I was able to confirm that I am only able to see a response for querying this endpoint due to my permissions. On a normal user account, it is expected to be returned with the invalid time-series resource path error due to the device not having a sensor to track floors. 

I apologize for any confusion this may have caused, and I hope this helps!