WearAPI.com

DOCS / PATTERNS & EXAMPLES

Build a clear contract
for wearable data.

A practical starting point for developers: choose an access route, understand a record, and plan what happens when the happy path ends.

These docs explain integration patterns and include a local, illustrative JSON record. To connect a real device, use the relevant platform or manufacturer’s documented interface.

1. Choose an access path

Begin with the user experience and how fresh its information needs to be. A live workout, a retrospective sleep view, and a connected garment prototype have different requirements. A device API, a phone health store, and a vendor cloud account can all be useful, but they do not promise the same records or delivery timing.

Access pathUseful questionVerify before building
Device or nearby sensorDoes the app need readings while an activity happens?Capabilities, protocol, permissions, connection lifecycle.
Phone health storeCan the feature use records already available on the phone?Record types, authorization semantics, history access.
Vendor cloudDoes an account-based integration fit the product?Developer access, consent flow, sync delay, quotas.

Choose the smallest path that can answer the product’s question. Keep the source adapter separate from the screen that presents its data. That makes it easier to test one route now and add a second without erasing the differences between them.

2. Define a record contract

A shared record should preserve the meaning of the measurement. The following example deliberately keeps observation time separate from receipt time. The sample value is fictional and exists only to demonstrate the format.

{
  "id": "sample-001",
  "type": "heart_rate",
  "value": 72,
  "unit": "bpm",
  "observed_at": "2026-09-30T08:00:00Z",
  "received_at": "2026-09-30T08:04:00Z",
  "source": {
    "device": "example_watch",
    "record_id": "demo-record-001"
  },
  "status": "illustrative"
}

Use a stable source record identifier when one is provided, and keep it within a source-specific namespace. Define units explicitly. Treat an absent value as missing rather than converting it into zero. If you derive a value, keep enough provenance to explain the transformation. Your production contract may also need intervals, time-zone context, record revisions, or a source quality indicator; include only fields the source or your own processing can meaningfully support.

3. Read the bundled example

The file example-heart-rate.json is included with this site. The following JavaScript reads that static file and validates the few fields used by the demonstration. It does not call a WearAPI service or request health data from a user.

// Run on a page hosted from this website’s root.
// Reads the bundled illustrative record; no device is connected.
const response = await fetch('/assets/data/example-heart-rate.json');
if (!response.ok) throw new Error(`Example unavailable: ${response.status}`);
const record = await response.json();

if (record.type !== 'heart_rate' || record.unit !== 'bpm' ||
    !Number.isFinite(record.value)) {
  throw new Error('Unexpected example record');
}
console.log(`${record.value} ${record.unit}`); // 72 bpm

For a real integration, add an adapter that maps the provider’s documented schema into your contract. Validate timestamp formats, optional fields, error responses, and revisions at that boundary. Keep any client secret and other server-only credentials out of publicly delivered JavaScript. The consent and security guide explains how a connected application differs from an educational example.

4. Plan the sync lifecycle

Represent connection state separately from data presence. A connected source may have no records for the selected interval. A disconnected source may still have previously imported data. Some platforms deliberately limit what an app can infer about permission denial, so your interface should explain what it knows without claiming to distinguish every cause of missing data.

  • Connect: explain the feature, request the necessary scopes, and confirm the observable result.
  • Import: keep a checkpoint and handle pagination or bounded time windows.
  • Update: reconcile new, repeated, corrected, and deleted records using the source’s semantics.
  • Recover: apply documented retry guidance and make reconnection understandable.
  • Disconnect: stop future access and follow the product’s clearly defined retention and deletion behavior.

Do not use a dashboard’s most recent date as proof that an import is complete. Record import progress explicitly and consider whether old records can arrive or change after a later interval is already visible.

5. Test the difficult cases

Build a small fixture set before broadening device support. The point is to verify behavior a user can understand, not merely whether a request returns a success status.

ScenarioExpected design behavior
Missing measurementShow no available reading; never insert a zero.
Duplicate deliveryResolve the record according to your identity and revision rules.
Late synchronizationPlace the record by observation time and retain its arrival time.
Time-zone changePreserve the original interval and apply the product’s reporting-day rule.
Partial or withdrawn accessDescribe the available state and offer the supported recovery route.
Unsupported capabilityExplain that the feature is unavailable for this source.

Then test on the devices and platform versions the product intends to support. Measure the real synchronization workload, record coverage, and failure behavior before promising wider compatibility. A unit-level fixture is valuable, but it cannot establish what a physical device actually delivers in ordinary use.

6. Continue with real platforms

Use the smart watch guide, smart ring guide, or heart rate monitor guide to narrow the next implementation step. For platform details, consult the official documentation linked below; access requirements and supported fields may evolve.