Data Integration

Scores

Overview

Sahha analyzes user data such as sleep, steps and more to create daily scores which you can display to your users.

Use the the getScores method to return a variety of Sahha Health Scores .

Consider exploring our design principles for best practices around displaying Sahha data.

Sahha App

Get scores for today

Get the most recent scores for the current day in the user's local timezone. 

// Get scores for last 24 hours


Sahha.getScores(
  types: [.wellbeing, .activity, .sleep],
  startDateTime: .now,
  endDateTime: .now)
  { error, json in
    if let error = error {
        print(error)
    } else if let json = json {
        print(json)
    }
}

Get scores for the last week

You can provide a date range if you would like to receive multiple scores over a specific time period. The response will include an array of scores for each 24 hour segment in that time period. 

// Get scores for last 7 days
// Add a date range


let today = Date()
let sevenDaysAgo = Calendar.current.date(byAdding: .day, value: -7, to: today) ?? Date()


Sahha.getScores(
  types: [.wellbeing, .activity, .sleep],
  startDate: sevenDaysAgo,
  endDate: today)
  { error, json in
    if let error = error {
        print(error)
    } else if let json = json {
        print(json)
    }
}

Score response

Scores are generated via the Sahha API.

Scores are returned as an array of objects in JSON format.

  • Parameters :

    • id: UUID for the score
    • type: The type of the score ( wellbeing, activity, sleep, etc.)
    • state: The state of the score ( low, medium, high, etc.)
    • scoreDateTime: The user's local date-time for the score in "yyyy-MM-dd'T'HH:mm:ss.SSZZZZZ" format ( "2021-10-27T16:34:06-06:00")
    • createdAtUtc: The date-time the score was created via the server in "yyyy-MM-dd'T'HH:mm:ss.SSZZZZZ" format ( "2021-10-27T16:44:06-06:00")
    • value: Numerical value of the score ( 100, 200, etc.)
    • unit: The unit for measuring the value ( count, minute, kg, bpm, etc.)
    • version: Version number of the scoring algorithm used
    • dataSources: Any array of data sources which were used to calculate the score ( age, gender, sleep, etc.)
    • factors: An array of factors which contributed to the score

    You can learn more about factors here.

Array response

The response will be in JSON format. An example response includes these fields: 

