Data Structure

Our Definition Of Health

At ROOK, we define health as a state of complete well-being, achieved through a balanced integration of three core pillars: physical health, body health, sleep health. Achieving balance means maintaining ideal levels of activity, recovery, and sleep based on individual physical characteristics and life stage. We visualize this concept through our Health Circle, a graphical representation that shows the balance among these pillars and highlights areas where adjustments may be necessary.

Our Data Structure Explained:

Summaries

Summaries are collections of data aggregated from one or more sources that represent past events. They provide a concise overview rather than complete raw data. Summaries are triggered after a full day's data has been collected for each of our three Pillars. Physical and Body Summaries are generated at the end of the day based on the users local time zone and covering activities and Sleep Summaries are generated once the full night of sleep has been processed. These summaries offer a consolidated report of daily health metrics.

Events

Events are detailed records from specific incidents that occur throughout the day and are delivered within minutes of their completion. These records may include full raw data and are triggered by occurrences throughout the day, such as an exercise session or a smart scale reading.

Our Four Pillars

Structured around our health definition, our API organizes data into four primary pillars:

1. Information Of User

User Info includes essential details about the user, such as:

• Name
• Date of birth
• Gender
• Height
• Weight

2. Physical Health

This pillar contains data about the user's physical health, such as physical activity, heart rate, oxygen levels, stress, etc.

Physical Summary

Provides the user with a summary of their physical activity from the previous day, with data collected from all activities taken from their data sources. The summary includes data such as the number of workouts performed, duration, intensity, and more.

Activity Event

Activity events contain detailed information about a specific physical activity, such as the date, time, duration, intensity, and type of activity.

Heart Rate Event

Heart rate events contain information about the user's heart rate, such as the date, time, maximum heart rate, and minimum heart rate.

Oxygenation Event

Oxygenation events contain information about the user's oxygen levels, such as the date, time, oxygen saturation, and respiratory rate.

Stress Event

Stress events contain information about the user's stress levels, such as the date, time, stress level, and stressors.

3. Sleep Health

This pillar contains data about the user's sleep health, such as sleep duration, sleep quality, sleep stages, etc.

Sleep Summary

Provides the user with a summary of their sleep activity from the previous night. The summary includes a summary of the user's sleep health, such as sleep duration, sleep quality, and sleep stages.

4. Body Health

This pillar contains data about the user's body health, such as blood glucose, blood pressure, heart rate, hydration, mood, nutrition, oxygen levels, and body temperature.

Body Summary

Provides the user with a summary of their body health from the previous day. This summary includes a summary of the user's body health, such as blood glucose, blood pressure, heart rate, hydration, mood, nutrition, oxygen levels, and body temperature.

Blood Glucose Event

Blood glucose events contain information about the user's blood glucose, such as the date, time, blood glucose level, and type of glucose test.

Blood Pressure Event

Blood pressure events contain information about the user's blood pressure, such as the date, time, systolic blood pressure, and diastolic blood pressure.

Heart Rate Event

Heart rate events contain information about the user's heart rate, such as the date, time, maximum heart rate, and minimum heart rate.

Hydration Event

Hydration events contain information about the user's hydration, such as the date, time, and hydration level.

Mood Event

Mood events contain information about the user's mood, such as the date, time, and mood.

Nutrition Event

Nutrition events contain information about the user's nutrition, such as the date, time, protein consumed, carbohydrates consumed, calorie intake, and more.

Oxygenation Event

Oxygenation events contain information about the user's oxygen levels, such as the date, time, oxygen saturation, and respiratory rate.

Temperature Event

Temperature events contain information about the user's body temperature, such as the date, time, and body temperature.

Datetimes

When interfacing with our services, all datetime values are presented in a consistent and standardized format to ensure seamless integration and clear understanding. Here are guidelines for our datetime handling:

To Clarify Terminology:

• The term "input" specifically pertains to datetime formats as they exist in our records. These are formats we've assimilated from various external data sources.

The format for the datetimes clients will receive from us is as follows:

• YYYY-MM-DDTHH:MM:SS.MS+-TZ.

Here's a breakdown of the format components:

• YYYY: Year represented in 4 digits.
• MM: Month represented in 2 digits.
• DD: Day represented in 2 digits.
• T: A literal separator.
• HH: Hour in 24-hour format (00 through 23).
• MM: Minute represented in 2 digits.
• SS: Second represented in 2 digits.
• MS: Microsecond represented in 6 digits.
• +-TZ: Time zone offset from UTC. + or - indicates the direction of the offset, and TZ represents the actual offset in HH:MM format. If the time is in UTC, this will be represented by a 'Z'.

