Skip to main content

renpho-api

PyPI CI Python

Unofficial Python client for the Renpho Health API. Pull body composition measurements from Renpho smart scales and measuring tapes programmatically.

Based on reverse-engineering from RenphoGarminSync-CLI.

Installation

pip install renpho-api

For .env file support (recommended for CLI usage):

pip install "renpho-api[dotenv]"

CLI Usage

  1. Create a .env file (copy .env.example, or export the variables):
RENPHO_EMAIL=your@email.com
RENPHO_PASSWORD=your_plain_text_password
  1. Run the CLI:
renpho            # or, from a source checkout: python -m renpho

This will log in, discover your scales, fetch all measurements, print the 5 most recent, and save everything to renpho_data/ as JSON and CSV. If the account has a smart tape measure it also writes girth.json / girth.csv; accounts without one simply report no girth records.

The CLI exports measurements for you and every family member on the account. Each row is tagged with a userName field, and the family profiles are saved to family_members.json. Session tokens and password fields are never written to these files.

Set RENPHO_SESSION_FILE to reuse the login between runs: the CLI then logs in only when the saved session has been ended by another login (see Sessions). A run that reuses a session doesn't know your display name, so your own rows have no userName that time.

Environment variables

Variable Required Description
RENPHO_EMAIL Yes Your Renpho account email
RENPHO_PASSWORD Yes Your Renpho account password
RENPHO_DEBUG No Set to 1 to print API request/response details
RENPHO_OUTPUT_DIR No Output directory (default: renpho_data)
RENPHO_FRIEND_ID No Read this friend's daily data instead of your own (see Reading through a friend account)
RENPHO_SESSION_FILE No Save the session here and reuse it on the next run (e.g. ~/.config/renpho/session.json)

Library Usage

from renpho import RenphoClient

client = RenphoClient("user@example.com", "password")
client.login()

# All of your measurements, newest first. Family members who share the scale
# are not included (see "Family members" below).
measurements = client.get_all_measurements()

for m in measurements:
    print(m["weight"], m.get("bodyfat"), m.get("muscle"))

import renpho
print(renpho.__version__)

Step-by-step control

from renpho import RenphoClient, save_json, save_csv

client = RenphoClient("user@example.com", "password")
client.login()

# Get device/scale info
device_info = client.get_device_info()
scales = device_info["scale"]

# Fetch your rows from a scale table that lists you. The server only returns
# rows for the user id you pass, even on a table shared with family members.
# Use get_body_composition_measurements() for scales with impedance sensors
# (body fat, muscle, etc.) and fall back to get_measurements() when it comes
# back empty. Don't pass the table's "count" as a total: it counts every
# person on that table.
table = next(s for s in scales if str(client.user_id) in map(str, s["userIds"]))
measurements = client.get_body_composition_measurements(
    table_name=table["tableName"],
    user_id=client.user_id,
)
if not measurements:
    measurements = client.get_measurements(
        table_name=table["tableName"],
        user_id=client.user_id,
    )

# Export
save_json(measurements, "my_data.json")
save_csv(measurements, "my_data.csv")

Family members (sub-users)

Profiles added under your account in the app (e.g. family members sharing a scale) can be listed with get_family_members(). The logged-in user is not part of that list; their own profile is in client.user_info.

names = {str(client.user_id): client.user_info["accountName"]}
for member in client.get_family_members():
    names[str(member["id"])] = member["accountName"]

# {'5981614576857776000': 'Alice', '5991064042346217344': 'Bob'}

Each entry is a full profile dict. Its id matches the userIds listed per scale in get_device_info() and the bUserId field on measurement records. Compare IDs as strings, since they arrive as both int and str.

To fetch a family member's measurements, pass their id:

family = client.get_family_members()

# One person instead of you:
kid = client.get_all_measurements(profile_user_id=family[0]["id"])

# You plus everyone; bUserId says whose each row is:
everyone = client.get_all_measurements(extra_user_ids=[m["id"] for m in family])

Reading through a friend account

Renpho allows one active session per account, so logging in with your main account signs the phone app out. To sync without that, read your data through Renpho's friends feature from a second account:

  1. Create a second Renpho account with an email and password. An account created with "Sign in with Google" or Apple has no password and can't log in through the API.
  2. In the Renpho app, add the second account as a friend of your main account and accept the request.
  3. Log in as the second account and read your main account's data:
client = RenphoClient("second@example.com", "password")
friend = client.get_friends()[0]          # {"userId", "accountName", ...}

