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:
| 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.
| Fitbit Web API Data Type | Google Health API Data TypedataType |
Description |
|---|---|---|
| Activity Calories | Active Energy Burnedactive-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 Minutesactive-zone-minutes
|
|
| Contains changes to the user's activity levels | Activity Levelactivity-level
|
|
| Elevation | Altitudealtitude
|
|
Activity caloriesBMR |
Basal Energy Burnedbasal-energy-burned
|
The calories burned due to Basal Metabolic Rate (BMR) over a specific period of time. |
| Blood Glucose | Blood Glucoseblood-glucose
|
|
| Body fat | Body Fatbody-fat
|
|
caloriesOut in each heart rate zone |
Calories In Heart Rate Zonecalories-in-heart-rate-zone
|
|
| Temperature (Core) | Core Body Temperaturecore-body-temperature
|
|
| HRV summary | Daily Heart Rate Variabilitydaily-heart-rate-variability
|
|
| SpO2 summary | Daily Oxygen Saturationdaily-oxygen-saturation
|
|
| Resting heart rate | Daily Resting Heart Ratedaily-resting-heart-rate
|
|
| Skin temperature | Daily Sleep Temperature Derivationsdaily-sleep-temperature-derivations
|
|
| Distance | Distancedistance
|
|
| Electrocardiogram (ECG) | Electrocardiogram (ECG)electrocardiogram
|
|
| Recorded activity | Exerciseexercise
|
Recorded workouts or exercise sessions, which include start/end times, activity types, and session metrics. |
| Floors | Floorsfloors
|
|
| Food | Foodfood
|
|
| Food Measurement Unit | Food Measurement Unitfood-measurement-unit
|
|
| Heart Rate | Heart Rateheart-rate
|
|
| HRV Intraday | Heart Rate Variabilityheart-rate-variability
|
|
| Irregular Rhythm Notifications (IRN) | Irregular Rhythm Notificationirregular-rhythm-notification
|
|
| Food Log | Nutrition Lognutrition-log
|
|
| SpO2 Intraday | Oxygen Saturationoxygen-saturation
|
|
| VO2 Max value when the user runs | Run VO2 Maxrun-vo2-max
|
|
| Activity time series minutes sedentary | Sedentary Periodsedentary-period
|
|
| Sleep | Sleepsleep
|
|
| Steps | Stepssteps
|
|
| Activity time series swimming strokes | Swim Lengths Dataswim-lengths-data
|
|
Activity caloriesOut |
Total Caloriestotal-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 Maxvo2-max
|
|
| Weight | Weightweight
|
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 | ≥ 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
Body Mass Index (BMI)
Because the Google Health API does not expose a built-in BMI data type, applications must calculate Body Mass Index client-side using height and weight records:
- Retrieve the user's weight in grams from the
weightGramsfield in the Weight data type. Convert this to kilograms (divide by 1,000) or pounds (divide by 453.59237). - Retrieve the user's height in millimeters from the
heightMillimetersfield in the Height data type. Convert this to meters (divide by 1,000) or inches (divide by 25.4). - Use one of the following formulas to
calculate the BMI value:
- Metric formula:
BMI = weight (kg) / [height (m)]^2 - Imperial formula:
BMI = (weight (lbs) / [height (in)]^2) * 703
- Metric formula:
The resulting BMI values correspond to the following categories:
| Weight category | BMI range |
|---|---|
| Underweight | Under 18.5 |
| Healthy weight | 18.5 to 24.9 |
| Overweight | 25 to 29.9 |
| Obese | 30 or higher |
Basal Metabolic Rate (BMR)
Basal Metabolic Rate (BMR) is the minimum number of calories required for basic bodily functions at rest. Because the Google Health API does not expose a built-in BMR data type, applications must calculate it client-side using the Harris-Benedict formula. See the Harris–Benedict equation article on Wikipedia to learn more.
To perform this calculation:
- Retrieve the user's weight in grams from the
weightGramsfield in the Weight data type and convert to kilograms (divide by 1,000). To convert pounds to kilograms, divide by 2.2. - Retrieve the user's height in millimeters from the
heightMillimetersfield in the Height data type and convert to centimeters (divide by 10). To convert inches to centimeters, multiply by 2.54. - Retrieve the user's age in years from the
agefield in the Profile resource. - Retrieve the biological sex independently (for example, by prompting the user or maintaining it in your own database), as the Google Health API does not expose this field.
- Use one of the following formulas based
on the user's biological sex:
- Men:
BMR = 66 + (13.7 x weight_kg) + (5 x height_cm) - (6.8 x age_years) - Women:
BMR = 655 + (9.6 x weight_kg) + (1.8 x height_cm) - (4.7 x age_years)
- Men:
Total Daily Energy Expenditure (TDEE)
Total Daily Energy Expenditure (TDEE) is an estimation of the total number of calories a person burns in a day, which accounts for both BMR and physical activity. To estimate the user's TDEE, multiply the BMR value by an activity factor corresponding to their lifestyle:
| Activity level | Description | Multiplier |
|---|---|---|
| Sedentary | Little or no exercise. | BMR x 1.2 |
| Lightly active | 1–3 days of exercise per week. | BMR x 1.375 |
| Moderately active | 3–5 days of exercise per week. | BMR x 1.55 |
| Very active | 6–7 days of exercise per week. | BMR x 1.725 |
| Extra active | Very hard exercise or physical job. | BMR x 1.9 |
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 informationusers.getSettings returns the user's units and timezones |
| UPDATE Profile | users.updateProfile modifies the user's specific informationusers.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 |