Raw data

Contracted partners only

Access to raw data is a special feature available only for contracted partners. If you are interested in using this feature, please contact us.

The Raw Data API provides access to unprocessed sensor signals captured directly from the Withings ScanWatch. This includes accelerometer and optical sensor (PPG) data sampled at approximately 25 Hz, enabling partners to build custom algorithms for motion analysis, heart rate variability studies, and other advanced health research use cases. Unlike processed health metrics, raw data gives full control over signal interpretation and is designed for research and clinical applications that require granular, high-frequency sensor output.

Available services

The Raw Data API consists of 3 webservices:

Rawdata v2 - Activate

This service allows to request the activation of Raw Data collection on a specific device already setup, and set the date at which the raw data collection will stop (enddate). The raw data capture will be activated as soon as the watch is able to sync with the Withings app following the Rawdata v2 - Activate API call. The capture will stop automatically at the enddate provided in the Rawdata v2 - Activate API call.

Notes

Raw data activation will put the Withings device in a specific mode that will disable all features except raw data capture. Raw data activation will strongly impact battery life of the device, it will typically drop four to seven times faster when raw data capture is activated. For Withings ScanWatch, continuous collection of raw data would reduce battery life to 3-4 days. We advise that you find the right balance between collecting raw data and optimizing battery life for your users.

Rawdata v2 - Deactivate

The role of this service is to de-activate raw data capture. Raw Data de-activation will occur as soon as the Withings device is able to sync with the Withings app.

Rawdata v2 - Get

The role of this service is to fetch raw data of a specific type that were previously captured by the Withings device.

Structure of raw data

Detailed information about the data structure can be found in the API Reference.

How to parse raw data properly

Example of body.rawdata object for Optical Sensor (PPG)

{
    "rawdata": [
        {
            "data": {
                "agc_green_adc_range": [3, 3, 3, 3],
                "agc_green_current_ua": [28188, 28188, 28188, 28188],
                "agc_ir_adc_range": [3, 3, 3, 3],
                "agc_ir_current_ua": [42768, 42768, 42768, 42768],
                "agc_red_adc_range": [3, 3, 3, 3],
                "agc_red_current_ua": [69984, 69984, 69984, 69984],
                "id": [124525, 124526, 124527, 124528],
                "ppg_green": [415607, 415595, 415587, 415578],
                "ppg_ir": [445317, 445329, 445328, 445324],
                "ppg_red": [451761, 451769, 451742, 451734],
                "timestamp": [1656329019, 1656329019, 1656329019, 1656329019]
            },
            "hash_deviceid": "00d27f2d3b8d778ac56a831663ebec528085faa0",
            "type": 2,
            "format_version": 2,
            "firmware_version": 2561,
            "sensor_name": "MAX8614X_PPG_AGC",
            "startdate": 1656329019,
            "enddate": 1656329071
        }
    ]
}

Example of body.rawdata object for Accelerometer

{
    "rawdata": [
        {
            "data": {
                "acc_x": [19, 19, 22, 20],
                "acc_y": [49, 48, 64, 58],
                "acc_z": [657, 663, 662, 659],
                "id": [73141, 73142, 73143, 73144],
                "timestamp": [1656322724, 1656322724, 1656322724, 1656322724]
            },
            "hash_deviceid": "00d27f2d3b8d778ac56a831663ebec528085faa0",
            "type": 1,
            "format_version": 2,
            "firmware_version": 2561,
            "sensor_name": "ADXL362_RAW",
            "startdate": 1656322724,
            "enddate": 1656322740
        }
    ]
}

Details on sensors and raw data

Accelerometer:
- 3 axis digital accelerometer (x, y and z) configured with a sensing range of +- 4 g
- Data for each axis is provided with a sensitivity of ~ 2 mg
  - acc_x: x axis data
  - acc_y: y axis data
  - acc_z: z axis data
Optical Sensor
- 3 wavelengths digital photoplethysmograph (green, red and infrared) provided on a positive 19 bits range (from 0 to 2^19 - 1)
- The optical driver is configured to adapt the emitted light intensity and the reception gain automatically
- For each wavelength, data is provided with additional information regarding intensity and gain settings
  - ppg_green: green wavelength data
    - agc_green_current_ua: green emitter electrical current in microampere
    - agc_green_adc_range: green channel gain setting
  - ppg_red: red wavelength data
    - agc_red_current_ua: red emitter electrical current in microampere
    - agc_red_adc_range: red channel gain setting
  - ppg_ir: infrared wavelength data
    - agc_ir_current_ua: infrared emitter electrical current in microampere
    - agc_ir_adc_range: infrared channel gain setting
- Optionally, digital optical data can be converted to get the electrical current flowing from the photodiode receiver, by using the intensity and gain settings described above:
  - ppg_green_ua [in microampere] = ppg_green * 2^agc_green_adc_range * adc_range_min_lsb_ua
    - with adc_range_min_lsb_ua = 7.8125 * 10^-6 microampere

Note

Both sensors sampling rate are about 24.824 Hz