days = client.get_friend_measurements(friend["userId"])
# [{"day": "2026-11-02", "timeStamp": ..., "weight": 79.5, "bodyfat": 20.1, ...}, ...]

With the CLI, set RENPHO_FRIEND_ID to the friend's userId. It writes friend_daily.json and friend_daily.csv instead of the usual files.

get_friend_trend(friend_id, param) returns the daily points for a single parameter, and get_friend_summary() and get_friend_measure_days() return the server's raw responses.

Limits of the friend endpoints:

  • One value per day (the last weigh-in that day).
  • Body composition values only on days the scale measured them.
  • One call covers a limited window. For older data, move end_time (unix seconds) back.
  • No segmental or girth data.
  • Days are grouped by a whole-hour UTC offset, by default this machine's (time_zone= to override).

This approach was worked out in #14, with a reference implementation at DawidKrynski/renpho-friends.

Multiple Renpho accounts on one email

Some users end up with two Renpho accounts under the same email — for example after the Google SSO migration created an orphan account, or after re-registering. Each account has its own user ID and its own measurement table, so the default get_all_measurements() will only return data from the account you log in to.

If you know the other account's user ID, pass it in:

measurements = client.get_all_measurements(
    extra_user_ids=["5975813831868809088"],
)

The library locates that user's rows, fetches them, and dedupes by (table, id) so you get a single combined timeline.

A password login can land on either account. If you know which one you want, pass its ID to login(). On a mismatch the session is cleared and RenphoAPIError is raised, so nothing reads the wrong account's data:

client.login(expected_user_id="5975813831868809088")

How the lookup works. Measurements are sharded across 24 tables, measurements_info_0 through measurements_info_23, and a user's rows live in measurements_info_<user_id % 24>. device/count only names the table for the account you logged in to, so any other account's table is computed instead:

RenphoClient.measurement_table_for(6000380382810832768)
# -> 'measurements_info_16'

That's normally a single lookup; only if the computed shard comes back empty does the library sweep the remaining 23. Each check tries the body-composition endpoint and then the legacy one, because some accounts answer empty on the former while holding all their rows on the latter.

How to find your other user ID:

Unfortunately there is no first-party API endpoint that lists "all accounts associated with this email" — Renpho treats accounts as independent even when emails collide. Options:

  1. Renpho support — email them and ask for your user ID(s) on file
  2. Inspect the iOS / Android app — sign in to the other account in the official app and look in Settings / Account / Help → Feedback pages (the user ID is sometimes visible there)
  3. Capture network traffic — proxy the official app through mitmproxy, sign in, and look at any request body containing userId (decrypt with the published AES-128 key — see the reverse-engineering write-up linked at the top of this README)

Once you have the ID, save it alongside your credentials and you won't need to discover it again.

Sessions: reusing a login

Two facts, checked on a live account in November 2026, shape how to use the API:

  • One session per account. Any login ends every other session on the account, on any platform. Logging in from a script signs the phone app out, and logging back in on the phone ends the script's session. (Sending platform: "web" does not get around this.)
  • Tokens last 90 days. Until another login ends it, a session can be reused for months.

So a script that runs often should keep its session instead of logging in each time:

client = RenphoClient("user@example.com", "password",
                      session_file="~/.config/renpho/session.json")
measurements = client.get_all_measurements()  # logs in only if no usable saved session

The file is written with mode 0600 and holds the session token, not the password. Treat it like a password anyway: it grants access to the account until it expires.

When another login has ended the saved session, calls raise RenphoSessionError. Pass auto_relogin=True to log in again and retry once instead. That login signs the phone app out again, which is why it is off by default. To avoid that conflict entirely, read your data from a second account (see Reading through a friend account), which then only needs to log in once every 90 days.

Lower-level pieces: client.token_expires_at (unix seconds, from the token), client.get_token_info() (asks the server; raises RenphoSessionError if the session is dead), and export_session() / import_session() / save_session() / load_session().

Devices and data counts

After login(), client.devices lists the scales and other devices bound to the account, each with deviceModel, deviceName, deviceType, mac, firmwareVersion and a connection of "bluetooth" or "wifi".

client.get_measurement_count()   # 31: your total, in one cheap request
client.get_data_counts()         # tables per store, plus girth/rope/treadmill/step/goal totals

get_measurement_count() is a cheap "has anything new arrived?" check before a full fetch. get_data_counts() is what the Renpho app uses in place of get_device_info(): it lists each measurement table for both the legacy scale store (scale) and the body composition store (compositionScale), and get_all_measurements() uses those counts to read only the stores that hold rows.

