Samples | Sahha Docs

Overview

Sahha provides your app with realtime data samples directly from Apple Health and Google Health Connect.

Samples are an array of events and values that occur within a time period that you specify.

For example:

a steps sample which includes step count
a heartRate sample which includes beats per minute
a sleep sample which includes minutes spent in various sleep stages

Samples are fetched in realtime

Using the getSamples method will fetch the most up-to-date samples for a SahhaSensor.

This is very useful for monitoring the most recent changes in user activity.

For example, you can monitor changes in a user's heart rate.

If you'd like to check for new data continuously, you can call getSamples(.heartRate) with a timer (for example every 5 minutes).

Limiting the Date Range of Samples

Although the getSamples method is free to use, it still requires time for the device to fetch samples.

The longer the date range you specify for this method, the longer it will take for samples to ready - potentially blocking your UI.

If you are going to call getSamples using a timer, we recommend limiting the date range for new samples to match the interval you are polling (for example every 5 minutes).

Get samples for the last hour

Using getSamples will return an array of samples for the SahhaSensor and time period you specify.

To get samples for the last hour, specify a startDateTime and endDateTime with a one hour difference.

Older samples will be at the start of the array.

Newer samples will be at the end of the array.

MyApp.swift

Swift

// Get samples for the last 24 hours
// Add a date range

let today = Date()
let lastHour = Calendar.current.date(byAdding: .hour, value: -1, to: today) ?? Date()

Sahha.getSamples(
    sensor: .steps,
    startDateTime: lastHour,
    endDateTime: today)
{ error, samples in
    if let error = error {
        print(error)
    } else if samples.isEmpty == false {
        print(samples)
    }
}

MainActivity.kt

Kotlin

// Get samples for the last 24 hours
// Add a date range

Sahha.getSamples(
	sensor = SahhaSensor.steps,
  dates = Pair(LocalDateTime.now().minusHours(1), LocalDateTime.now())
    ) { error, samples ->
    error?.also {
        println(error)
    }
    samples?.also {
        println(samples)
    }
}

MyApp.dart

Dart

// Get samples for the last 24 hours
// Add a date range

SahhaFlutter.getSamples(
  sensor: SahhaSensor.steps,
  startDateTime: DateTime.now().subtract(const Duration(hours: 1)),
  endDateTime: DateTime.now())
.then((value) {
    List<dynamic> data = jsonDecode(value);
    debugPrint(data.toString());
}).catchError((error, stackTrace) => {debugPrint(error.toString())});

MyApp.tsx

TypeScript

// Get samples for the last 24 hours
// Add date range as milliseconds since epoch time

