renpho-api 0.1.0__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. renpho_api-0.2.0/PKG-INFO +346 -0
  2. renpho_api-0.2.0/README.md +321 -0
  3. {renpho_api-0.1.0 → renpho_api-0.2.0}/pyproject.toml +16 -3
  4. renpho_api-0.2.0/renpho/__init__.py +38 -0
  5. {renpho_api-0.1.0 → renpho_api-0.2.0}/renpho/cli.py +51 -26
  6. renpho_api-0.2.0/renpho/client.py +626 -0
  7. renpho_api-0.2.0/renpho/constants.py +148 -0
  8. {renpho_api-0.1.0 → renpho_api-0.2.0}/renpho/export.py +22 -1
  9. renpho_api-0.2.0/renpho/girth.py +155 -0
  10. renpho_api-0.2.0/renpho_api.egg-info/PKG-INFO +346 -0
  11. {renpho_api-0.1.0 → renpho_api-0.2.0}/renpho_api.egg-info/SOURCES.txt +3 -1
  12. renpho_api-0.2.0/tests/test_client.py +443 -0
  13. {renpho_api-0.1.0 → renpho_api-0.2.0}/tests/test_constants.py +18 -1
  14. renpho_api-0.2.0/tests/test_girth.py +291 -0
  15. renpho_api-0.1.0/PKG-INFO +0 -159
  16. renpho_api-0.1.0/README.md +0 -134
  17. renpho_api-0.1.0/renpho/__init__.py +0 -24
  18. renpho_api-0.1.0/renpho/client.py +0 -267
  19. renpho_api-0.1.0/renpho/constants.py +0 -45
  20. renpho_api-0.1.0/renpho_api.egg-info/PKG-INFO +0 -159
  21. renpho_api-0.1.0/tests/test_client.py +0 -64
  22. {renpho_api-0.1.0 → renpho_api-0.2.0}/renpho/crypto.py +0 -0
  23. {renpho_api-0.1.0 → renpho_api-0.2.0}/renpho_api.egg-info/dependency_links.txt +0 -0
  24. {renpho_api-0.1.0 → renpho_api-0.2.0}/renpho_api.egg-info/entry_points.txt +0 -0
  25. {renpho_api-0.1.0 → renpho_api-0.2.0}/renpho_api.egg-info/requires.txt +0 -0
  26. {renpho_api-0.1.0 → renpho_api-0.2.0}/renpho_api.egg-info/top_level.txt +0 -0
  27. {renpho_api-0.1.0 → renpho_api-0.2.0}/setup.cfg +0 -0
  28. {renpho_api-0.1.0 → renpho_api-0.2.0}/tests/test_crypto.py +0 -0
  29. {renpho_api-0.1.0 → renpho_api-0.2.0}/tests/test_export.py +0 -0