Experimental endpoints

These were found in the Renpho Health app (7.11.6) and answer on a live account, but that account had none of this data, so the fields of individual records are unconfirmed. They return the server's data as-is.

Method Returns
get_unassigned_measurements() Weigh-ins the scale couldn't attribute to a profile
get_third_party_measurements() Measurements imported from other apps (Fitbit, Health Connect, Samsung Health)
get_third_party_sources() The third-party sources linked to the account
get_goals() {"scale": [...], "girth": [...]} goals set in the app

If you have this kind of data, an issue with the (redacted) record shapes would help firm these up.

Error handling

Every API error is a RenphoAPIError (with .code, .msg, .context). Specific cases have subclasses:

Exception When
RenphoAuthError Wrong password or unknown email (codes 104, 106, 20001), or login(expected_user_id=...) landed on another account
RenphoSessionError The session expired or another login replaced it (401/403)
RenphoRateLimitError Too many requests (429)
from renpho import RenphoAPIError, RenphoAuthError, RenphoClient, RenphoSessionError

client = RenphoClient("user@example.com", "password")
try:
    measurements = client.get_all_measurements()
except RenphoAuthError:
    print("Check the email and password")
except RenphoSessionError:
    print("Signed out by another login; log in again")
except RenphoAPIError as e:
    print(f"API error: {e}")

Requests time out after 10 s to connect and 30 s to read by default. Pass RenphoClient(..., timeout=60) (or a (connect, read) pair) to change that.

Troubleshooting login

  • code=-114 ("Decryption failed …"). Renpho's gateway changed in October 2026 and now needs an appVersion header on the login request. Upgrade to renpho-api>=0.2.1. APP_VERSION must stay below 8.0.0, because the bundled AES key only works for app versions before 8.0.0.
  • code=104 ("wrong user name or password") with a correct password. Upgrade to 0.2.1 first. If it persists, check whether the account signs in with Google or Apple (next point), and if not, report it in #10.
  • Your account signs in with Google or Apple. These accounts have no password, so they cannot log in through the API.
  • The phone app logs you out after a sync. Renpho allows one active session per account, so every login() ends the app's session. Reuse the session between runs to log in far less often (see Sessions), or read your data from a second account so the phone is never signed out (see Reading through a friend account).

Smart Tape Measure (body girth)

The Renpho Smart Tape Measure stores circumference measurements (waist, hip, arms, thighs, etc.) under a separate set of endpoints from the smart scale. The same login/token works for both. All circumferences are in centimetres.

Reading girths

from renpho import RenphoClient, format_girth, normalize_girth, save_csv, save_json

client = RenphoClient("user@example.com", "password")

# Paginates through everything, newest first; logs in automatically if needed.
girths = client.get_girth_measurements()

for record in girths[:5]:
    print(format_girth(record))

save_json(girths, "girth.json")
save_csv(girths, "girth.csv")

# Or reduce a record to just the sites that were measured (zeros omitted):
latest = normalize_girth(girths[0])
# -> {"date": "2024-06-27", "waist": 90.0, "left_arm": 33.0, "hip": 100.0, "whr": 0.9, ...}

Records come back as raw API dicts (same convention as the scale methods) — see Girth metrics for the field names.

normalize_girth() returns the local measurement date (from timeStamp + timeZone), each measured site in cm, and whr (waist/hip ratio) when present. A site that was not measured comes back as 0.0 and is omitted rather than reported as a real zero.

Site names returned by normalize_girth() / accepted by build_girth_record(): neck, shoulder, chest, waist, hip, abdomen, arm / left_arm / right_arm (upper arm), thigh / left_thigh / right_thigh, calf / left_calf / right_calf. A tape measure records either the overall site or the left/right pair — whichever is unused stays 0.

The renpho CLI also fetches girth data automatically, saving it to girth.json / girth.csv alongside the scale exports.

Writing girths (backfill)

