Fitbit Web API Basics
Fitbit provides a Web API for accessing data from Fitbit activity trackers, Aria & Aria 2 scales, and manually entered logs. Anyone can develop an application to access and modify a Fitbit user's data on their behalf, so long as it complies with Fitbit Platform Terms of Service.
Note: All API requests must use HTTPS.
To use the Fitbit Web API, you must register your application at dev.fitbit.com.
When registering your application, select the appropriate "OAuth 2.0 Application Type".
"Server" applications authenticate using the Authorization Code Grant Flow.
"Personal" applications authenticate using either the Authorization Code Grant Flow or the Implicit Grant Flow, and also have access to the intraday time series data (such as Heart Rate or Activity) of the owner of the app only.
The Fitbit Web API uses OAuth 2.0 protocol for user authorization.
All integer ids for resources should be considered unsigned 64 bit integers.
The Fitbit Web API has a common implementation of the OAuth 2.0 specification. You don't need a Fitbit-specific library to use the Fitbit Web API. Instead, we recommend that you use the best OAuth 2.0 or HTTP client library available for your platform. If you don't have a favorite OAuth 2.0 or HTTP library yet, here is a list of some people have told us worked for them.
Some of the API responses include text fields that may be suitable for
displaying to the end user. Setting the
Accept-Locale header will return a
translated response if available. We currently support the following locales:
|en_US||United States (default)|
Fitbit does not support time zones for data. Users can specify a time zone in their settings, but this offset is only used to determine the start of their 24-hour period. As such, there is no way to request a specific time zone, because all data is aligned with the user's specified UTC offset.
All date and time related fields in the API requests and responses are rendered in the local time of the resource owner's timezone (either authorized user or the owner of the resource requested).
A user's current time zone and UTC offset in milliseconds can be retrieved through the Get Profile endpoint.
API calls reveal and log resource values in one of the unit systems based on the
value of the
Accept-Language header. If an endpoint respects the
Accept-Language header, it is explicitly mentioned in the endpoint details.
|none of the above or not provided||METRIC|
|liquids||fluid ounces (fl oz)|
|blood glucose||milligrams per deciliter (mg/dL) (mass concentration)|
|blood glucose||millimoles per liter (mmol/l) (molar concentration)|
Note that the API uses decimal values for all unit types, so UK weight will be expressed as 10.5 stone instead of 10 stone 7 pounds.
|blood glucose||millimoles per liter (mmol/dl) (molar concentration)|
Requests to food related APIs may specify the
foodDatabase query parameter
with the food locale they wish to use. The allowed values are returned from the
Food Locales API.
Some calls allow to fetch resources of other users with full OAuth authorization on behalf of the authorized user or public data without full OAuth authorization on behalf of the client. Currently the following user profile privacy controls affect the visibility of this data: About Me, Age and Height, Location (affect profile fields visibility), Weight & BMI, Activities, Foods, Friends, Sleep (affect complete access to those endpoints). An authorized user always has access to all of their own data and is not affected by privacy controls.
The Fitbit API has two separate rate limits on the number of calls an app can make. Both are hourly limits that reset at the start of the hour.
The Client + Viewer Rate Limit
You can make 150 API requests per hour for each user that has authorized your application to access their data. This rate limit is applied when you make an API request using the user's access token.
The vast majority of your API calls should use the user's access token. As such, because these API requests are metered per user, your application will not be constrained as your user base grows.
The Client Rate Limit
Your application can make 150 API requests per hour without a user access token. These types of API requests are for retrieving non-user data, such as Fitbit's general resources (Browse Activities, Get Activity, Search Foods, Get Food, and Get Food Units).
Automatic Email Notices
The Fitbit API will email the application owner when the hourly rate limit is exceeded. These are courtesy notices and do not require action unless you would like to optimize your API integration.
Fitbit API responses include headers that provide you with your rate limit status.
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.
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.
Hitting the Rate Limit
Your application will receive an HTTP 429 response from the Fitbit API when a
request is not fulfilled due to reaching the rate limit. A
is sent with the number of seconds until your rate limit is reset and you can
begin making calls again.