DOCSEARCHbyAlgolia
Submit Docs

Open Wearables Documentation

repository·main·Indexed 24 days ago

https://github.com/the-momentum/open-wearables

An open-source platform that unifies wearable device data from multiple providers into a single, normalized API. The project includes a FastAPI backend, a frontend built with TanStack Start and shadcn/ui, and an MCP server for integrating health data with AI assistants like Claude Desktop and Cursor.

Tokens
123.7K
Snippets
270
Records
462
Agent score
79%

What's inside Open Wearables

  1. Overview of Open Wearables

    main

    Open Wearables is an open-source health intelligence platform designed to unify wearable device data from multiple providers into a single, normalized API. It allows developers to build health applications without managing individual integrations for every device (like Garmin, Whoop, or Apple Health).

    Key capabilities include:

    • Unified API: Access consistent REST API endpoints for health data regardless of the source.
    • AI-Powered Insights: Define health automations and notifications using natural language.
    • Embeddable Widgets: Quickly integrate connection flows and AI assistants into existing applications.
    • Self-Hosting: Deploy the entire platform on your own infrastructure for full data control and privacy.
    • Provider Support: Integrates with Garmin, Polar, Suunto, Whoop, Strava, Fitbit, Oura, Ultrahuman, Apple Health, and Google Health Connect.

  2. Overview of the Wearable Sync SDK

    main

    The Open Wearables Sync SDKs enable background synchronization of health data from on-device stores—specifically Apple HealthKit (iOS), Samsung Health, and Health Connect (Android)—to the Open Wearables platform.

    Because these health stores do not expose cloud APIs, the SDK uses a push-based model: your mobile application must actively read data from the device's local health store and push it to the Open Wearables backend. This differs from cloud-to-cloud providers (like Garmin or Polar) that use webhooks.

  4. Understand Wearable API Coverage and Capabilities

    main

    Use the coverage matrix to determine which health data types and features are available for specific wearable providers (Apple, Garmin, Polar, Suunto, Oura, Whoop, Ultrahuman, Strava, Fitbit, and Google Health Connect).

    Capability Legend

    • ✅ Full support: Fully implemented and collecting data.
    • ◐ Partial: Limited data or only during certain contexts (e.g., workouts only).
    • 🔜 Coming soon: Provider API supports this, but processing is not yet implemented.
    • ❌ Not available: Provider doesn't support this or it is not applicable.

    Key Concepts

    • Timeseries: Refers to granular, timestamped data points (such as heart rate samples, step counts, or HRV readings) accessible via the /timeseries API endpoint.
    • 24/7 Data: Refers to continuous health monitoring throughout the day (not just during workouts), including resting heart rate, HRV during sleep, SpO2 spot checks, and daily activity samples.

  5. Available Wearable Device Providers

    main

    Open Wearables supports 10 primary providers categorized by their integration method: Cloud-based (OAuth) and SDK-based (Mobile).

    ### Cloud-based providers