upload_girth_measurements() appends historical measurements (useful for backfilling the app's history graph). The endpoint only adds — there is no in-place replace, so re-uploading an existing date creates a second entry.

from renpho import RenphoClient, build_girth_record

client = RenphoClient("user@example.com", "password")
client.login()

record = build_girth_record(
    {"waist": 90.0, "left_arm": 33.0, "right_arm": 33.5},
    user_id=client.user_id,
    timestamp=1719500400,        # epoch seconds for the measurement
    time_zone="-5:00",
)

acks = client.upload_girth_measurements(
    [record],
    time_zone="-5",                    # short form, NOT "-5:00"
    zone_id="America/New_York",
)
# acks -> [{"id": <server id>, "timeStamp": 1719500400}]

Notes:

  • The upload endpoint returns HTTP 400 (Missing request header 'timeZone') unless the fuller app header set is sent. upload_girth_measurements() handles that for you — just pass time_zone (short form) and zone_id.
  • The server does not recalculate whrValue (waist-to-hip ratio) for records written outside the app, so uploaded entries have no WHR.

The write path was reverse-engineered from the iOS app, so it tags uploads as platform: ios / dataSource: Health — the only combination confirmed against a live account, and the reason it differs from the android platform the rest of the library sends. Both are overridable if you'd rather not claim iOS:

record = build_girth_record(
    {"waist": 90.0},
    user_id=client.user_id,
    timestamp=1719500400,
    platform="ANDROID",        # record tag; default "IOS"
    data_source="python",      # record tag; default "Health"
)

client.upload_girth_measurements([record], platform="android")  # header; default "ios"

If you confirm the endpoint accepts other values, please open an issue and we can change the defaults.

Available Metrics

Each measurement dict can contain these fields (availability depends on your scale model):

Key Description Unit
weight Weight kg
bmi BMI
bodyfat Body Fat %
water Body Water %
muscle Muscle Mass %
bone Bone Mass %
bmr Basal Metabolic Rate kcal/day
visfat Visceral Fat level
subfat Subcutaneous Fat %
protein Protein %
bodyage Body Age years
sinew Lean Body Mass kg
fatFreeWeight Fat Free Weight kg
heartRate Heart Rate bpm
cardiacIndex Cardiac Index
bodyShape Body Shape

Girth metrics

Records from get_girth_measurements() contain these fields (each with a paired *Unit, where 0 = cm). Unmeasured fields are returned as 0.

Key Description Unit
neckValue Neck cm
shoulderValue Shoulder cm
chestValue Chest cm
waistValue Waist cm
abdomenValue Abdomen cm
hipValue Hip cm
armValue / leftArmValue / rightArmValue Arm cm
thighValue / leftThighValue / rightThighValue Thigh cm
calfValue / leftCalfValue / rightCalfValue Calf cm
whrValue Waist-to-hip ratio
customValue, customValue1…customValue5 User-defined measurements cm

Project Structure

renpho-api/
├── pyproject.toml        # Package config & dependencies
├── README.md
├── renpho/
│   ├── __init__.py       # Public API exports
│   ├── __main__.py       # python -m renpho
│   ├── client.py         # RenphoClient class
│   ├── cli.py            # CLI entry point
│   ├── constants.py      # API endpoints, device types, metrics, girth sites
│   ├── crypto.py         # AES encryption/decryption
│   ├── export.py         # JSON/CSV export helpers
│   ├── girth.py          # Smart Tape Measure (body girth) helpers
│   └── py.typed          # Marks the package as typed for type checkers
├── tests/                # Unit tests (network access is blocked)
├── Makefile              # make test / make lint / make check
└── .github/workflows/    # CI (ruff + tests) and PyPI release automation

Metadata

Release files for renpho-api 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for renpho-api 0.5.0
File Size Uploaded Provenance Actions
renpho_api-0.5.0.tar.gz 57.9 kB With provenance Details for renpho_api-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for renpho-api 0.5.0
File Interpreter ABI Platform Actions
renpho_api-0.5.0-py3-none-any.whl Python 3 none any Details for renpho_api-0.5.0-py3-none-any.whl

Total release size: 94.1 kB

Release files / renpho_api-0.5.0.tar.gz

Download URL renpho_api-0.5.0.tar.gz
Size 57.9 kB
Tags Source
SHA-256 checksum
How to use checksums
988a8ab4bb97e6f925baf4ea1d453f3d85e28c6c79bb973745a6ef916018402f
BLAKE2b-256 checksum
How to use checksums
5bc82a57dc1357396a682953817a72f98ff31cf7238dc1de108fb6cdbc4a9d6d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / renpho_api-0.5.0-py3-none-any.whl

Download URL renpho_api-0.5.0-py3-none-any.whl
Size 36.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
69e64e00db1141f7d6ddb83821273549650c326441124c819de7bd2a53d2ad44
BLAKE2b-256 checksum
How to use checksums
01a6009f61a7b665a61cce49bafa99d0e79746c14a5caa315f71944473996fca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for renpho-api 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for renpho_api-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page