Examples

Here are some example conversions to demonstrate how various datetime inputs (from our stored data) are transformed into the standardized ROOKConnect format:

1. Basic Date Input:

   • Input: '2023-08-09'
   • Output: '2023-08-09T00:00:00.000000Z'

2. Datetime with Hours, Minutes, and Seconds:

   • Input: '2023-08-09 15:30:50'
   • Output: '2023-08-09T15:30:50.000000Z'

3. Datetime without Seconds Precision:

   • Input: '2023-08-09T15:30:50'
   • Output: '2023-08-09T15:30:50.000000Z'

4. Datetime with Microseconds:

   • Input: '2023-08-09T15:30:50.4567'
   • Output: '2023-08-09T15:30:50.456700Z'

5. Datetime with Microseconds in UTC:

   • Input: '2023-08-09T15:30:50.4567Z'
   • Output: '2023-08-09T15:30:50.456700Z'

6. Datetime with Microseconds and Time Zone 'Z':

   • Input: '2023-08-09T15:30:50.456795438Z'
   • Output: '2023-08-09T15:30:50.456795Z'

7. Datetime with Microseconds and Time Zone Offset:

   • Input: '2023-08-09T15:30:50.4567-05'
   • Output: '2023-08-09T15:30:50.456700-05:00'

8. Datetime with Microseconds and Shortened Time Zone Offset:

   • Input: '2023-08-09T15:30:50.4567-0600'
   • Output: '2023-08-09T15:30:50.456700-06:00'

9. Datetime with Microseconds and Shortened Positive Time Zone Offset:

   • Input: '2023-08-09T15:30:50.4567+0230'
   • Output: '2023-08-09T15:30:50.456700+02:30'

10. Datetime with Microseconds and Full Positive Time Zone Offset:

    • Input: '2023-08-09T15:30:50.4567+02:00'
    • Output: '2023-08-09T15:30:50.456700+02:00'

note

• Datetime strings without timezone are assumed to be UTC.
• Microseconds are rounded to six digits.
• 'Z' represents UTC offset in alignment with ISO 8601.

Dataset

Explore our repository for examples of data structures managed by ROOK, categorized by the data sources that provide the information. Currently, we have datasets from Fitbit, Garmin, Oura, Polar, and Whoop.

Available Data Structures

Detailed definitions of each structure can be found in the ROOK documentation. The datasets in this repository include data structured as follows:

Health Pilar	Data Structure	Source of Data
		Fitbit	Garmin	Oura	Polar	Whoop
Body Health	Oxygenation Events	✖️	✖️	✔️	✖️	✖️
	Body Summaries	✔️	✖️	✔️	✔️	✔️
Physical Health	Activity Events	✔️	✔️	✔️	✔️	✔️
	Physical Summaries	✔️	✔️	✔️	✔️	✔️
Sleep Health	Sleep Summaries	✔️	✔️	✔️	✔️	✔️

Null Values

Per the JSON standard, null values, empty objects, and empty arrays are used to indicate the absence of data from the source. If a value is 0, it is provided explicitly by the data source.

How To Load Data Reports

The data structures in this repository are organized by source into JSON files. Each file contains key components such as:

• data_structure: Name of the data structure, corresponding to the data source.
• version: Version of the ROOK API that the dataset conforms to.
• created_at: Date when the dataset was created.
• body_health: Data related to the Body Health pillar.
• physical_health: Data pertaining to the Physical Health pillar.
• sleep_health: Data concerning the Sleep Health pillar.

Python Example

In the following Python code, an example is presented of how to access a body summary, an activity event, and a sleep summary from the Fitbit data source.

#!/usr/bin/env python
import json

dataset_name = 'ROOKConnect-Fitbit-dataset-v2.json'
with open(dataset_name) as f:
    data = json.load(f)

body_summary = data['body_health']['body_summaries'][0]
activity_event = data['physical_health']['activity_events'][0]
sleep_summary = data['sleep_health']['sleep_summaries'][0]

Disclaimer: This dataset is automatically updated at the end of each month. Therefore, there may be minor discrepancies with the data structures as described in the ROOK API Reference. It is advisable to always consult the API Reference for the most accurate and current structure details.