Google Health API: A Practical Guide to Getting Started

Open Wearables Team · August 12, 2026 · 6 min read

Key Takeaways

The Google Health API is a server-side OAuth 2.0 flow that aggregates 24/7 metrics, workouts, and sleep from every source connected to a user's Google Health account, not just one device.
You need three things before you start: a Google Cloud project with the Health API enabled, OAuth client credentials, and a registered redirect URI. Webhooks additionally require a service account.
Setup is five steps: enable the API and create an OAuth client, configure environment variables, connect a user through OAuth, trigger a sync, and verify data comes back.
Most Google Health API scopes are restricted rather than merely sensitive, which means OAuth app verification and, past 100 users, an annual CASA security assessment before going to production.
The default configuration (reconcile mode, raw granularity) returns app-accurate, deduplicated totals out of the box, so most integrations don't need to touch the fetch mode settings at all.

The Google Health API is Google's cloud OAuth layer for health data, the successor Google points developers toward as it retires the legacy Fitbit Web API in September 2026. It aggregates data from every source connected to a user's Google Health account: Fitbit, Google Fit, Health Connect on their phone, and other connected apps, all through one OAuth connection and no mobile SDK.

This is a practical, step-by-step walkthrough of getting from zero to a working integration, using Open Wearables as the reference implementation. The mechanics (Google Cloud setup, OAuth client, scopes) apply whether or not you use Open Wearables specifically.

What You Need Before You Start

Four things, and you can gather all of them before writing any code:

A Google Cloud project with the Health API enabled
OAuth client credentials (Client ID and Secret) with the Google Health scopes
A redirect URI registered in your OAuth client
If you plan to use webhooks, a service account for project-level subscriber registration

You also need a Google Cloud project to work from, and access to the Health API enabled on it.

Step 1: Enable the Health API and Create an OAuth Client

In the Google Cloud Console, select your project and enable the Health API:

            gcloud config set project YOUR_PROJECT_ID
gcloud services enable health.googleapis.com

Then create an OAuth 2.0 Client ID (Web application) under APIs & Services, Credentials, and add your server-side callback as an Authorized redirect URI. For local development, that's:

            http://localhost:8000/api/v1/oauth/google/callback

One thing to get right immediately: store the Client Secret securely the moment you create it. Google shows it to you once, and there is no way to retrieve it again afterward.

Step 2: Configure Credentials

Add the following to your .env file:

            #--- Google ---#
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_DEFAULT_SCOPE=openid email https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly https://www.googleapis.com/auth/googlehealth.nutrition.readonly https://www.googleapis.com/auth/googlehealth.sleep.readonly https://www.googleapis.com/auth/googlehealth.settings.readonly
GOOGLE_USE_RECONCILE=true

Four variables matter here:

GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are your OAuth credentials from step 1.
GOOGLE_DEFAULT_SCOPE is the space-separated list of Health API scopes to request. The value above is the full read-only set covering activity and fitness, health metrics, nutrition, sleep, and settings.
GOOGLE_USE_RECONCILE controls whether overlapping data from multiple sources gets merged into one app-accurate total (true, the default) or kept as raw per-device data (false). This only affects raw-granularity data; leave it at the default unless you specifically need per-device attribution.
DEFAULT_DATA_GRANULARITY (not shown above, defaults to raw) chooses between raw, hourly, or daily data resolution.

One detail worth double-checking before you move on: the redirect URI is derived from your API_BASE_URL setting, and it has to match the Authorized redirect URI you registered on the OAuth client in step 1 exactly. A mismatch here is one of the most common reasons the OAuth flow fails silently.

Step 3: Connect a User via OAuth

With credentials configured, initiate the OAuth flow for a specific user.

First, get the authorization URL:

            curl -X GET "http://localhost:8000/api/v1/oauth/google/authorize?user_id={user_id}&redirect_uri=http://localhost:3000/users/{user_id}" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

Redirect the user to the returned authorization_url. They log in to Google and grant consent on Google's standard OAuth screen.

Google then redirects back to your registered callback, where the backend exchanges the authorization code for tokens and stores the connection automatically. You don't need to handle the code exchange yourself.

Verify the connection landed correctly:

            curl -X GET "http://localhost:8000/api/v1/users/{user_id}/connections" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

You should see a connection with "provider": "google" and "status": "active". If the status is anything else, the OAuth exchange did not complete, and the redirect URI mismatch from step 2 is the first thing worth checking.

Step 4: Sync Data

An initial sync typically runs automatically right after a successful OAuth connection. To trigger one manually:

            curl -X POST "http://localhost:8000/api/v1/providers/google/users/{user_id}/sync" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

Step 5: Verify the Integration End to End

Fetch a synced 24/7 series, for example steps:

            curl -X GET "http://localhost:8000/api/v1/users/{user_id}/timeseries/steps?start_date=2026-01-01T00:00:00Z&end_date=2026-02-01T00:00:00Z" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

If data comes back, the integration is working end to end: OAuth, sync, and data retrieval all confirmed.

Before You Go to Production: Verification and CASA

Getting the integration working technically is not the same as being ready for production traffic. Most Google Health API scopes are restricted rather than merely sensitive, and Google requires OAuth app verification plus, past 100 users, an annual CASA security assessment. Below that user threshold you can operate unverified, but every user sees an "unverified app" warning at sign-in, which is not something you want in a live product.

This is worth planning for before launch, not discovering after. The full breakdown of what CASA actually costs and who is responsible for it covers the timeline, cost, and what you can and cannot delegate to a platform like Open Wearables.

If You Need Webhooks

Everything above covers pull-based sync, which is enough for most integrations. If you want to be notified when a user's data changes instead of polling on a schedule, the Google Health API supports notify-only webhooks: a notification names the changed data type and time interval, and your backend fetches the actual data over REST in response. Setting this up requires a service account for project-level subscriber registration, which is a separate setup step from the OAuth flow above.

See related articles

Google Health API and Google Health Connect: What's the Difference

Google CASA and OAuth Verification for Health Apps

Fitbit Web API Shutdown 2026: Migration Guide

Fitbit Alternatives for Developers

FAQ

What do I need before setting up the Google Health API?

A Google Cloud project with the Health API enabled, OAuth client credentials (Client ID and Secret), and a registered redirect URI. If you plan to use webhooks, you also need a service account for project-level subscriber registration.

What scopes does the Google Health API use?

The full read-only scope set covers activity and fitness, health metrics and measurements, nutrition, sleep, and settings, each as a separate googlehealth.*.readonly scope requested via a space-separated GOOGLE_DEFAULT_SCOPE value.

What does GOOGLE_USE_RECONCILE do?

It controls whether overlapping data from multiple connected sources gets merged into one deduplicated, app-accurate total (true, the default) or returned as raw per-device data (false). It only affects raw-granularity data; most integrations should leave it at the default.

Why does my OAuth flow fail after the user grants consent?

The most common cause is a mismatch between your configured API_BASE_URL (which derives your redirect URI) and the Authorized redirect URI registered on your OAuth client in Google Cloud Console. These have to match exactly.

Do I need to handle Google's OAuth token exchange myself?

No, if you're using Open Wearables. When Google redirects back to the registered callback, the backend exchanges the authorization code for tokens and stores the connection automatically.

Do I need OAuth verification and CASA just to test the integration?

No. Apps under 100 users can operate without Google's OAuth app verification, which is enough for development and testing. Verification and the annual CASA security assessment become necessary once you're serving real production users past that threshold.

Back to all posts