The Resource Access API is the main part of Fitbit API and contains of long list of REST endpoints that allow reading and modifying user resources via their URLs. Currently we provide methods to work with tracker collections and their metadata, profile and social resources and actions, user's device data and general system resources. The most basic example of resources are user's activities and food log entries. Examples of resource URLs for them are:
- Fitbit API base URL is http://api.fitbit.com (we support SSL protocol, but it is not required, though you should always use SSL for initial OAuth authorization handshake).
- URI of the OAuth authorization page is https://www.fitbit.com/oauth/authorize?oauth_token=. Note that it should be the main Fitbit domain name (versus api.fitbit.com) and use SSL.
- Any endpoint supports both JSON and XML response formats.
- There are two groups of calls: Read and Read & Write. Your application should have appropriate default Access Type set to make the latter.
- Client must provide OAuth signature with each call in the Authorization header.
- Most calls are made on behalf of an authorized user with token credentials (3-legged OAuth). However, there are several Read calls that can be made with OAuth signature based on consumer_key only. Those calls allow to fetch general data (like Food Units) and public resources of Fitbit users (Get User Info, Get Body Measurements, Get Activities, Get Food Logs, Get Sleep). These calls respect privacy permissions that users set for their profiles ("Anyone" in case of consumer_key only authorization, "Anyone" or "Friends" in case of full OAuth authorization). Respective calls allow <user-id> portion in their resource paths. Whenever call supports such behavior, it would be mentioned in it's description.
All Read calls (as well as couple of sensitive Read & Write) are rate limited with the current quota of 150 calls/hour. Rate limiting is based either on CLIENT+VIEWER or CLIENT (for calls made on behalf of application, without access token in authorization header) quota types, where CLIENT is your application and VIEWER is the authorized user who makes the request. Each API application has only one CLIENT quota and number of the CLIENT+VIEWER quotas, one for each of the application's authorized users. When the limit is reached for the user or for client application API will response with 409 http status code and a json or xml message explaining what have happened (in a meantime we also will send an email to email developer's address the app was registered with explaining what have happened).
As described in Getting started 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 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). Authorized user always has access to all of his own data and doesn't affected by privacy controls.
API Unit System
The Fitbit system uses a range of units in its internal representations of data. Values that you read or write to the API should be associated with one of the unit systems we support. API defaults to metric units system. The unit system that you pass to API doesn't affect or affected by user profile defaults.
Timestamps in the API
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). The timezone setting and the UTC offset for the particular user could be easily fetched via the Get User Info call. Currently we are not providing the timezone with each and every response field, thinking about the data behind more as "days of my activity" versus the continuous activity stream.
Groups of endpoints
To simplify understanding of API architecture we divided all calls into several groups: user profile data, user collection resources (most important data), user social resources, user device data and general reference data (the only collection that is not attached to any specific user). We also tagged calls with "collection" tag to help you find the whole set of calls for that collection.
User Profile Data
Most basic API calls help to get and update profile info for the user. Note, that you can fetch profile of other user who have public profile data.
User Collection Resources
Retrieving Collection Data
There are a variety of API calls available to retrieve data pertaining to a given user, ranging from that user's body measurements to their activities, logged foods and sleep. Remember, all of these calls are governed by the privacy settings that a user has applied to their account if you are fetching data of other users.
Get Water Goal
Logging & Deleting Collection Data
Fitbit API has a number of calls available to log and delete collection tracker's data for the authorized user. The log methods are complimentary to the read methods enumerated above, and can be used together with collection metadata calls to retrieve what should be logged in each case. Please be careful and respectful when using these methods, and, as always, adhere to the Terms of Service when removing data on behalf of a user, there is no undo.
Retrieving Statistical Data
To build visualizations or gather range of statistics for the logged data on authorized user's behalf, it is possible to retrieve a variety of data for a given time period. This data currently has daily detail.
There are also several calls for reading, creating and deleting authorized user's collections metadata, that can help develop interfaces similar to Fitbit website trackers, but most commonly GET calls should be used to assist creating of log entries for those trackers.
User Social Resources
The distinct category of API endpoints provides access to platform social features like friend lists, leaderboards and also contains endpoints that allow to invite other user's to become friends and accept those invites.
User Device Data
Some applications may want to retrieve information about tracker devices status associated with the authorized user. Currently we provide only battery life status for each device.
There is a bunch of calls that describe general Fitbit system metadata like food database and catalog of activities that is not attached to specific user.