[
[
  {
    "id": "8292bd3b-babd-5229-8b8a-47e9fb6ea4e7",
    "type": "wellbeing",
    "state": "medium",
    "score": 0.75,
    "factors": [
      {
        "id": "6706845e-403d-5164-bbcf-01b4edf10393",
        "name": "sleep_duration",
        "value": 407,
        "goal": 480,
        "score": 0.81,
        "state": "medium",
        "unit": "minute"
      },
      {
        "id": "eb87ae1d-8b1f-55e0-9e61-eb730d614c5c",
        "name": "sleep_regularity",
        "value": 0.472,
        "goal": 1,
        "score": 0.47,
        "state": "low",
        "unit": "index"
      },
      {
        "id": "51bc5fc3-1a01-5ed3-9cb5-526343ea7776",
        "name": "sleep_continuity",
        "value": 9,
        "goal": 10,
        "score": 0.96,
        "state": "high",
        "unit": "minute"
      },
      {
        "id": "75f1528e-a856-5906-a710-32a35c3ec22d",
        "name": "sleep_debt",
        "value": 4.288,
        "goal": 0,
        "score": 0.77,
        "state": "minimal",
        "unit": "hour"
      },
      {
        "id": "223a84d3-b26a-5d31-9b0f-3cbfba436cda",
        "name": "circadian_alignment",
        "value": 65.5,
        "goal": 30,
        "score": 0.8,
        "state": "medium",
        "unit": "minute"
      },
      {
        "id": "595b47a0-efb4-5d97-8aab-bc715cd11e01",
        "name": "mental_recovery",
        "value": 93,
        "goal": 120,
        "score": 0.86,
        "state": "medium",
        "unit": "minute"
      },
      {
        "id": "e5ccd2a7-ae90-5f74-aa5b-f05eb2850e72",
        "name": "physical_recovery",
        "value": 38,
        "goal": 90,
        "score": 0.69,
        "state": "low",
        "unit": "minute"
      }
    ],
    "dataSources": [
      "age",
      "gender",
      "sleep"
    ],
    "scoreDateTime": "2024-12-19T15:00:00+00:00",
    "createdAtUtc": "2024-12-20T06:04:33.573051+00:00",
    "version": 1
  },
  {
    "id": "6345291b-2e0a-50d6-9fb9-767d82ba7d42",
    "type": "sleep",
    "state": "medium",
    "score": 0.75,
    "factors": [
      {
        "id": "434d2ac4-62e6-591a-a712-52b275671f27",
        "name": "sleep_duration",
        "value": 407,
        "goal": 480,
        "score": 0.81,
        "state": "medium",
        "unit": "minute"
      },
      {
        "id": "ccdd2e93-cf8e-543c-bd8c-61c2851ee2bf",
        "name": "sleep_regularity",
        "value": 0.472,
        "goal": 1,
        "score": 0.47,
        "state": "low",
        "unit": "index"
      },
      {
        "id": "f516ed53-9f8a-58b6-875c-b0e152e89356",
        "name": "sleep_continuity",
        "value": 9,
        "goal": 10,
        "score": 0.96,
        "state": "high",
        "unit": "minute"
      },
      {
        "id": "a840caa5-e541-509a-bf7f-9dd06244940d",
        "name": "sleep_debt",
        "value": 4.288,
        "goal": 0,
        "score": 0.77,
        "state": "minimal",
        "unit": "hour"
      },
      {
        "id": "7d97eda2-4e07-53d1-ad3f-0d0d91cc905e",
        "name": "circadian_alignment",
        "value": 65.5,
        "goal": 30,
        "score": 0.8,
        "state": "medium",
        "unit": "minute"
      },
      {
        "id": "53d90a66-ef66-5ee8-93bd-69aaff889125",
        "name": "mental_recovery",
        "value": 93,
        "goal": 120,
        "score": 0.86,
        "state": "medium",
        "unit": "minute"
      },
      {
        "id": "5242b459-964a-5fc6-af6c-ad6dd1473b65",
        "name": "physical_recovery",
        "value": 38,
        "goal": 90,
        "score": 0.69,
        "state": "low",
        "unit": "minute"
      }
    ],
    "dataSources": [
      "age",
      "gender",
      "sleep"
    ],
    "scoreDateTime": "2024-12-19T15:00:00+00:00",
    "createdAtUtc": "2024-12-20T06:04:25.302778+00:00",
    "version": 1
  }
]

Empty response

An empty JSON but successful response.

MINIMUM DATA REQUIREMENTS

The scoring engine requires a minimum amount of device sensor data to be uploaded and processed before a score can be determined.

If you call getScores for a new user profile or a user that has been inactive lately, it's possible for the response to be 204 No Content. This is not an error.

You will need to wait and try again every few hours until a score is available. 

// Scores are not ready yet
// Try again in a few hours
// Empty JSON
{}

Data sources

Data sources are required to generate a score.

The score is created from various data sources

To receive an score, a minimum of one data source must be configured by the SDK.

The more data sources that you configure via the SDK, the better the score that will be generated.

Some data sources are not yet available on all platforms. Sahha continues to improve its scoring engine by bringing feature parity between platforms as well as adding new data sources. a

Data Source Description Android iOS
sleep User sleep patterns ✓ ✓
steps User walking patterns ✓ ✓
screen User device screen time ✓ X
heart User heart patterns ✓ ✓
blood User blood patterns ✓ ✓
age User age ✓ ✓
gender User gender ✓ ✓

Device sensors

Use Sensors as a Data Source

Learn how to configure device sensors to collect data.

Configure Sensors

Demographics

Use Demographics as a Data Source

Learn how to configure demographics as a data source.

Configure Demographics

Next
Step 11.) User Permission