An unofficial TypeScript SDK for the Withings API. Weight, sleep, activity, heart and blood pressure data, fully typed.
Not affiliated with, endorsed by, or supported by Withings. Use of the Withings API is subject to their terms of service.
pnpm add withings-sdkNode.js 18 or newer. Zero runtime dependencies. Ships ESM and CommonJS with bundled types.
You need a client ID, client secret and redirect URI from the Withings developer dashboard.
import { MeasurementType, WithingsClient } from "withings-sdk";
const client = new WithingsClient({
clientId: process.env.WITHINGS_CLIENT_ID!,
clientSecret: process.env.WITHINGS_CLIENT_SECRET!,
redirectUri: "https://example.com/auth/withings/callback",
accessToken: storedAccessToken,
refreshToken: storedRefreshToken,
});
const measurements = await client.measures.getMeasurement({
meastype: MeasurementType.Weight,
startdate: new Date("2024-01-01"),
enddate: new Date("2024-02-01"),
});Getting those tokens the first time is the authentication flow.
- Renews expired tokens and retries the request, once.
- Backs off and retries when the API rate limits you.
- Types every failure, so a refused request, a network level failure and a
proxy error page are told apart rather than all arriving as
Error. - Walks paginated endpoints lazily, so breaking out early stops the requests.
- Explains missing metrics, which usually means your API plan rather than a bug.
client.measures |
Weight, body composition, activity, workouts |
client.sleep |
Sleep states and nightly summaries |
client.heart |
ECG, atrial fibrillation, blood pressure |
client.user |
Devices, goals, account management |
client.notify |
Webhooks |
client.auth |
OAuth2, token refresh, signed requests |
Full documentation, including measurements, sleep, heart, notifications, errors and rate limits and API plans.
Stable, and following semantic versioning. A breaking change to anything documented means a major version.
Every Withings service carrying general health data is covered: measure,
sleep, heart, user, notify, signature and oauth2. The partner and
RPM services are not implemented.
Response shapes are checked against the live API by a contract test suite, so a change on Withings' side is caught here rather than discovered by you.
See CONTRIBUTING.md.