Implementation

Implementation

There are two ways to implement the Score:

• Implementation via webhook
  • A real-time implementation.
  • You only need to provide a webhook.
  • ROOK will automatically send you the Health Score of your users whenever they are generated.
• Implementation via API
  • An on-demand implementation.
  • It is necessary to make a request to our API.
  • It allows you to obtain historical information about your users' Health Score.

Implementation via webhook

In this implementation, it is only necessary that, at the time of contracting Health Score, you provide ROOK with a webhook to which ROOK will be automatically sending the Health Score of your users as it is generated.

This implementation follows the flow described below:

1. Your user generates data using their wearable.
2. ROOK receives the data generated by your user.
3. ROOK structures and normalizes the data generated by your user.
4. ROOK generates a Health Score with the structured information.
5. ROOK sends the Health Score of your user to your webhook.
6. You receive the Health Score of your user.

Under this implementation, you will be receiving a JSON for each of your users every time new data is generated. The JSON you will receive will follow the following structure:

Example structure

{
  "data_structure": "health_score",
  "version": 1,
  "score": {
    "health_score_data": {
      "user_id": "<USER_ID>",
      "datetime": "2020-01-01T00:00:00.000000Z",
      "global_score": 92,
      "activity_readiness_score": 88,
      "activity_sleep_score": 95,
      "readiness_sleep_score": 93,
      "activity": {
        "datetime": "2020-01-01T00:00:00.000000Z",
        "activity_score": 90,
        "generic_score": true,
        "missing_data": [
          "sex",
          "age"
        ]
      },
      "readiness": {
        "datetime": "2020-01-01T00:00:00.000000Z",
        "readiness_score": 85,
        "generic_score": true,
        "missing_data": [
          "sex",
          "age"
        ]
      },
      "sleep": {
        "datetime": "2020-01-01T00:00:00.000000Z",
        "sleep_score": 100,
        "generic_score": true,
        "missing_data": [
          "age"
        ]
      }
    }
  }
}

Implementation via API

This implementation requires making a query to the ROOK API, specifying the date range in which you want to consult the Health Score of your user. For this implementation, it will be necessary to use the <CLIENT_UUID> and <SECRET_KEY> that were provided to you when you hired the service.

This implementation follows the flow described below:

1. Your user generates data using their wearable device.
2. ROOK receives the data generated by your user.
3. ROOK structures and normalizes the data generated by your user.
4. ROOK generates a Health Score with the structured information.
5. ROOK stores the Health Score of your user.
6. You query the historical Health Score of your user through an API request to ROOK.

Example of request to ROOK's API.

GET <ROOK_API_URL>/v1/processed_data/health_score

Authentication

• Type: Basic.
• Username: <CLIENT_UUID>.
• Password: <SECRET_KEY>.

Request parameters

• user_id (required)
  • The ID with which you have registered your user.
• start_date (required)
  • Initial date of the time period you want to query.
  • It must follow the format YYYY-MM-DD.
• end_date (required)
  • End date of the time period you want to query.
  • It must follow the format YYYY-MM-DD.

Response body

{
  "data_structure": "health_score",
  "version": 1,
  "score": {
    "health_score_data": [
      {
        "user_id": "<USER_ID>",
        "datetime": "2020-01-01T00:00:00.000000Z",
        "global_score": 92,
        "activity_readiness_score": 88,
        "activity_sleep_score": 95,
        "readiness_sleep_score": 93,
        "activity": {
          "datetime": "2020-01-01T00:00:00.000000Z",
          "activity_score": 90,
          "generic_score": true,
          "missing_data": [
            "sex",
            "age"
          ]
        },
        "readiness": {
          "datetime": "2020-01-01T00:00:00.000000Z",
          "readiness_score": 85,
          "generic_score": true,
          "missing_data": [
            "sex",
            "age"
          ]
        },
        "sleep": {
          "datetime": "2020-01-01T00:00:00.000000Z",
          "sleep_score": 100,
          "generic_score": true,
          "missing_data": [
            "age"
          ]
        }
      },
      {
        "user_id": "<USER_ID>",
        "datetime": "2020-01-02T00:00:00.000000Z",
        "global_score": 92,
        "activity_readiness_score": 88,
        "activity_sleep_score": 95,
        "readiness_sleep_score": 93,
        "activity": {
          "datetime": "2020-01-02T00:00:00.000000Z",
          "activity_score": 90,
          "generic_score": true,
          "missing_data": [
            "sex",
            "age"
          ]
        },
        "readiness": {
          "datetime": "2020-01-02T00:00:00.000000Z",
          "readiness_score": 85,
          "generic_score": true,
          "missing_data": [
            "sex",
            "age"
          ]
        },
        "sleep": {
          "datetime": "2020-01-02T00:00:00.000000Z",
          "sleep_score": 100,
          "generic_score": true,
          "missing_data": [
            "age"
          ]
        }
      }      
    ]
  }
}

Response codes

• 200: OK.
• 422: The user_id does not exist.

About the generic score

Sometimes data providers may not have the ability to provide basic user data such as gender, age, weight, and height. Health Score requires this data to generate a fully customized score for your user. In this scenario, the Health Score structure includes two keys whose purpose is to indicate whether the score calculation was performed in a personalized way or not. These keys are described below:

• generic_score
  • Data type: bool.
  • Possible values: [true, false].
  • Description: If true, indicates that the user does not have the basic data required to obtain a personalized score.
• missing_data
  • Data type: array.
  • Possible values: ["sex", "age", "weight", "height"]
  • Description: Indicate which basic user data is missing to generate a personalized score.

About null values

Not all wearables are capable of obtaining all the data that Health Score requires to calculate the scores. In this case, the score in the affected section, as well as all related keys, will contain a null value, and the composite scores will not take this value into account.

Example of score with null values

{
  "data_structure": "health_score",
  "version": 1,
  "score": {
    "health_score_data": {
      "user_id": "<USER_ID>",
      "datetime": "2020-01-01T00:00:00.000000Z",
      "global_score": 65,
      "activity_readiness_score": 50,
      "activity_sleep_score": 80,
      "readiness_sleep_score": 65,
      "activity": {
        "datetime": null,
        "activity_score": null,
        "generic_score": null,
        "missing_data": [
          
        ]
      },
      "readiness": {
        "datetime": "2020-01-01T00:00:00.000000Z",
        "readiness_score": 50,
        "generic_score": true,
        "missing_data": [
          "sex",
          "age"
        ]
      },
      "sleep": {
        "datetime": "2020-01-01T00:00:00.000000Z",
        "sleep_score": 80,
        "generic_score": true,
        "missing_data": [
          "age"
        ]
      }
    }
  }
}