2023-08-02 13:58:04 +01:00
# Withings
2023-07-29 19:43:41 +01:00
2023-08-02 13:58:04 +01:00
This module provides interfaces used to communicate with the Withings Public API.
## Smart Devices Used
We use the following devices for vitals data measurement:
* [Withings Scanwatch ](https://www.withings.com/de/en/scanwatch )
* Heart Rate, SPO2
* [Withings Thermo ](https://www.withings.com/de/en/thermo )
* Body Surface Temperature
* [WIthings BPM Core ](https://www.withings.com/de/en/bpm-core )
* Blood Pressure
## API Access
Data is gathered by taking measurements using the devices, either actively (BP sleeve, thermometer) or passively (smartwatch).
The devices are connected to the Withings mobile app.
The mobile app then regularly pushes gathered data to the Withings cloud.
The Withings Dev Free plan allows for 120 API requests per minute.
Access to vitals data is available through the [Withings API ](https://developer.withings.com/ ).
A detailed [API integration guide ](https://developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/public-health-data-api-overview/ ),
as well as an [API reference guide ](https://developer.withings.com/api-reference ) are available online.
### Token expiry
2023-07-29 19:43:41 +01:00
When the access token expires, HTTP status `200 OK` is returned, but the response body is as follows:
```json
{
"status": 401,
"body": {},
"error": "XRequestID: Not provided invalid_token: The access token provided is invalid"
}
```
2023-08-02 13:58:04 +01:00
### Fetching health data
2023-07-29 19:43:41 +01:00
Health records can be fetched via GET request as follows:
```http
https://wbsapi.withings.net/measure?action=getmeas& meastypes=9,10,54,71,11
```
The type of vitals measurement is mapped as follows:
| Code | Type | Unit |
|------|--------------------------|------|
| 9 | Diastolic Blood Pressure | mmHg |
| 10 | Systolic Blood Pressure | mmHg |
| 11 | Heart Rate | bpm |
| 54 | SP02 | % |
| 71 | Body Temperature | °C |
Note the `unit` -field in the response.
For body temperature, the `unit` -field has the value `-3` .
This means that to get the body temperature in °C, you must multiply the `value` by `10^(-3)` .
The time of measurement can be parsed from the `measuregrps` 's `date` field.
A successful response looks like so:
```json
{
"status": 0,
"body": {
"updatetime": 1690491663,
"timezone": "Europe/Berlin",
"measuregrps": [
{
"grpid": 4716596696,
"attrib": 0,
"date": 1690491576,
"created": 1690491663,
"modified": 1690491663,
"category": 1,
"deviceid": "c405eb8e0e053f6601e151c7e43c04e29aad6956",
"hash_deviceid": "c405eb8e0e053f6601e151c7e43c04e29aad6956",
"measures": [
{
"value": 89,
"type": 9,
"unit": 0,
"algo": 0,
"fm": 3
},
{
"value": 109,
"type": 10,
"unit": 0,
"algo": 0,
"fm": 3
},
{
"value": 88,
"type": 11,
"unit": 0,
"algo": 0,
"fm": 3
}
],
"modelid": 44,
"model": "BPM Core",
"comment": null
},
{
"grpid": 4716596681,
"attrib": 0,
"date": 1690491236,
"created": 1690491662,
"modified": 1690491662,
"category": 1,
"deviceid": "c405eb8e0e053f6601e151c7e43c04e29aad6956",
"hash_deviceid": "c405eb8e0e053f6601e151c7e43c04e29aad6956",
"measures": [
{
"value": 65,
"type": 9,
"unit": 0,
"algo": 0,
"fm": 3
},
{
"value": 92,
"type": 10,
"unit": 0,
"algo": 0,
"fm": 3
},
{
"value": 88,
"type": 11,
"unit": 0,
"algo": 0,
"fm": 3
}
],
"modelid": 44,
"model": "BPM Core",
"comment": null
},
{
"grpid": 4712963495,
"attrib": 0,
"date": 1690375238,
"created": 1690375243,
"modified": 1690375243,
"category": 1,
"deviceid": "dbf7f61809d5fb350a16a50f6af6e826f0746082",
"hash_deviceid": "dbf7f61809d5fb350a16a50f6af6e826f0746082",
"measures": [
{
"value": 99,
"type": 54,
"unit": 0,
"algo": 33619971,
"fm": 3,
"apppfmid": 9,
"appliver": 2741,
"algo_params": {
"1": 0,
"2": 15
}
}
],
"modelid": null,
"model": null,
"comment": null,
"is_inconclusive": false
},
{
"grpid": 4712927310,
"attrib": 1,
"date": 1690374434,
"created": 1690374456,
"modified": 1690374486,
"category": 1,
"deviceid": "1d453daf947378fac40677e7a085eea73750b061",
"hash_deviceid": "1d453daf947378fac40677e7a085eea73750b061",
"measures": [
{
"value": 37370,
"type": 71,
"unit": -3,
"algo": 0,
"fm": 0
}
],
"modelid": null,
"model": null,
"comment": null
},
{
"grpid": 4712911433,
"attrib": 0,
"date": 1690373994,
"created": 1690374078,
"modified": 1690374078,
"category": 1,
"deviceid": "c405eb8e0e053f6601e151c7e43c04e29aad6956",
"hash_deviceid": "c405eb8e0e053f6601e151c7e43c04e29aad6956",
"measures": [
{
"value": 88,
"type": 9,
"unit": 0,
"algo": 0,
"fm": 3
},
{
"value": 124,
"type": 10,
"unit": 0,
"algo": 0,
"fm": 3
},
{
"value": 70,
"type": 11,
"unit": 0,
"algo": 0,
"fm": 3
}
],
"modelid": null,
"model": null,
"comment": null
}
]
}
}
```