| Provider | Setup Guide | Notes |
|----------|-------------|--------|
| **Suunto** | [Setup Guide →](/providers/suunto-api-integration) | You must apply for [Suunto Developer Program](https://www.suunto.com/en-gb/partners/partners/) |
| **Garmin** | [Setup Guide →](/providers/garmin-api-integration) | You must apply for [Garmin Developer Program](https://developer.garmin.com/) |
| **Polar** | [Setup Guide →](/providers/polar-api-integration) | You must register for the [Polar API program](https://www.polar.com/en/business/api) |
| **Whoop** | [Setup Guide →](/providers/whoop-api-integration) | Whoop membership required |
| **Strava** | [Setup Guide →](/providers/strava-api-integration) | Free Strava account required |
| **Fitbit** | [Setup Guide →](/providers/fitbit-api-integration) | Free Fitbit account required. The Fitbit Web API is [turned down in September 2026](https://developers.google.com/health/about) |
| **Ultrahuman** | [Setup Guide →](/providers/ultrahuman-api-integration) | Ultrahuman Ring Air account required |
| **Oura Ring** | — | Oura account required |
| **Google Health** | [Setup Guide →](/providers/google-api-integration) | Google Cloud project with the Health API enabled |

### SDK-based providers

| Provider | Setup Guide | Notes |
|----------|-------------|--------|
| **Apple Health** | [Setup Guide →](/providers/apple-health) | Mobile SDK coming soon! |
| **Google Health Connect** | [Setup Guide →](/sdk/android/integration) | Via Android SDK |
| **Samsung Health** | [Setup Guide →](/sdk/android/integration) | Via Android SDK |

  6. Fitbit API Integration Overview

    main

    The Fitbit integration uses OAuth 2.0 to fetch workout and activity data via the Fitbit Web API.

    Key Characteristics:

    • Sync Method: Pull-based (polling) via Celery Beat. Webhook/Subscription support is not implemented.
    • Supported Data Types: Only Workouts / Activities are actively synced.
    • Unsupported Data Types: Sleep, Heart rate (intraday), and Daily activity summary are available via the Fitbit API but are not implemented in this integration. Use the Google Health API integration for these data types.

    Rate Limits:

    • Limit: 150 requests per hour, per user, per application.
    • Error: Returns HTTP 429 Too Many Requests when exceeded. Check the Fitbit-Rate-Limit-Reset header for the reset Unix timestamp.

  7. Understand the Open Wearables Repository Structure

    main

    The project is organized as a monorepo with three primary components:

    • backend/: The FastAPI Python backend containing API routes, SQLAlchemy models, Pydantic schemas, business logic (services), and data access layers (repositories).
    • frontend/: A React application using TanStack Router, TanStack Query, and Vite.
    • mcp/: A Model Context Protocol (MCP) server (currently in Beta) that allows AI assistants like Claude Desktop or Cursor to interact with health data via the backend REST API.
    • docs/: Project documentation.
    open-wearables/
├── backend/          # FastAPI Python backend
│   ├── app/
│   │   ├── api/     # API routes and endpoints
│   │   ├── models/  # SQLAlchemy database models
│   │   ├── schemas/ # Pydantic request/response schemas
│   │   ├── services/# Business logic layer
│   │   ├── repositories/ # Data access layer
│   │   └── integrations/ # Third-party integrations (Celery, Sentry)
│   ├── migrations/  # Alembic database migrations
│   └── scripts/     # Utility and initialization scripts
├── frontend/        # React + TanStack Router frontend
│   └── src/
│       ├── components/ # React components
│       ├── routes/     # Route definitions
│       ├── hooks/      # Custom React hooks
│       └── lib/        # Utilities and API clients
├── mcp/            # MCP server (Beta) - AI assistant integration
│   └── app/
│       ├── tools/     # MCP tool definitions
│       └── services/  # API client for backend communication
└── docs/            # Mintlify documentation

  8. Understand Open Wearables Health Scores

    main

    The Open Wearables (OW) platform provides two science-backed, custom health scores on a 0-100 scale. These scores are designed to help users understand physiological trends and habits rather than serving as clinical diagnostic tools.

    Available Scores

    1. Sleep Score: A nightly metric (0-100) that measures sleep quality based on four pillars: duration, stages, consistency, and interruptions.
    2. Resilience Score: A weekly metric (0-100) that measures autonomic nervous system stability using the Heart Rate Variability (HRV) Coefficient of Variation.

    In both cases, a higher score indicates a better outcome (better sleep quality or better HRV consistency).

  9. Understand the React Native Authentication Architecture

    main

    The Open Wearables React Native SDK supports two authentication modes: token-based (recommended for production) and API key (for internal/trusted tools).

    In the recommended token-based flow, your backend acts as a secure intermediary to prevent exposing sensitive credentials to the mobile client:

    1. Backend Generation: Your backend calls the Open Wearables API using your app_id and app_secret to request a user-scoped token via the POST /api/v1/users/{user_id}/token endpoint.
    2. Token Forwarding: Your backend returns the resulting access_token and refresh_token to the mobile app.
    3. SDK Sign-In: The mobile app passes these tokens to OpenWearablesHealthSdk.signIn().
    4. Secure Storage: The SDK stores these credentials in the iOS Keychain or Android EncryptedSharedPreferences and uses them to sync health data directly to Open Wearables.

    CRITICAL SECURITY RULE: Never embed app_id or app_secret in your mobile application code. These must only reside on your backend server.

  10. How Google Health webhooks work in Open Wearables

    main

    Google Health webhooks are notify-only. When data changes, Google sends a notification containing the dataType, the operation (UPSERT or DELETE), and the physical-time intervals that changed. The notification itself does not contain the actual health data.

    Upon receiving a notification, Open Wearables verifies the request using a secret and then performs a REST API call to Google to fetch the actual data for the specified intervals.

    To ensure security, two types of credentials are used:

    1. GOOGLE_WEBHOOK_SECRET: A bearer token used to verify that incoming notifications are genuine. This is echoed back by Google in the Authorization header.
    2. Service-account credentials: Used exclusively for the administrative task of registering the webhook subscriber at the Google project level. These are not used for processing the notifications themselves.

  11. Understand the backend project structure

    main

    The backend/ directory is organized as follows:

    • app/: Main application code
      • api/routes/: Versioned route handlers
      • config.py: Configuration settings
      • database.py: DB connection and session management
      • main.py: FastAPI entry point
      • models/: SQLAlchemy database models
      • repositories/: Data access layer
      • schemas/: Pydantic schemas (request/response validation)
      • services/: Business logic layer
      • utils/: Utility functions
    • migrations/: Alembic migration files
    • scripts/: Utility scripts
    • alembic.ini: Alembic configuration
    • pyproject.toml: Dependencies and tool config
    • uv.lock: Locked dependency versions

  12. Compare Google Health fetch modes: Reconcile vs List

    main

    Open Wearables uses different fetch modes based on the DEFAULT_DATA_GRANULARITY and the GOOGLE_USE_RECONCILE flag. This determines how overlapping data from multiple sources (e.g., a phone and a Fitbit) is handled.

    Reconcile Mode (Default)

    • Setting: GOOGLE_USE_RECONCILE=true (only applies at raw granularity).
    • Operation: dataPoints:reconcile.
    • Behavior: Returns a single merged, deduplicated stream that matches what the user sees in native Google Health/Fitbit apps.
    • Trade-off: Provides app-accurate totals but carries no device attribution (device_model will be empty).

    List Mode

    • Setting: GOOGLE_USE_RECONCILE=false (only applies at raw granularity).
    • Operation: dataPoints (list).
    • Behavior: Returns raw per-source points, each tagged with its originating device. Open Wearables deduplicates on read by source priority (it does not sum them).
    • Trade-off: Preserves per-device attribution but does not match the merged totals shown in native health apps.

    Summary Table

    GranularityOperationResolutionCross-sourceDevice attribution
    raw + RECONCILE=truedataPoints:reconcilenativemerged & deduplicatednone
    raw + RECONCILE=falsedataPoints (list)nativeraw, per-sourceper-device
    hourly / dailydataPoints:rollUpwindowedreconcilednone