Develop Steps Experiences with Google Health API

The Google Health API tracks user steps and activity data using the steps interval data type. Steps count represents a fundamental measure of daily physical activity, helping developers track fitness progress, calculate energy expenditure, and build user-facing daily activity summaries.

Understand how to read and structure steps count metrics in your application to deliver the best experience for your users.

Supported data types

The API supports the following data type for tracking step counts:

Table: Google Health API Steps data types
Data type
  dataType
  filter parameter		 Record
type		 Available
operations		 Scope Webhook
support		 True zeros
support
Steps
  steps
  steps

  Steps guide

Compatible devices

 		Interval list, reconcile, rollup, dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly

The following sections provide technical details for the steps data type, including REST representation examples and integration guidelines.

Required scopes

To access this data type, your app must request the following OAuth scopes:

  • Read: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • Write: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly

Guidelines

When integrating steps tracking into your app, follow these design and implementation guidelines.

Daily overview

To aggregate daily step counts accurately under travel, time zone changes, or daylight savings, don't perform client-side duration calculations. Instead, query the dailyRollUp endpoint which reconciles physical data gaps automatically using the UTC offsets. The rollup returns a StepsRollupValue containing the countSum field, representing the total accumulated steps for the requested day.

Drawing user interfaces (Reconciliation)

When building user interface elements to display step data, use the reconcile endpoint. If multiple data sources (such as a smartwatch and a mobile phone) have recorded steps at the same time, the reconcile endpoint resolves conflicts and merges the streams to return a single, reconciled data stream.

Intraday tracking and histograms

To display detailed user activity throughout the day (such as charts and graphs):

  • Hourly step histograms: Query the rollUp endpoint, specifying the duration (e.g. 3600s for 1 hour) using the windowSize parameter.
  • All step records: Use the list endpoint to fetch the most granular, raw step records.

Both the rollUp and reconcile endpoints accept the dataSourceFamily query parameter, allowing you to filter data from specific source groups.

Real-time sync using webhooks

Subscribe to the steps data type collection to get notified in real time when new step data is imported or synchronized. Rather than polling REST endpoints, update client-side dashboards dynamically in response to these webhook notifications. For details on how to set up subscriptions, see Webhook subscriptions.

Handle true zeros

The Google Health API implements true zeros to resolve sedentary intervals. If a user is wearing a tracker but not walking during a given period, the API returns a record for that interval that contains the normal data source and timestamp metadata but omits the count property.

This allows you distinguish between:

  • Stationary on-wrist periods: The user is wearing the device but not walking. This returns records without the count property (interpreted as zero steps).
  • Off-wrist periods: The user is not wearing the device. This returns no record, resulting in large data gaps.

Refer to the Data presence and true zeros guide for more details.

Previous
Nutrition
Next
Sleep and recovery