Health Data

Choose the API resource that matches the shape of data your product needs.

Sonar normalizes provider records into five public resources. Daily data and scores are aligned arrays for charts and summaries. Workouts and sleep are session feeds. Time series contains sampled vitals grouped into fixed-width buckets.

How Data Becomes Queryable

Providers and mobile health platforms describe similar observations with different payloads, names, units, and timestamp conventions. Sonar first maps those records into a unified metric vocabulary, converts values to canonical units, and normalizes real instants before applying the user’s health-data clock.

Repeated deliveries of the same provider record are deduplicated. Sonar then consolidates overlapping device contributions according to the metric and resource being produced. The result is shaped into the stable public resources below rather than exposing each provider’s native representation.

Multiple devices

Consolidation happens at the metric level, not by choosing one device for the entire user. A person can therefore contribute activity, sleep, and vitals from different connected sources.

For daily data, Sonar first resolves overlapping representations reported by the same device and then combines devices according to the metric’s consolidation rule. Totals such as steps and sleep duration generally use the highest reported daily value so overlapping device totals are not added together. Vitals and body measurements generally use the average of the available device values. Sleep receives additional handling to prefer records with stage detail when several sources describe the same night.

Workouts and sleep remain session feeds and are deduplicated with session-specific rules. Time-series samples retain their temporal shape and are averaged into the fixed-resolution buckets requested by the reader. Scores are calculated after the underlying daily, sleep, and vitals data has been consolidated.

Choose a Resource

Shared Contract

Every endpoint requires a Sonar user UUID and reads only the environment selected by the API key. Numbers have at most one decimal. Missing daily values and empty time-series buckets are null; Sonar keeps the requested axis intact instead of dropping gaps. Session fields unsupported by a provider are also null.

The Health-Data Clock

Provider samples that identify real instants are normalized and stored in UTC. The read API projects them onto the calendar and clock the person experienced, using the IANA timezone saved in the user’s profile. If no timezone was supplied, the API uses UTC.

Dates in health-data queries are inclusive. When to_date is omitted, “today” means the current date in the user’s timezone. The default from_date is then calculated from that local date. A request made at 2026-09-16T23:30:00Z, for example, ends on September 17 for Pacific/Auckland but September 16 for America/Los_Angeles.

Daily data

Daily metrics and scores are assigned to the calendar day in the user’s timezone. The returned date is an axis label, not a midnight UTC timestamp. Do not parse it as UTC and convert it again.

Sessions

Workout and sleep clock fields use local wall time without a suffix. Sleep also has an assigned date: the night ending on the morning of September 16 normally counts toward 2026-09-16, even if start_time is late on September 15.

Time series

Sonar keeps sampled readings as UTC instants internally. For a timeseries request it converts the requested local-midnight boundaries to UTC, reads the matching samples, projects them back into the user’s wall clock, and buckets them from local midnight. The response carries this dense axis as start, step_seconds, and values; bucket i begins at start + i * step_seconds in wall-clock time.

The axis has a fixed number of wall-clock buckets per calendar day. Across daylight-saving changes, the nonexistent spring hour is returned as empty buckets, while readings from both occurrences of the repeated autumn hour are averaged into the same local-time buckets.

See the Metric Catalog for accepted metric IDs and units, and API Conventions for validation, errors, and pagination rules.