Overview

Fitbit provides a Web API for accessing data from Fitbit activity trackers, Aria scale, 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's API Terms of Use.

Note: All API requests must use HTTPS.

App Registration

To use the Fitbit Web API, you must register your application at dev.fitbit.com.

App Types

When registering your application, select the appropriate "OAuth 2.0 Application Type".

Server

"Server" applications authenticate using the Authorization Code Grant Flow.

Client

"Client" applications authenticate using either the Authorization Code Grant Flow or the Implicit Grant Flow. An advantage of "Client" applications is that they allow for client-side authentication.

Personal

"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.

Authentication

The Fitbit Web API uses OAuth 2.0 protocol for user authorization.

Numerical Ids

All integer ids for resources should be considered unsigned 64 bit integers.

Libraries

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.

Localization

Language

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:

Accept-HeaderLocale
en_AUAustralia
fr_FRFrance
de_DEGermany
ja_JPJapan
en_NZNew Zealand
es_ESSpain
en_GBUnited Kingdom
en_USUnited States (default)

Time Zones

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.

Units

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.

Accept-LanguageUnit System
en_USUS
en_GBUK
none of the above or not providedMETRIC

Unit Systems

US

Unit TypeUnit
durationmilliseconds
distancemiles
elevationfeet
heightinches
weightpounds
body measurementsinches
liquidsfluid ounces (fl oz)
blood glucosemilligrams per deciliter (mg/dL) (mass concentration)

UK

Unit TypeUnit
durationmilliseconds
distancekilometers
elevationmeters
heightcentimeters
weightstone*
body measurementscentimeters
liquidsmillileters
blood glucosemillimoes 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.

Metric

Unit TypeUnit
durationmilliseconds
distancekilometers
elevationmeters
heightcentimeters
weightkilograms
body measurementscentimeters
liquidsmilliliters
blood glucosemillimoles per liter (mmol/dl) (molar concentration)

Food Databases

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.

Privacy controls

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.

Rate Limits

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.

Response Headers

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 "Retry-After" header is sent with the number of seconds until your rate limit is reset and you can begin making calls again.