Every question the Concepts pages answer
The 13 concepts pages answer 65 named questions between them. Every one is listed below, and every link lands on the paragraph that answers it rather than the top of the page.
What Is a Fitness API?
- What is a fitness API in simple terms?It is a documented way for your app to get fitness or health data, or trigger a fitness feature, from another service. Your app sends a…
- What are the main types of fitness API?There are roughly five categories: exercise and workout content APIs (libraries of exercises, demos, and plans), wearable and…
- Is a fitness API the same as Fitbit's API or HealthKit?No. 'Fitness API' is the general category; Fitbit's API, Terra, and Apple HealthKit are specific implementations of it. Answering 'which…
- How do I connect my app to a fitness API?For cloud APIs, you register a developer app for credentials, have the user authorize your app via OAuth 2.0 to get scoped tokens, call the…
- Why use a fitness API instead of building it yourself?A fitness API gives you leverage: you ship features like device sync, an exercise library, calorie logging, or camera coaching without…
What Is a Health-Data Aggregator?
- What is a health-data aggregator?It is a single third-party integration that connects to many wearables and health providers, normalizes their data into one consistent…
- Why use a health-data aggregator instead of integrating each provider directly?To avoid the 'N integrations' problem. Supporting five wearables directly means five OAuth setups, five data formats, five sets of rate…
- How does a health-data aggregator work?You integrate once and register a webhook endpoint. The user connects their device through the aggregator's widget or connect flow, which…
- What are the trade-offs of using an aggregator?You pay a recurring vendor fee (often per connected user) on top of the providers themselves. For several sources such as Garmin you may…
- Does an aggregator cover both cloud APIs and on-device data like Apple HealthKit?Yes. An aggregator's servers pull from cloud/OAuth providers (Fitbit, Garmin, Oura, Whoop, Strava), and its mobile SDKs read from on-device…
On-Device vs Cloud Health Data: What's the Difference?
- What is the difference between on-device and cloud health data?On-device health data lives in an encrypted store on the user's phone (Apple HealthKit on iOS, Google Health Connect on Android), and your…
- Do Apple HealthKit and Google Health Connect use OAuth?No. Both use OS-level permissions rather than OAuth. The user grants access per data type in a system dialog, there is no access or refresh…
- When should I use a cloud API instead of an on-device store?Use a cloud/OAuth API when you need server-side, always-on access that does not depend on a specific phone being present, or when the data…
- Can I get both on-device and cloud data through one integration?Yes, that is what an aggregator like Terra, Junction, Rook, or Spike does. It orchestrates OAuth for cloud providers and, via mobile SDKs,…
- Is on-device health data more private than cloud data?Generally yes, in the sense that on-device data stays on the phone and never touches a vendor's cloud unless your own app uploads it.…
What Is OAuth 2.0 (and How Health APIs Use It)?
- What is OAuth 2.0 in simple terms?OAuth 2.0 is an authorization framework that lets a user grant one app limited access to their data on another service without sharing…
- How does the OAuth authorization-code flow work?Your app redirects the user to the provider's consent screen listing the scopes you request. The user logs in at the provider and approves,…
- What is the difference between an access token and a refresh token?An access token is short-lived (often about an hour) and is sent on every API call to authenticate the request. A refresh token is…
- Why do health APIs use OAuth instead of API keys?Health data is user-owned and sensitive, so authorization must be tied to the individual user's explicit consent. OAuth gives the user…
- Do HealthKit and Health Connect use OAuth?No. Apple HealthKit and Google Health Connect are on-device stores that use OS-level permissions instead of OAuth. The user grants access…
What Are Webhooks (and Why Fitness APIs Use Them)?
- What is a webhook in simple terms?It is a way for one server to notify another automatically. Instead of your app asking a provider 'any new data?' on a timer (polling), the…
- What is the difference between webhooks and polling?Polling is your server pulling data on a schedule; a webhook is the provider's server pushing data to you when an event occurs. Polling is…
- How do you verify a webhook is legitimate?Two mechanisms. First, a validation handshake at setup, where the provider sends a challenge value your endpoint must echo back before…
- Does a webhook payload contain all the data?Often no. Many webhooks are 'thin' notifications that tell you something changed and give you an ID (for example, a new activity ID), not…
- Why do fitness and wearable APIs use webhooks?Wearable data arrives sporadically, whenever a device syncs, so there is no good polling interval. Poll too often and you burn through rate…
What Is Pose Estimation (for Fitness Apps)?
- What is pose estimation in simple terms?It is computer vision that finds where a person's joints are in a camera frame. A model looks at each frame and returns coordinates for a…
- How does pose estimation work?A trained model takes a camera frame and predicts the pixel position (and sometimes a depth value) of each landmark, plus a confidence…
- How many keypoints does pose estimation track?It depends on the model. MediaPipe BlazePose tracks 33 keypoints (the 17 standard COCO body points plus extra face, hand, and foot…
- Do I have to train my own pose model?No, and for a fitness app you almost certainly should not. Pose estimation ships as an embedded SDK or library you drop in — MediaPipe,…
- What are the limits of pose estimation?Accuracy depends on physical conditions. Poor framing (body out of frame, too close or too far), bad lighting, and occlusion (one body part…
What Is HRV (Heart Rate Variability)?
- What does HRV measure?It measures how much the time between consecutive heartbeats varies. The raw input is the inter-beat interval (the RR or NN interval, in…
- How do wearables measure HRV?They time the gaps between heartbeats. Most wrist and ring devices use optical PPG sensors (green LEDs reading blood-volume pulses), while…
- What is a good HRV number?There is no universal 'good' number, and comparing your HRV to someone else's or to a chart is misleading. Population ranges are very wide…
- Can I compare HRV across different devices or brands?Not reliably. Different sensors (PPG vs. ECG), different aggregation windows, and proprietary algorithms mean the same person's HRV will…
- How does HRV appear in a wearable API?Usually as a single daily (typically nightly) value on a sleep or daily-summary object, with field names like hrv_rmssd, rmssd,…
What Is VO2 Max (and How Do Wearables Estimate It)?
- Is wearable VO2 max measured or estimated?Estimated. A true VO2 max comes from a lab graded-exercise test where you breathe through a gas-analysis mask (indirect calorimetry).…
- How accurate is VO2 max from a smartwatch?It varies. Accuracy depends more on method than brand: estimates from an actual workout tend to have low average bias, while resting…
- What is a good VO2 max?VO2 max is expressed in mL/kg/min, often in the 30s to 50s for many recreational adults and higher for trained endurance athletes,…
- How does VO2 max appear in a fitness API?Usually as a single scalar field such as vo2_max or vo2Max in mL/kg/min on a user-summary or activity-summary object, sometimes with a…
- Why do Apple and Garmin show different VO2 max numbers?Each vendor uses its own model and inputs. Garmin relies on Firstbeat Analytics from heart-rate-versus-pace data, while Apple combines…
What Are Sleep Stages (Awake, Light, Deep, REM)?
- What are the four sleep stages?Awake (periods of wakefulness and brief arousals), light sleep (clinically N1 and N2, the largest share of a typical night), deep sleep (N3…
- How do wearables measure sleep stages?They do not read brainwaves. Consumer wearables estimate stages by inferring them from movement (an accelerometer) combined with heart rate…
- How accurate is sleep-stage tracking on a wearable?Directionally useful but limited for exact stages. Validation studies find wearables are fairly good at telling sleep from wake (often…
- How do sleep stages appear in a wearable API?Usually as a nightly sleep object with per-stage durations (for example light, deep, REM, and awake in seconds or minutes) plus totals like…
- Can I use wearable sleep stages for medical decisions?No. Consumer sleep-stage estimates are a general wellness signal, not a clinical measurement or a diagnosis of any sleep disorder. They are…
How Do Fitness Apps Estimate Calories Burned?
- How do fitness apps calculate calories burned?They estimate it with a model rather than measuring it. A calorie figure is assembled from some combination of METs (an activity's…
- Are fitness app calorie counts accurate?Not very, in absolute terms. A 2017 Stanford study of seven wrist devices found the most accurate was still off by about 27% on average for…
- Why is calorie burn an estimate and not a measurement?Because a device has no way to directly measure energy expenditure. A true measurement needs lab methods like indirect calorimetry (a…
- Why do two devices show different calories for the same workout?Each device uses its own proprietary model, its own mix of METs, heart-rate, and movement inputs, and the profile data you gave it. Because…
- How does calorie data appear in a fitness API?Usually as kilocalorie (kcal) fields on daily summaries and per workout — commonly an active_energy value (energy above resting from…
Webhooks vs. Polling for Fitness Data: How to Decide
- When is polling actually the right choice for a fitness integration?When you have no public HTTPS endpoint yet, when your freshness requirement is measured in hours rather than minutes, or when your user…
- How often should I poll a wearable API when there is no push option?Work it out from the quota rather than from taste: divide the provider's documented limit by your user count and by the number of calls…
- Which wearable providers push data and which make you pull it?It varies more than people expect. Our Garmin guide documents push only, with callback URLs registered per summary type and no polling.…
- Do webhooks make wearable data arrive faster than the device syncs?No. Data travels from the device to the vendor's phone app to the provider's cloud before anything reaches you, and each hop runs on its…
- Is running a scheduled poll alongside push delivery wasteful?No, and it is usually the correct architecture. Because most fitness notifications are pointers rather than data, the effect of an event is…
What Are OAuth Scopes (and How Health APIs Grant Them)?
- Can a user grant only some of the scopes my app requested?Yes, and on health APIs you should assume they will. Fitbit documents that you cannot force a user to grant every scope because consent is…
- How do I find out which scopes were actually granted?Read them back from the provider rather than assuming. Fitbit returns a scope field in the token-exchange response alongside the access…
- Is an Android or iOS health permission the same thing as an OAuth scope?No. An OAuth scope is granted by the user at a cloud provider's consent screen and enforced by that provider's API. An OS permission is a…
- Which error code means a scope is missing?A 403 Forbidden, mapping to the Bearer error insufficient_scope, means the token is authentic but not permitted to do that. A 401…
- Why did I get no refresh token even though the login worked?Usually because you omitted the scope that unlocks offline access. WHOOP documents offline as a required scope to receive a refresh token…
What Is RPE (Rating of Perceived Exertion)?
- What does RPE stand for in training?Rating of perceived exertion. It is a number someone gives to describe how hard an effort felt to them, and the operative word is felt: it…
- What is the difference between the 6-20 and 0-10 RPE scales?They are two different conventions for labelling the same feeling, and they are not interchangeable. The 6-to-20 range is the older one,…
- Does any wearable API return RPE as a measured value?No, and it cannot. Wearables report sensor readings such as heart rate, heart-rate variability, GPS traces, steps, and sleep, plus vendor…
- How should a fitness app collect RPE from users?Ask close to the effort, keep it to one tap, and label the anchors. A rating given right after a set describes that set, while one given…
- Is RPE reliable enough to drive automatic plan adjustments?Treat it as one soft input among several, not a control signal on its own. It is genuinely informative because it captures cost that logged…
Back to the Concepts hub, or see every question this site answers.