let endDate: Date = new Date();
let startDate = new Date(endDate.setHours(endDate.getHours()-1);

Sahha.getSamples(
    SahhaSensor.steps,
    startDate.getTime(),
    endDate.getTime(),
    (error: string, value: string) => {
        if (error) {
            console.error(`Error: ${error}`);
        } else if (value) {
            const jsonArray = JSON.parse(value);
            const jsonString = JSON.stringify(jsonArray);
            console.log(value);
        }
    }
);

MyApp.js

JavaScript

// Get samples for the last 24 hours
// Add date range as milliseconds since epoch time

let endDate: Date = new Date();
let startDate = new Date(endDate.setHours(endDate.getHours()-1);

Sahha.getSamples({
	sensor: SahhaSensor.steps,
	startDateTime: startDate.getTime(),
	endDateTime: endDate.getTime() })
.then(
    function (response) {
        const array = JSON.parse(response.value);
        const jsonString = JSON.stringify(array);
        console.log(jsonString);
    },
    function (error) {
        console.log(error);
    }
)

Get samples for the last day

Using getSamples will return an array of samples for the SahhaSensor and time period you specify.

To get samples for the last 24 hours, specify a startDateTime and endDateTime with a one day difference.

Older samples will be at the start of the array.

Newer samples will be at the end of the array.

MyApp.swift

Swift

// Get samples for the last 24 hours
// Add a date range

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

Sahha.getSamples(
    sensor: .steps,
    startDateTime: yesterday,
    endDateTime: today)
{ error, samples in
    if let error = error {
        print(error)
    } else if samples.isEmpty == false {
        print(samples)
    }
}

MainActivity.kt

Kotlin

// Get samples for the last 24 hours
// Add a date range

Sahha.getSamples(
	sensor = SahhaSensor.steps,
  dates = Pair(LocalDateTime.now().minusDays(1), LocalDateTime.now())
    ) { error, samples ->
    error?.also {
        println(error)
    }
    samples?.also {
        println(samples)
    }
}

MyApp.dart

Dart

// Get samples for the last 24 hours
// Add a date range

SahhaFlutter.getSamples(
  sensor: SahhaSensor.steps,
  startDateTime: DateTime.now().subtract(const Duration(days: 1)),
  endDateTime: DateTime.now())
.then((value) {
    List<dynamic> data = jsonDecode(value);
    debugPrint(data.toString());
}).catchError((error, stackTrace) => {debugPrint(error.toString())});

MyApp.tsx

TypeScript

// Get samples for the last 24 hours
// Add date range as milliseconds since epoch time

let endDate: Date = new Date();
let days = endDate.getDate() - 1;
var startDate = new Date();
startDate.setDate(days);

Sahha.getSamples(
	SahhaSensor.steps,
	startDate.getTime(),
	endDate.getTime(),
	(error: string, value: string) => {
		if (error) {
			console.error(`Error: ${error}`);
		} else if (value) {
			const jsonArray = JSON.parse(value);
			const jsonString = JSON.stringify(jsonArray);
			console.log(value);
		}
	}
);

MyApp.js

JavaScript

// Get samples for the last 24 hours
// Add date range as milliseconds since epoch time

let endDate: Date = new Date();
let days = endDate.getDate() - 1;
var startDate = new Date();
startDate.setDate(days);

Sahha.getSamples({
	sensor: SahhaSensor.steps,
	startDateTime: startDate.getTime(),
	endDateTime: endDate.getTime() })
.then(
    function (response) {
        const array = JSON.parse(response.value);
        const jsonString = JSON.stringify(array);
        console.log(jsonString);
    },
    function (error) {
        console.log(error);
    }
)

Sample response

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

Parameters:
- id: UUID for the sample
- type: The type of the sample (steps, sleep, etc.)
- startDateTime: Start date-time in "yyyy-MM-dd'T'HH:mm:ss.SSZZZZZ" format ("2021-10-27T16:34:06-06:00")
- endDateTime: End date-time in "yyyy-MM-dd'T'HH:mm:ss.SSZZZZZ" format ("2021-10-27T16:44:06-06:00")
- value: Numerical value of the sample (100, 200, etc.)
- unit: The unit for measuring the value (count, minute, kg, bpm, etc.)
- source: The source which recorded the sample in com.company.app format ("com.apple.health")

For iOS and Android, samples are returned as an array of objects in SahhaSample format.

SahhaSample.swift

Swift

public struct SahhaSample: Comparable, Codable {
    public var id: String
    public var type: String
    public var value: Double
    public var unit: String
    public var startDateTime: Date
    public var endDateTime: Date
    public var source: String
}

SahhaSample.kt

Kotlin

data class SahhaSample(
    val id: String,
    val type: String,
    val value: Double,
    val unit: String,
    val startDateTime: ZonedDateTime,
    val endDateTime: ZonedDateTime,
    val source: String,
)

Array response

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

Older samples will be at the start of the array.

Newer samples will be at the end of the array.

An example response includes these fields:

RESPONSE

JSON

[
	{
		"endDateTime": "2024-12-19T12:25:53.44+09:00",
		"source": "com.apple.health.0C1972B1-DBA3-4B25-9FE7-E9C00DF1DCE6",
		"unit": "count",
		"startDateTime": "2024-12-19T12:16:16.82+09:00",
		"value": 111,
		"type": "steps",
		"id": "4CD8C605-46CB-4349-B317-FFD984E5015A"
	},
	{
		"type": "steps",
		"source": "com.apple.health.0C1972B1-DBA3-4B25-9FE7-E9C00DF1DCE6",
		"startDateTime": "2024-12-19T12:35:09.56+09:00",
		"value": 198,
		"id": "3F16DFB3-6013-452A-95A0-EC89455F9059",
		"unit": "count",
		"endDateTime": "2024-12-19T12:40:52.96+09:00"
	},
	{
		"unit": "count",
		"id": "AA60B687-18BB-47EA-8541-D9EBE4788B82",
		"startDateTime": "2024-12-19T12:51:10.59+09:00",
		"source": "com.apple.health.0C1972B1-DBA3-4B25-9FE7-E9C00DF1DCE6",
		"value": 47,
		"endDateTime": "2024-12-19T12:56:36.07+09:00",
		"type": "steps"
	}
]

Empty response

If no samples are found for the SahhaSensor and time period you specify, you will receive an error message.

RESPONSE

JSON

"No samples found"

Using SahhaSensor

Samples are grouped by SahhaSensor type.

For example, use getSamples(.heartRate) to get samples of a user's heart rate.

Choose a SahhaSensor

You must specify which SahhaSensor to use for getSamples.

SahhaSensor	Android	iOS
gender	Sensor Not Available	Sensor Not Available
date_of_birth	Sensor Not Available	Sensor Not Available
sleep	✔	✔
steps	✔	✔
floors_climbed	✔	✔
heart_rate	✔	✔
resting_heart_rate	✔	✔
walking_heart_rate_average	Sensor Not Available	✔
heart_rate_variability_rmssd	✔	Sensor Not Available
heart_rate_variability_sdnn	Sensor Not Available	✔
blood_pressure_systolic	✔	✔
blood_pressure_diastolic	✔	✔
blood_glucose	✔	✔
vo2_max	✔	✔
oxygen_saturation	✔	✔
respiratory_rate	✔	✔
active_energy_burned	✔	✔
basal_energy_burned	Sensor Not Available	✔
total_energy_burned	✔	Sensor Not Available
basal_metabolic_rate	✔	Sensor Not Available
time_in_daylight	Sensor Not Available	✔
body_temperature	✔	✔
basal_body_temperature	✔	✔
sleeping_wrist_temperature	Sensor Not Available	✔
height	✔	✔
weight	✔	✔
lean_body_mass	✔	✔
body_mass_index	Sensor Not Available	✔
body_fat	✔	✔
body_water_mass	✔	Sensor Not Available
bone_mass	✔	Sensor Not Available
waist_circumference	Sensor Not Available	✔
stand_time	Sensor Not Available	✔
move_time	Sensor Not Available	✔
exercise_time	Sensor Not Available	✔
activity_summary	Sensor Not Available	Sensor Not Available
device_lock	Sensor Not Available	Sensor Not Available
exercise	✔	✔
energy_consumed	✔	✔