Get Temperature (Skin) Summary by Interval
chevron down
 

Get Temperature (Skin) Summary by Interval

This endpoint returns Temperature (Skin) data for a date range. It only returns a value for dates on which the Fitbit device was able to record Temperature (skin) data and the maximum date range cannot exceed 30 days.

Temperature (Skin) data applies specifically to a user’s “main sleep,” which is the longest single period of time asleep on a given date.

The measurement is provided at the end of a period of sleep. The data returned usually reflects a sleep period that began the day before. For example, if you request a daily Temperature (Skin) rate for 2021-12-22, it may include measurements that were taken the previous night on 2021-12-21 when the user fell asleep.

It uses units that correspond to the Accept-Language header provided.

Scope: temperature


Request

GET /1/user/[user-id]/temp/skin/date/[start-date]/[end-date].json

URI Arguments
user-id required The encoded ID of the user. Use "-" (dash) for current logged-in user.
start-date required The date in the format yyyy-MM-dd or today.
end-date required The date in the format yyyy-MM-dd or today.

Maximum range: 30 days

Request Headers
authorization required Specify the token type and Fitbit user’s access token.
Token type: Bearer
accept optional The media type of the response content the client is expecting.
Supported: application/json
accept-language optional The measurement unit system to use for response values. See Localization.
accept-locale optional The locale to use for response values. See Localization.

Examples
GET https://api.fitbit.com/1/user/-/temp/skin/date/2021-10-25/2021-11-24.json
GET https://api.fitbit.com/1/user/GGNJL9/temp/skin/date/2021-10-25/2021-11-24.json
curl -X GET "https://api.fitbit.com/1/user/-/temp/skin/date/2021-10-25/2021-11-24.json" \
-H "accept: application/json" \
-H "authorization: Bearer <access_token>"


Response

Element Name Description
tempSkin : dateTime The log date in the format YYYY-MM-DD.
tempSkin : value : nightlyRelative The user's average temperature during a period of sleep.

It is displayed to the user as a delta from their baseline temperature in degrees Celsius or Fahrenheit depending on the country specified in the Accept-Language header. See How can Fitbit help me track my temperature? for more information.
tempSkin : value : logType The type of skin temperature log created. See Temperature Sensors for more information
Supported: dedicated_temp_sensor | other_sensors
{
    "tempSkin": [
        {
            "dateTime": "2019-12-10",
            "value": {
               "nightlyRelative": 0.3
            },
            "logType": "dedicated_temp_sensor"
        },
        {
            "dateTime": "2019-12-11",
            "value": {
              "nightlyRelative": -0.2
            },
            "logType": "dedicated_temp_sensor"
        },
        {
            "dateTime": "2019-12-12",
            "value": {
              "nightlyRelative": 2
            },
            "logType": "dedicated_temp_sensor"
        },
    ]
}
      

Response Headers
content-type The media type of the response content being sent to the client.
Supported: application/json
fitbit-rate-limit-limit The quota number of calls.
fitbit-rate-limit-remaining The number of calls remaining before hitting the rate limit.
fitbit-rate-limit-reset The number of seconds until the rate limit resets.

Note: The rate limit headers are approximate and asynchronously updated. This means that there may be a minor delay in the decrementing of remaining requests. This could result in your application receiving an unexpected 429 response if you don't track the total number of requests you make yourself.

Response Type

HTTP Status Code HTTP response code. List of codes are found in the Troubleshooting Guide.
Status Message Description of the status code.
Response Body Contains the JSON response to the API call. When errors are returned by the API call, the errorType, fieldName and message text will provide more information to the cause of the failure.

Response Codes
200 A successful request.
400 The request had bad syntax or was inherently impossible to be satisfied.
401 The request requires user authentication.

Note: For a complete list of response codes, please refer to the Troubleshooting Guide.

Additional Information

Sleep periods

The value returned does not apply to a single date, necessarily, but to a measurement taken during a period of sleep. For most users, this will span two dates to account for Temperature (Skin) values on the date at which the summary was provided, as well as during the previous night’s sleep.

Collecting Temperature (Skin) data

Temperature (Skin) data is collected when the user is in an extended period of sleep of at least 3 hours.

There are many factors that can affect a user’s Temperature (Skin) value. Recording the data while a person is asleep allows the Fitbit device to correctly and accurately collect Temperature (Skin) data. Data is only processed when the user is still. If a user moves too much or their sleep session is too short, this can prevent Temperature (Skin) data from being processed correctly. In addition, if recorded data is incapable of computing specific sleep stages for a period of sleep, this will compromise the user’s ability to retrieve a Temperature (Skin) value.

The device automatically stops collecting Temperature (Skin) data after it determines the user is awake, typically through physical movements. Once the user syncs their device, Temperature (Skin) data will begin processing for that sleep period. It usually takes up to 15 minutes for the data to be processed and made available to download.

Subscription Support for Temperature (Skin)

Temperature (Skin) does not support subscription notifications (webhooks). Since Temperature (Skin) is recorded during periods of sleep, the sleep notification arrival time can be used to estimate when the Temperature (Skin) data will be available (See the "Collecting Data" section). For applications that do not track sleep, or cannot retrieve sleep data, we recommend querying the Temperature (Skin) data once or twice a day to determine if new data is available (e.g. 12 noon and midnight). However, the frequency or rate at which you query Temperature (Skin) data should be based on your specific use cases and with this in mind.

Rate limit

The Temperature (Skin) endpoints are bound by our standard rate limit. See Rate Limits.

Device compatibility

Temperature (Skin) data is retrieved from the user’s Fitbit account. This gives the user secure and transparent control over their data. The data is then processed and made available through the API after the user syncs their device with the Fitbit data service.

Most of the current devices sold support Temperature (Skin) data collection. See the Fitbit Product page to determine if your specific device supports Temperature (Skin).

Temperature Sensors

Some Fitbit devices use a dedicated temperature sensor to estimate the user’s skin temperature variation each night. Other Fitbit devices use other sensors to measure the temperature in the user’s surrounding area. See How can Fitbit help me track my temperature? for more information.