Building a Python SDK for Polar Watches

I've been wearing a Polar Ignite 3 for a while now. Sleep tracking, HRV, nightly recharge - the data is genuinely useful. Problem is, Polar locks it all behind their Flow app. You can see your stats, but you can't do anything with them.

Polar has an API. It's called AccessLink, and it's actually pretty comprehensive. Sleep metrics, exercise data, daily activity, heart rate - all there. But the documentation assumes you're going to write a bunch of boilerplate to talk to it.

So I built a Python client: polar-flow.

What It Does

It's an async Python library that wraps the entire Polar AccessLink API. Sleep data, exercise history, activity metrics, nightly recharge, HRV - everything accessible through clean method calls.

async with PolarFlow(access_token="your-token") as client:
    sleep = await client.sleep.list(days=7)
    exercises = await client.exercises.list()
    activity = await client.daily_activity.list(days=30)

Type hints everywhere. Pydantic models for all the responses. Proper async/await so you're not blocking while waiting for API calls.

The Authentication Nightmare

OAuth2 is always a pain. Polar uses the authorization code flow, which means opening a browser, redirecting to their auth page, catching the callback, exchanging codes for tokens.

Built a CLI tool to handle this:

polar-flow auth

Opens your browser, handles the callback, saves your tokens. Done. You don't need to think about OAuth again unless your token expires.

Why Async

Most Python HTTP libraries use requests, which is synchronous. That's fine for quick scripts, but if you're building something that fetches data for multiple users or needs to stay responsive, you're going to have problems.

Used httpx instead. Same API feel as requests but properly async. All the endpoint methods are async, so you can fetch data without blocking your event loop.

The Data

Polar tracks a lot:

Sleep: Total duration, deep sleep, REM sleep, light sleep. Sleep score (0-100). HRV during sleep. Breathing rate. Sleep stages timeline.

Exercises: Duration, calories, heart rate zones. GPS data (if your watch has it). Samples at whatever interval you recorded.

Activity: Steps, distance, calories. Active time vs sedentary time. Inactivity alerts.

Nightly Recharge: ANS charge (how well your autonomic nervous system recovered). Sleep charge. HRV-derived recovery metrics.

Installing

pip install polar-flow-api

Get API credentials from Polar's developer portal, run the auth CLI, and you're pulling data in minutes.

What I'm Building With It

This was the first step. The SDK lets me pull data programmatically. Next up: a server that stores everything and provides my own API on top of it.

Polar only keeps 28-30 days of data available through the API. If you want historical data, you need to sync it yourself and store it somewhere. That's what polar-flow-server is for - but that's another post.

The repo: github.com/StuMason/polar-flow