@@ -0,0 +1,346 @@
1
+ Metadata-Version: 2.4
2
+ Name: renpho-api
3
+ Version: 0.2.0
4
+ Summary: Unofficial Python client for the Renpho Health API — pull body composition data from Renpho smart scales and body girth data from smart tape measures.
5
+ Author: danvaneijck
6
+ License-Expression: MIT
7
+ Project-URL: Repository, https://github.com/danvaneijck/renpho-api
8
+ Keywords: renpho,health,body-composition,smart-scale,tape-measure,girth,api-client
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.10
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Topic :: Software Development :: Libraries
17
+ Requires-Python: >=3.10
18
+ Description-Content-Type: text/markdown
19
+ Requires-Dist: requests>=2.28
20
+ Requires-Dist: pycryptodome>=3.15
21
+ Provides-Extra: dotenv
22
+ Requires-Dist: python-dotenv>=1.0; extra == "dotenv"
23
+ Provides-Extra: dev
24
+ Requires-Dist: pytest>=7.0; extra == "dev"
25
+
26
+ # renpho-api
27
+
28
+ [![PyPI](https://img.shields.io/pypi/v/renpho-api)](https://pypi.org/project/renpho-api/)
29
+ [![CI](https://github.com/danvaneijck/renpho-api/actions/workflows/ci.yml/badge.svg)](https://github.com/danvaneijck/renpho-api/actions/workflows/ci.yml)
30
+ [![Python](https://img.shields.io/pypi/pyversions/renpho-api)](https://pypi.org/project/renpho-api/)
31
+
32
+ Unofficial Python client for the Renpho Health API. Pull body composition measurements from Renpho smart scales and measuring tapes programmatically.
33
+
34
+ Based on reverse-engineering from [RenphoGarminSync-CLI](https://github.com/forkerer/RenphoGarminSync-CLI).
35
+
36
+ ## Installation
37
+
38
+ ```bash
39
+ pip install renpho-api
40
+ ```
41
+
42
+ For `.env` file support (recommended for CLI usage):
43
+
44
+ ```bash
45
+ pip install "renpho-api[dotenv]"
46
+ ```
47
+
48
+ ## CLI Usage
49
+
50
+ 1. Create a `.env` file (or export the variables):
51
+
52
+ ```ini
53
+ RENPHO_EMAIL=your@email.com
54
+ RENPHO_PASSWORD=your_plain_text_password
55
+ ```
56
+
57
+ 2. Run the CLI:
58
+
59
+ ```bash
60
+ renpho
61
+ ```
62
+
63
+ This will log in, discover your scales, fetch all measurements, print the 5 most
64
+ recent, and save everything to `renpho_data/` as JSON and CSV. If the account has
65
+ a smart tape measure it also writes `girth.json` / `girth.csv`; accounts without
66
+ one simply report no girth records.
67
+
68
+ ### Environment variables
69
+
70
+ | Variable | Required | Description |
71
+ | --- | --- | --- |
72
+ | `RENPHO_EMAIL` | Yes | Your Renpho account email |
73
+ | `RENPHO_PASSWORD` | Yes | Your Renpho account password |
74
+ | `RENPHO_DEBUG` | No | Set to `1` to print API request/response details |
75
+ | `RENPHO_OUTPUT_DIR` | No | Output directory (default: `renpho_data`) |
76
+
77
+ ## Library Usage
78
+
79
+ ```python
80
+ from renpho import RenphoClient
81
+
82
+ client = RenphoClient("user@example.com", "password")
83
+ client.login()
84
+
85
+ # Fetch all measurements in one call
86
+ measurements = client.get_all_measurements()
87
+
88
+ for m in measurements:
89
+ print(m["weight"], m.get("bodyfat"), m.get("muscle"))
90
+ ```
91
+
92
+ ### Step-by-step control
93
+
94
+ ```python
95
+ from renpho import RenphoClient, save_json, save_csv
96
+
97
+ client = RenphoClient("user@example.com", "password")
98
+ client.login()
99
+
100
+ # Get device/scale info
101
+ device_info = client.get_device_info()
102
+ scales = device_info["scale"]
103
+
104
+ # Fetch from a specific scale table
105
+ # Use get_body_composition_measurements() for scales with impedance sensors
106
+ # (body fat, muscle, etc.) — the server-side count is unreliable for these.
107
+ # Fall back to get_measurements() for weight-only scales.
108
+ table = scales[0]
109
+ measurements = client.get_body_composition_measurements(
110
+ table_name=table["tableName"],
111
+ user_id=client.user_id,
112
+ )
113
+ if not measurements:
114
+ measurements = client.get_measurements(
115
+ table_name=table["tableName"],
116
+ user_id=client.user_id,
117
+ total_count=table["count"],
118
+ )
119
+
120
+ # Export
121
+ save_json(measurements, "my_data.json")
122
+ save_csv(measurements, "my_data.csv")
123
+ ```
124
+
125
+ ### Multiple Renpho accounts on one email
126
+
127
+ Some users end up with **two Renpho accounts under the same email** — for
128
+ example after the Google SSO migration created an orphan account, or after
129
+ re-registering. Each account has its own user ID and its own measurement
130
+ table, so the default `get_all_measurements()` will only return data from
131
+ the account you log in to.
132
+
133
+ If you know the other account's user ID, pass it in:
134
+
135
+ ```python
136
+ measurements = client.get_all_measurements(
137
+ extra_user_ids=["5975813831868809088"],
138
+ )
139
+ ```
140
+
141
+ The library locates that user's rows, fetches them, and dedupes by
142
+ `(table, id)` so you get a single combined timeline.
143
+
144
+ **How the lookup works.** Measurements are sharded across 24 tables,
145
+ `measurements_info_0` through `measurements_info_23`, and a user's rows live in
146
+ `measurements_info_<user_id % 24>`. `device/count` only names the table for the
147
+ account you logged in to, so any other account's table is computed instead:
148
+
149
+ ```python
150
+ RenphoClient.measurement_table_for(6000380382810832768)
151
+ # -> 'measurements_info_16'
152
+ ```
153
+
154
+ That's normally a single lookup; only if the computed shard comes back empty
155
+ does the library sweep the remaining 23. Each check tries the body-composition
156
+ endpoint and then the legacy one, because some accounts answer empty on the
157
+ former while holding all their rows on the latter.
158
+
159
+ **How to find your other user ID:**
160
+
161
+ Unfortunately there is no first-party API endpoint that lists "all
162
+ accounts associated with this email" — Renpho treats accounts as
163
+ independent even when emails collide. Options:
164
+
165
+ 1. **Renpho support** — email them and ask for your user ID(s) on file
166
+ 2. **Inspect the iOS / Android app** — sign in to the other account in
167
+ the official app and look in Settings / Account / Help → Feedback
168
+ pages (the user ID is sometimes visible there)
169
+ 3. **Capture network traffic** — proxy the official app through
170
+ mitmproxy, sign in, and look at any request body containing
171
+ `userId` (decrypt with the published AES-128 key — see the
172
+ reverse-engineering write-up linked at the top of this README)
173
+
174
+ Once you have the ID, save it alongside your credentials and you won't
175
+ need to discover it again.
176
+
177
+ ### Error handling
178
+
179
+ ```python
180
+ from renpho import RenphoClient, RenphoAPIError
181
+
182
+ client = RenphoClient("user@example.com", "wrong_password")
183
+ try:
184
+ client.login()
185
+ except RenphoAPIError as e:
186
+ print(f"API error: {e}")
187
+ ```
188
+
189
+ ## Smart Tape Measure (body girth)
190
+
191
+ The Renpho Smart Tape Measure stores circumference measurements (waist, hip,
192
+ arms, thighs, etc.) under a separate set of endpoints from the smart scale. The
193
+ same login/token works for both. All circumferences are in **centimetres**.
194
+
195
+ ### Reading girths
196
+
197
+ ```python
198
+ from renpho import RenphoClient, format_girth, normalize_girth, save_csv, save_json
199
+
200
+ client = RenphoClient("user@example.com", "password")
201
+
202
+ # Paginates through everything, newest first; logs in automatically if needed.
203
+ girths = client.get_girth_measurements()
204
+
205
+ for record in girths[:5]:
206
+ print(format_girth(record))
207
+
208
+ save_json(girths, "girth.json")
209
+ save_csv(girths, "girth.csv")
210
+
211
+ # Or reduce a record to just the sites that were measured (zeros omitted):
212
+ latest = normalize_girth(girths[0])
213
+ # -> {"date": "2024-06-27", "waist": 90.0, "left_arm": 33.0, "hip": 100.0, "whr": 0.9, ...}
214
+ ```
215
+
216
+ Records come back as raw API dicts (same convention as the scale methods) — see
217
+ [Girth metrics](#girth-metrics) for the field names.
218
+
219
+ `normalize_girth()` returns the local measurement `date` (from `timeStamp` +
220
+ `timeZone`), each measured site in cm, and `whr` (waist/hip ratio) when present.
221
+ A site that was not measured comes back as `0.0` and is omitted rather than
222
+ reported as a real zero.
223
+
224
+ **Site names** returned by `normalize_girth()` / accepted by
225
+ `build_girth_record()`: `neck`, `shoulder`, `chest`, `waist`, `hip`, `abdomen`,
226
+ `arm` / `left_arm` / `right_arm` (upper arm), `thigh` / `left_thigh` /
227
+ `right_thigh`, `calf` / `left_calf` / `right_calf`. A tape measure records
228
+ either the overall site or the left/right pair — whichever is unused stays `0`.
229
+
230
+ The `renpho` CLI also fetches girth data automatically, saving it to
231
+ `girth.json` / `girth.csv` alongside the scale exports.
232
+
233
+ ### Writing girths (backfill)
234
+
235
+ `upload_girth_measurements()` appends historical measurements (useful for
236
+ backfilling the app's history graph). The endpoint only **adds** — there is no
237
+ in-place replace, so re-uploading an existing date creates a second entry.
238
+
239
+ ```python
240
+ from renpho import RenphoClient, build_girth_record
241
+
242
+ client = RenphoClient("user@example.com", "password")
243
+ client.login()
244
+
245
+ record = build_girth_record(
246
+ {"waist": 90.0, "left_arm": 33.0, "right_arm": 33.5},
247
+ user_id=client.user_id,
248
+ timestamp=1719500400, # epoch seconds for the measurement
249
+ time_zone="-5:00",
250
+ )
251
+
252
+ acks = client.upload_girth_measurements(
253
+ [record],
254
+ time_zone="-5", # short form, NOT "-5:00"
255
+ zone_id="America/New_York",
256
+ )
257
+ # acks -> [{"id": <server id>, "timeStamp": 1719500400}]
258
+ ```
259
+
260
+ > **Notes:**
261
+ >
262
+ > - The upload endpoint returns HTTP 400 (`Missing request header 'timeZone'`)
263
+ > unless the fuller app header set is sent. `upload_girth_measurements()`
264
+ > handles that for you — just pass `time_zone` (short form) and `zone_id`.
265
+ > - The server does not recalculate `whrValue` (waist-to-hip ratio) for records
266
+ > written outside the app, so uploaded entries have no WHR.
267
+
268
+ The write path was reverse-engineered from the iOS app, so it tags uploads as
269
+ `platform: ios` / `dataSource: Health` — the only combination confirmed against a
270
+ live account, and the reason it differs from the `android` platform the rest of
271
+ the library sends. Both are overridable if you'd rather not claim iOS:
272
+
273
+ ```python
274
+ record = build_girth_record(
275
+ {"waist": 90.0},
276
+ user_id=client.user_id,
277
+ timestamp=1719500400,
278
+ platform="ANDROID", # record tag; default "IOS"
279
+ data_source="python", # record tag; default "Health"
280
+ )
281
+
282
+ client.upload_girth_measurements([record], platform="android") # header; default "ios"
283
+ ```
284
+
285
+ If you confirm the endpoint accepts other values, please open an issue and we
286
+ can change the defaults.
287
+
288
+ ## Available Metrics
289
+
290
+ Each measurement dict can contain these fields (availability depends on your scale model):
291
+
292
+ | Key | Description | Unit |
293
+ | --- | --- | --- |
294
+ | `weight` | Weight | kg |
295
+ | `bmi` | BMI | |
296
+ | `bodyfat` | Body Fat | % |
297
+ | `water` | Body Water | % |
298
+ | `muscle` | Muscle Mass | % |
299
+ | `bone` | Bone Mass | % |
300
+ | `bmr` | Basal Metabolic Rate | kcal/day |
301
+ | `visfat` | Visceral Fat | level |
302
+ | `subfat` | Subcutaneous Fat | % |
303
+ | `protein` | Protein | % |
304
+ | `bodyage` | Body Age | years |
305
+ | `sinew` | Lean Body Mass | kg |
306
+ | `fatFreeWeight` | Fat Free Weight | kg |
307
+ | `heartRate` | Heart Rate | bpm |
308
+ | `cardiacIndex` | Cardiac Index | |
309
+ | `bodyShape` | Body Shape | |
310
+
311
+ ### Girth metrics
312
+
313
+ Records from `get_girth_measurements()` contain these fields (each with a
314
+ paired `*Unit`, where `0` = cm). Unmeasured fields are returned as `0`.
315
+
316
+ | Key | Description | Unit |
317
+ | --- | --- | --- |
318
+ | `neckValue` | Neck | cm |
319
+ | `shoulderValue` | Shoulder | cm |
320
+ | `chestValue` | Chest | cm |
321
+ | `waistValue` | Waist | cm |
322
+ | `abdomenValue` | Abdomen | cm |
323
+ | `hipValue` | Hip | cm |
324
+ | `armValue` / `leftArmValue` / `rightArmValue` | Arm | cm |
325
+ | `thighValue` / `leftThighValue` / `rightThighValue` | Thigh | cm |
326
+ | `calfValue` / `leftCalfValue` / `rightCalfValue` | Calf | cm |
327
+ | `whrValue` | Waist-to-hip ratio | |
328
+ | `customValue`, `customValue1`…`customValue5` | User-defined measurements | cm |
329
+
330
+ ## Project Structure
331
+
332
+ ```text
333
+ renpho-api/
334
+ ├── pyproject.toml # Package config & dependencies
335
+ ├── README.md
336
+ ├── renpho/
337
+ │ ├── __init__.py # Public API exports
338
+ │ ├── client.py # RenphoClient class
339
+ │ ├── cli.py # CLI entry point
340
+ │ ├── constants.py # API endpoints, device types, metrics, girth sites
341
+ │ ├── crypto.py # AES encryption/decryption
342
+ │ ├── export.py # JSON/CSV export helpers
343
+ │ └── girth.py # Smart Tape Measure (body girth) helpers
344
+ ├── tests/ # Unit tests
345
+ └── .github/workflows/ # CI + PyPI release automation
346
+ ```
@@ -0,0 +1,321 @@
1
+ # renpho-api
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/renpho-api)](https://pypi.org/project/renpho-api/)
4
+ [![CI](https://github.com/danvaneijck/renpho-api/actions/workflows/ci.yml/badge.svg)](https://github.com/danvaneijck/renpho-api/actions/workflows/ci.yml)
5
+ [![Python](https://img.shields.io/pypi/pyversions/renpho-api)](https://pypi.org/project/renpho-api/)
6
+
7
+ Unofficial Python client for the Renpho Health API. Pull body composition measurements from Renpho smart scales and measuring tapes programmatically.
8
+
9
+ Based on reverse-engineering from [RenphoGarminSync-CLI](https://github.com/forkerer/RenphoGarminSync-CLI).
10
+
11
+ ## Installation
12
+
13
+ ```bash
14
+ pip install renpho-api
15
+ ```
16
+
17
+ For `.env` file support (recommended for CLI usage):
18
+
19
+ ```bash
20
+ pip install "renpho-api[dotenv]"
21
+ ```
22
+
23
+ ## CLI Usage
24
+
25
+ 1. Create a `.env` file (or export the variables):
26
+
27
+ ```ini
28
+ RENPHO_EMAIL=your@email.com
29
+ RENPHO_PASSWORD=your_plain_text_password
30
+ ```
31
+
32
+ 2. Run the CLI:
33
+
34
+ ```bash
35
+ renpho
36
+ ```
37
+
38
+ This will log in, discover your scales, fetch all measurements, print the 5 most
39
+ recent, and save everything to `renpho_data/` as JSON and CSV. If the account has
40
+ a smart tape measure it also writes `girth.json` / `girth.csv`; accounts without
41
+ one simply report no girth records.
42
+
43
+ ### Environment variables
44
+
45
+ | Variable | Required | Description |
46
+ | --- | --- | --- |
47
+ | `RENPHO_EMAIL` | Yes | Your Renpho account email |
48
+ | `RENPHO_PASSWORD` | Yes | Your Renpho account password |
49
+ | `RENPHO_DEBUG` | No | Set to `1` to print API request/response details |
50
+ | `RENPHO_OUTPUT_DIR` | No | Output directory (default: `renpho_data`) |
51
+
52
+ ## Library Usage
53
+
54
+ ```python
55
+ from renpho import RenphoClient
56
+
57
+ client = RenphoClient("user@example.com", "password")
58
+ client.login()
59
+
60
+ # Fetch all measurements in one call
61
+ measurements = client.get_all_measurements()
62
+
63
+ for m in measurements:
64
+ print(m["weight"], m.get("bodyfat"), m.get("muscle"))
65
+ ```
66
+
67
+ ### Step-by-step control
68
+
69
+ ```python
70
+ from renpho import RenphoClient, save_json, save_csv
71
+
72
+ client = RenphoClient("user@example.com", "password")
73
+ client.login()
74
+
75
+ # Get device/scale info
76
+ device_info = client.get_device_info()
77
+ scales = device_info["scale"]
78
+
79
+ # Fetch from a specific scale table
80
+ # Use get_body_composition_measurements() for scales with impedance sensors
81
+ # (body fat, muscle, etc.) — the server-side count is unreliable for these.
82
+ # Fall back to get_measurements() for weight-only scales.
83
+ table = scales[0]
84
+ measurements = client.get_body_composition_measurements(
85
+ table_name=table["tableName"],
86
+ user_id=client.user_id,
87
+ )
88
+ if not measurements:
89
+ measurements = client.get_measurements(
90
+ table_name=table["tableName"],
91
+ user_id=client.user_id,
92
+ total_count=table["count"],
93
+ )
94
+
95
+ # Export
96
+ save_json(measurements, "my_data.json")
97
+ save_csv(measurements, "my_data.csv")
98
+ ```
99
+
100
+ ### Multiple Renpho accounts on one email
101
+
102
+ Some users end up with **two Renpho accounts under the same email** — for
103
+ example after the Google SSO migration created an orphan account, or after
104
+ re-registering. Each account has its own user ID and its own measurement
105
+ table, so the default `get_all_measurements()` will only return data from
106
+ the account you log in to.
107
+
108
+ If you know the other account's user ID, pass it in:
109
+
110
+ ```python
111
+ measurements = client.get_all_measurements(
112
+ extra_user_ids=["5975813831868809088"],
113
+ )
114
+ ```
115
+
116
+ The library locates that user's rows, fetches them, and dedupes by
117
+ `(table, id)` so you get a single combined timeline.
118
+
119
+ **How the lookup works.** Measurements are sharded across 24 tables,
120
+ `measurements_info_0` through `measurements_info_23`, and a user's rows live in
121
+ `measurements_info_<user_id % 24>`. `device/count` only names the table for the
122
+ account you logged in to, so any other account's table is computed instead:
123
+
124
+ ```python
125
+ RenphoClient.measurement_table_for(6000380382810832768)
126
+ # -> 'measurements_info_16'
127
+ ```
128
+
129
+ That's normally a single lookup; only if the computed shard comes back empty
130
+ does the library sweep the remaining 23. Each check tries the body-composition
131
+ endpoint and then the legacy one, because some accounts answer empty on the
132
+ former while holding all their rows on the latter.
133
+
134
+ **How to find your other user ID:**
135
+
136
+ Unfortunately there is no first-party API endpoint that lists "all
137
+ accounts associated with this email" — Renpho treats accounts as
138
+ independent even when emails collide. Options:
139
+
140
+ 1. **Renpho support** — email them and ask for your user ID(s) on file
141
+ 2. **Inspect the iOS / Android app** — sign in to the other account in
142
+ the official app and look in Settings / Account / Help → Feedback
143
+ pages (the user ID is sometimes visible there)
144
+ 3. **Capture network traffic** — proxy the official app through
145
+ mitmproxy, sign in, and look at any request body containing
146
+ `userId` (decrypt with the published AES-128 key — see the
147
+ reverse-engineering write-up linked at the top of this README)
148
+
149
+ Once you have the ID, save it alongside your credentials and you won't
150
+ need to discover it again.
151
+
152
+ ### Error handling
153
+
154
+ ```python
155
+ from renpho import RenphoClient, RenphoAPIError
156
+
157
+ client = RenphoClient("user@example.com", "wrong_password")
158
+ try:
159
+ client.login()
160
+ except RenphoAPIError as e:
161
+ print(f"API error: {e}")
162
+ ```
163
+
164
+ ## Smart Tape Measure (body girth)
165
+
166
+ The Renpho Smart Tape Measure stores circumference measurements (waist, hip,
167
+ arms, thighs, etc.) under a separate set of endpoints from the smart scale. The
168
+ same login/token works for both. All circumferences are in **centimetres**.
169
+
170
+ ### Reading girths
171
+
172
+ ```python
173
+ from renpho import RenphoClient, format_girth, normalize_girth, save_csv, save_json
174
+
175
+ client = RenphoClient("user@example.com", "password")
176
+
177
+ # Paginates through everything, newest first; logs in automatically if needed.
178
+ girths = client.get_girth_measurements()
179
+
180
+ for record in girths[:5]:
181
+ print(format_girth(record))
182
+
183
+ save_json(girths, "girth.json")
184
+ save_csv(girths, "girth.csv")
185
+
186
+ # Or reduce a record to just the sites that were measured (zeros omitted):
187
+ latest = normalize_girth(girths[0])
188
+ # -> {"date": "2024-06-27", "waist": 90.0, "left_arm": 33.0, "hip": 100.0, "whr": 0.9, ...}
189
+ ```
190
+
191
+ Records come back as raw API dicts (same convention as the scale methods) — see
192
+ [Girth metrics](#girth-metrics) for the field names.
193
+
194
+ `normalize_girth()` returns the local measurement `date` (from `timeStamp` +
195
+ `timeZone`), each measured site in cm, and `whr` (waist/hip ratio) when present.
196
+ A site that was not measured comes back as `0.0` and is omitted rather than
197
+ reported as a real zero.
198
+
199
+ **Site names** returned by `normalize_girth()` / accepted by
200
+ `build_girth_record()`: `neck`, `shoulder`, `chest`, `waist`, `hip`, `abdomen`,
201
+ `arm` / `left_arm` / `right_arm` (upper arm), `thigh` / `left_thigh` /
202
+ `right_thigh`, `calf` / `left_calf` / `right_calf`. A tape measure records
203
+ either the overall site or the left/right pair — whichever is unused stays `0`.
204
+
205
+ The `renpho` CLI also fetches girth data automatically, saving it to
206
+ `girth.json` / `girth.csv` alongside the scale exports.
207
+
208
+ ### Writing girths (backfill)
209
+
210
+ `upload_girth_measurements()` appends historical measurements (useful for
211
+ backfilling the app's history graph). The endpoint only **adds** — there is no
212
+ in-place replace, so re-uploading an existing date creates a second entry.
213
+
214
+ ```python
215
+ from renpho import RenphoClient, build_girth_record
216
+
217
+ client = RenphoClient("user@example.com", "password")
218
+ client.login()
219
+
220
+ record = build_girth_record(
221
+ {"waist": 90.0, "left_arm": 33.0, "right_arm": 33.5},
222
+ user_id=client.user_id,
223
+ timestamp=1719500400, # epoch seconds for the measurement
224
+ time_zone="-5:00",
225
+ )
226
+
227
+ acks = client.upload_girth_measurements(
228
+ [record],
229
+ time_zone="-5", # short form, NOT "-5:00"
230
+ zone_id="America/New_York",
231
+ )
232
+ # acks -> [{"id": <server id>, "timeStamp": 1719500400}]
233
+ ```
234
+
235
+ > **Notes:**
236
+ >
237
+ > - The upload endpoint returns HTTP 400 (`Missing request header 'timeZone'`)
238
+ > unless the fuller app header set is sent. `upload_girth_measurements()`
239
+ > handles that for you — just pass `time_zone` (short form) and `zone_id`.
240
+ > - The server does not recalculate `whrValue` (waist-to-hip ratio) for records
241
+ > written outside the app, so uploaded entries have no WHR.
242
+
243
+ The write path was reverse-engineered from the iOS app, so it tags uploads as
244
+ `platform: ios` / `dataSource: Health` — the only combination confirmed against a
245
+ live account, and the reason it differs from the `android` platform the rest of
246
+ the library sends. Both are overridable if you'd rather not claim iOS:
247
+
248
+ ```python
249
+ record = build_girth_record(
250
+ {"waist": 90.0},
251
+ user_id=client.user_id,
252
+ timestamp=1719500400,
253
+ platform="ANDROID", # record tag; default "IOS"
254
+ data_source="python", # record tag; default "Health"
255
+ )
256
+
257
+ client.upload_girth_measurements([record], platform="android") # header; default "ios"
258
+ ```
259
+
260
+ If you confirm the endpoint accepts other values, please open an issue and we
261
+ can change the defaults.
262
+
263
+ ## Available Metrics
264
+
265
+ Each measurement dict can contain these fields (availability depends on your scale model):
266
+
267
+ | Key | Description | Unit |
268
+ | --- | --- | --- |
269
+ | `weight` | Weight | kg |
270
+ | `bmi` | BMI | |
271
+ | `bodyfat` | Body Fat | % |
272
+ | `water` | Body Water | % |
273
+ | `muscle` | Muscle Mass | % |
274
+ | `bone` | Bone Mass | % |
275
+ | `bmr` | Basal Metabolic Rate | kcal/day |
276
+ | `visfat` | Visceral Fat | level |
277
+ | `subfat` | Subcutaneous Fat | % |
278
+ | `protein` | Protein | % |
279
+ | `bodyage` | Body Age | years |
280
+ | `sinew` | Lean Body Mass | kg |
281
+ | `fatFreeWeight` | Fat Free Weight | kg |
282
+ | `heartRate` | Heart Rate | bpm |
283
+ | `cardiacIndex` | Cardiac Index | |
284
+ | `bodyShape` | Body Shape | |
285
+
286
+ ### Girth metrics
287
+
288
+ Records from `get_girth_measurements()` contain these fields (each with a
289
+ paired `*Unit`, where `0` = cm). Unmeasured fields are returned as `0`.
290
+
291
+ | Key | Description | Unit |
292
+ | --- | --- | --- |
293
+ | `neckValue` | Neck | cm |
294
+ | `shoulderValue` | Shoulder | cm |
295
+ | `chestValue` | Chest | cm |
296
+ | `waistValue` | Waist | cm |
297
+ | `abdomenValue` | Abdomen | cm |
298
+ | `hipValue` | Hip | cm |
299
+ | `armValue` / `leftArmValue` / `rightArmValue` | Arm | cm |
300
+ | `thighValue` / `leftThighValue` / `rightThighValue` | Thigh | cm |
301
+ | `calfValue` / `leftCalfValue` / `rightCalfValue` | Calf | cm |
302
+ | `whrValue` | Waist-to-hip ratio | |
303
+ | `customValue`, `customValue1`…`customValue5` | User-defined measurements | cm |
304
+
305
+ ## Project Structure
306
+
307
+ ```text
308
+ renpho-api/
309
+ ├── pyproject.toml # Package config & dependencies
310
+ ├── README.md
311
+ ├── renpho/
312
+ │ ├── __init__.py # Public API exports
313
+ │ ├── client.py # RenphoClient class
314
+ │ ├── cli.py # CLI entry point
315
+ │ ├── constants.py # API endpoints, device types, metrics, girth sites
316
+ │ ├── crypto.py # AES encryption/decryption
317
+ │ ├── export.py # JSON/CSV export helpers
318
+ │ └── girth.py # Smart Tape Measure (body girth) helpers
319
+ ├── tests/ # Unit tests
320
+ └── .github/workflows/ # CI + PyPI release automation
321
+ ```
@@ -4,13 +4,21 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "renpho-api"
7
- version = "0.1.0"
8
- description = "Unofficial Python client for the Renpho Health API — pull body composition data from Renpho smart scales."
7
+ version = "0.2.0"
8
+ description = "Unofficial Python client for the Renpho Health API — pull body composition data from Renpho smart scales and body girth data from smart tape measures."
9
9
  readme = "README.md"
10
10
  license = "MIT"
11
11
  requires-python = ">=3.10"
12
12
  authors = [{ name = "danvaneijck" }]
13
- keywords = ["renpho", "health", "body-composition", "smart-scale", "api-client"]
13
+ keywords = [
14
+ "renpho",
15
+ "health",
16
+ "body-composition",
17
+ "smart-scale",
18
+ "tape-measure",
19
+ "girth",
20
+ "api-client",
21
+ ]
14
22
  classifiers = [
15
23
  "Development Status :: 3 - Alpha",
16
24
  "Intended Audience :: Developers",
@@ -35,3 +43,8 @@ Repository = "https://github.com/danvaneijck/renpho-api"
35
43
 
36
44
  [project.scripts]
37
45
  renpho = "renpho.cli:main"
46
+
47
+ [dependency-groups]
48
+ dev = [
49
+ "pytest-cov>=7.1.0",
50
+ ]