API specifications

The API Specification section provides a detailed overview of the technical components essential for integrating with the platform, including authorization scopes, data type definitions, and endpoint structures. This API represents a strategic evolution of the legacy Fitbit Web API, rebuilt on modern infrastructure to ensure a more stable and consistent developer experience.

Scopes

You must update your authorization request to use the Google Health API scopes. The scopes define whether your app supports read or write operations. Follow the scope implementation instructions, which specify only requesting needed scopes, configuring write access only when sending data, and handling partial consent gracefully.

The Google Health API scopes are a HTTP URL beginning with https://www.googleapis.com/auth/googlehealth.{scope}. For example, https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly.

Scope mappings

Here is how the Fitbit Web API scopes map to the Google Health API scopes:

Table: Fitbit Web API to Google Health API scope mappings
Fitbit Web API Scopes Google Health API Scopes
activity .activity_and_fitness.readonly
.activity_and_fitness.writeonly
blood_glucose .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
cardio_fitness .activity_and_fitness.readonly
.activity_and_fitness.writeonly
electrocardiogram .ecg.readonly
heartrate .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
irregular_rhythm_notifications .irn.readonly
location .location.readonly
nutrition .nutrition.readonly
.nutrition.writeonly
oxygen_saturation .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
profile .profile.readonly
.profile.writeonly
respiratory_rate .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
settings .settings.readonly
.settings.writeonly
sleep .sleep.readonly
.sleep.writeonly
temperature .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
weight .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly

Data types

Here is a list of Google Health API data types and how they map to the Fitbit Web API.

For more information on how data is reported for these types, see the Data presence and true zeros guide. This guide includes details on inactivity and on-wrist filtering.

Table: Fitbit Web API to Google Health API data type mappings
Fitbit Web API Data Type Google Health API Data Type
  dataType		 Description
Activity Calories Active Energy Burned
  active-energy-burned 		Represents the calories burned during active periods, inclusive of BMR for those periods. In the Google Health API, this can be reconstructed by adding BMR to the active-energy-burned data type (which tracks activity-only burn, excluding basal rate).
Active Zone Minutes Active Zone Minutes
  active-zone-minutes
Contains changes to the user's activity levels Activity Level
  activity-level
Elevation Altitude
  altitude
Activity caloriesBMR Basal Energy Burned
  basal-energy-burned 		The calories burned due to Basal Metabolic Rate (BMR) over a specific period of time.
Blood Glucose Blood Glucose
  blood-glucose
Body fat Body Fat
  body-fat
caloriesOut in each heart rate zone Calories In Heart Rate Zone
  calories-in-heart-rate-zone
Temperature (Core) Core Body Temperature
  core-body-temperature
HRV summary Daily Heart Rate Variability
  daily-heart-rate-variability
SpO2 summary Daily Oxygen Saturation
  daily-oxygen-saturation
Resting heart rate Daily Resting Heart Rate
  daily-resting-heart-rate
Skin temperature Daily Sleep Temperature Derivations
  daily-sleep-temperature-derivations
Distance Distance
  distance
Electrocardiogram (ECG) Electrocardiogram (ECG)
  electrocardiogram
Recorded activity Exercise
  exercise 		Recorded workouts or exercise sessions, which include start/end times, activity types, and session metrics.
Floors Floors
  floors
Food Food
  food
Food Measurement Unit Food Measurement Unit
  food-measurement-unit
Heart Rate Heart Rate
  heart-rate
HRV Intraday Heart Rate Variability
  heart-rate-variability
Irregular Rhythm Notifications (IRN) Irregular Rhythm Notification
  irregular-rhythm-notification
Food Log Nutrition Log
  nutrition-log
SpO2 Intraday Oxygen Saturation
  oxygen-saturation
VO2 Max value when the user runs Run VO2 Max
  run-vo2-max
Activity time series minutes sedentary Sedentary Period
  sedentary-period
Sleep Sleep
  sleep
Steps Steps
  steps
Activity time series swimming strokes Swim Lengths Data
  swim-lengths-data
Activity caloriesOut Total Calories
  total-calories 		The complete number of calories burned by a user over a period of time, inclusive of Basal Energy Burned and Active Energy Burned.
VO2 Max value VO2 Max
  vo2-max
Weight Weight
  weight

Calculations

Mappings and rules in the Google Health API differ from the Fitbit Web API.

Activity level, METs, and step thresholds

In the Google Health API, a user's minute-by-minute activity level is derived from their Metabolic Equivalent of Task (MET) and step count.

Activity level Heart rate devices Non-heart rate devices
Sedentary ≤ 1.5 METs ≤ 1.5 METs
Lightly Active > 1.5 METs and ≤ 4.2 METs > 1.5 METs and ≤ 3.5 METs
Moderately Active > 4.2 METs and < 6.0 METs
(unless conditions for Very Active are met) 		> 3.5 METs and < 6.0 METs
(unless conditions for Very Active are met)
Very Active ≥ 6.0 METs, or ≥ 5.0 METs with a step rate of 150 steps per minute or more

Active minutes consist of combined MODERATELY_ACTIVE and VERY_ACTIVE minutes. However, a highly active minute is only credited if it occurs during a continuous streak of at least 10 minutes, allowing at most 2-minute gaps of lower activity.

Sedentary minutes and sleep

Sedentary minutes don't include sleep time. In daily rollups, sedentary minutes are calculated by subtracting sleep minutes and active minutes (lightly active, moderately active, and very active) from the total minutes in the day (1,440 minutes):

Sedentary Minutes = 1440 - Sleep Minutes - Lightly Active Minutes - Moderately Active Minutes - Very Active Minutes

Endpoints

The REST endpoints adopt a consistent syntax for all data types.

  • Service Endpoint: The base HTTP URL changes to https://health.googleapis.com.
  • Endpoint Syntax: The Google Health API supports a limited number of endpoints, which can be used by most of the supported data types. This provides consistent syntax for all data types and makes the endpoints easier to use.
  • User Identifier: Either the user ID or me should be specified in the endpoint syntax. When using me, the user ID is inferred from the access token.

Example: Here's an example of the GET Profile endpoint called using the Google Health API

GET https://health.googleapis.com/v4/users/me/profile

Endpoint mappings

See Google Health API data types table for a list of data types available and the API methods they support.

Fitbit Web API Endpoint Type Google Health API
GET (Log | Summary | Daily Summary) where you are requesting a single day of data dailyRollup method with windowSize = 1 day
GET (Intraday) where you are requesting granular data list method
GET (Time Series) by Date or Interval rollUp or dailyRollUp method including a date range
GET (Log List) list method
CREATE & UPDATE Logs patch method
DELETE Logs batchDelete method
GET Profile users.getProfile returns the user's specific information
users.getSettings returns the user's units and timezones
UPDATE Profile users.updateProfile modifies the user's specific information
users.updateSettings modifies the user's units and timezones
Get User ID users.getIdentity returns the user's Fitbit legacy and Google user ID.
Get Devices users.pairedDevices returns the list of paired devices
Create Subscriptions projects.subscribers.subscriptions.create manually creates a subscription
Delete Subscriptions projects.subscribers.subscriptions.delete delete a subscription
Get Subscriptions List projects.subscribers.subscriptions.list lists all subscriptions