Reports
Create Reports
- Asleep.createReports :Generate Reports to get results for sleep tracking.
fun createReports(asleepConfig: AsleepConfig?): Reports?| Parameter Name | Type | Description |
|---|---|---|
| asleepConfig | AsleepConfig? | Enter the set value received by the callback in the initasleepconfig call |
Get Single Report
- Asleep.Reports.getReport :Bring sessionId Report.
fun getReport(sessionId: String, reportListener: ReportListener)| Parameter Name | Type | Description |
|---|---|---|
| sessionId | String | When Sleep Tracking stops, sessionId value |
| reportListener | ReportListener | Report Callback listener |
- Asleep.Reports.ReportListener
interface ReportListener {
fun onSuccess(report: Report?)
fun onFail(errorCode: Int, detail: String)
}- If success, onSuccess() is called.
data class Report(
val timezone: String,
val peculiarities: List<String>,
val missingDataRatio: Float,
val session: Session?,
val stat: Stat?,
val analysis: Analysis? = null
)Session
data class Session(
val id: String,
val state: String,
val startTime: String,
val endTime: String?,
val sleepStages: List<Int>?,
val breathStages: List<Int>?,
val snoringStages: List<Int>?,
val createdTimezone: String,
val unexpectedEndTime: String?,
val sleepStageProbs: List<List<Float>>?,
val snoringStageProbs: List<List<Float>>?,
val breathStageProbs: List<List<Float>>?,
val measurementStartTime: String?,
val measurementEndTime: String?
)| Parameter Name | Type | Description |
|---|---|---|
| id | String | Sleep session id |
| state | String | Sleep session state (OPEN, CLOSED or COMPLETE) |
| startTime | String | Start time of the analysis range. If no range is set, it is the same as the tracking start time |
| endTime | String? | End time of the analysis range. If no range is set, it is the same as the tracking end time |
| sleepStages | List<Int>? | Sleep stages |
| breathStages | List<Int>? | Breath stability stages |
| snoringStages | List<Int>? | Snoring |
| createdTimezone | String | Timezone in which the session was created |
| unexpectedEndTime | String? | End time when the session ended unexpectedly |
| sleepStageProbs | List<List<Float>>? | Probability values per sleep stage |
| snoringStageProbs | List<List<Float>>? | Probability values per snoring stage |
| breathStageProbs | List<List<Float>>? | Probability values per breath stage |
| measurementStartTime | String? | The time at which the tracking (recording) actually started, regardless of the analysis range |
| measurementEndTime | String? | The time at which the tracking (recording) actually ended, regardless of the analysis range |
Stat
data class Stat(
val breathingIndex: Float?,
val breathingPattern: String?,
val deepRatio: Float?,
val lightRatio: Float?,
val remRatio: Float?,
val sleepEfficiency: Float?,
val sleepLatency: Int?,
val sleepRatio: Float?,
val sleepTime: String?,
val stableBreathRatio: Float?,
val timeInBed: Int?,
val timeInDeep: Int?,
val timeInLight: Int?,
val timeInRem: Int?,
val timeInSleep: Int?,
val timeInSleepPeriod: Int?,
val timeInStableBreath: Int?,
val timeInUnstableBreath: Int?,
val timeInWake: Int?,
val unstableBreathRatio: Float?,
val wakeRatio: Float?,
val wakeTime: String?,
val wakeupLatency: Int?,
val sleepCycle: Int?,
val sleepCycleCount: Int?,
val wasoCount: Int?,
val longestWaso: Int?,
val unstableBreathCount: Int?,
val lightLatency: Int?,
val remLatency: Int?,
val deepLatency: Int?,
val sleepIndex: Int?,
val timeInSnoring: Int?,
val timeInNoSnoring: Int?,
val snoringRatio: Float?,
val noSnoringRatio: Float?,
val snoringCount: Int?,
val sleepCycleTime: List<String>?
)| Parameter Name | Type | Description |
|---|---|---|
| breathingIndex | Float? | Breathing index |
| breathingPattern | String? | Breathing pattern |
| deepRatio | Float? | Deep sleep ratio |
| lightRatio | Float? | Light sleep ratio |
| remRatio | Float? | REM sleep ratio |
| sleepEfficiency | Float? | Percentage of time actually slept during measurement |
| sleepLatency | Int? | Time to fall asleep |
| sleepRatio | Float? | Sleep ratio during sleep stage |
| sleepTime | String? | Time the user fell asleep |
| stableBreathRatio | Float? | Percentage of stable breathing time |
| timeInBed | Int? | Total time from sleep measurement start to end |
| timeInDeep | Int? | Total deep sleep time |
| timeInLight | Int? | Total light sleep time |
| timeInRem | Int? | Total REM sleep time |
| timeInSleep | Int? | Actual sleep time |
| timeInSleepPeriod | Int? | Sleep measurement time excluding sleep onset and wake periods |
| timeInStableBreath | Int? | Total stable breathing time |
| timeInUnstableBreath | Int? | Total unstable breathing time |
| timeInWake | Int? | Wake time during sleep |
| unstableBreathRatio | Float? | Percentage of unstable breathing time |
| wakeRatio | Float? | Rate of waking time during sleep stage |
| wakeTime | String? | Wake time |
| wakeupLatency | Int? | Time to wake up and end sleep measurement |
| sleepCycle | Int? | Average duration of one sleep cycle |
| sleepCycleCount | Int? | Number of sleep cycles |
| wasoCount | Int? | Number of 'wake' occurrences during sleep |
| longestWaso | Int? | Duration of longest 'wake' period |
| unstableBreathCount | Int? | Number of unstable breathing episodes |
| lightLatency | Int? | Time from sleep onset to the first light sleep |
| remLatency | Int? | Time from sleep onset to the first REM sleep |
| deepLatency | Int? | Time from sleep onset to the first deep sleep |
| sleepIndex | Int? | Sleep index |
| timeInSnoring | Int? | Total snoring time |
| timeInNoSnoring | Int? | Total non-snoring time |
| snoringRatio | Float? | Percentage of time spent snoring |
| noSnoringRatio | Float? | Percentage of time not snoring |
| snoringCount | Int? | Number of snoring episodes |
| sleepCycleTime | List<String>? | List of sleep cycle times |
| Parameter Name | Type | Description |
|---|---|---|
| timezone | String | Requested timezone (e.g., UTC, Asia/Seoul) |
| startDate | String | Requested start date |
| endDate | String | Requested end date |
AverageStats
| Parameter Name | Type | Description |
|---|---|---|
| startTime | String | Session start time |
| endTime | String | Session end time |
| sleepTime | String | Time to fall asleep after sleep staging start |
| wakeTime | String | Wake time |
| sleepLatency | Int | Time to fall asleep |
| wakeupLatency | Int | Time to wake up and end sleep measurement |
| timeInBed | Int | Total time from sleep measurement start to end |
| timeInSleepPeriod | Int | Sleep measurement time excluding sleep onset and wake periods |
| timeInSleep | Int | Actual sleep time (deep, light, rem stages) |
| timeInWake | Int | Wake time during sleep |
| timeInLight | Int? | Total light sleep time |
| timeInDeep | Int? | Total deep sleep time |
| timeInRem | Int? | Total REM sleep time |
| sleepEfficiency | Float? | Percentage of time actually slept during measurement |
| wakeRatio | Float? | Rate of waking time during sleep stage |
| sleepRatio | Float? | Sleep ratio during sleep stage |
| lightRatio | Float? | Light sleep ratio |
| deepRatio | Float? | Deep sleep ratio |
| remRatio | Float? | REM sleep ratio |
| wasoCount | Int? | Number of 'wake' occurrences during sleep |
| longestWaso | Int? | Duration of longest 'wake' period |
| sleepCycleCount | Int? | Number of sleep cycles |
| timeInSnoring | Int? | Total snoring time |
| timeInNoSnoring | Int? | Total non-snoring time |
| snoringRatio | Float? | Percentage of time spent snoring |
| noSnoringRatio | Float? | Percentage of time not snoring |
| snoringCount | Int? | Number of snoring episodes |
Analysis
- Information about the range analysed by the server. If the session is still being tracked, the range is not determined yet and
analysisis null.
data class Analysis(
val startEpochIndex: Int,
val endEpochIndex: Int,
val epochDurations: List<Int>,
val totalEpochCount: Int
) {
val epochCount: Int
fun contains(seq: Int): Boolean
}| Parameter Name | Type | Description |
|---|---|---|
| startEpochIndex | Int | The first epoch number of the analysis range (based on the whole measurement, inclusive) |
| endEpochIndex | Int | The number after the last epoch of the analysis range (exclusive) |
| epochDurations | List<Int> | Length in seconds of each epoch in the range. If the range boundary does not match the epoch boundary, the first and last values can be less than 30 |
| totalEpochCount | Int | Number of epochs of the whole measurement |
| epochCount | Int | Number of epochs included in the range |
| contains(seq) | Boolean | Whether the epoch number seq, based on the whole measurement, is included in the analysis range. Use it when matching with the sequence number of a recording file |
When an analysis range is specified, the index of the stage array is not based on the start of the measurement.
sleepStages[i]is thestartEpochIndex + ith epoch (30 seconds) of the whole measurement.When you calculate a time from an array index or match it with a recording file, add
startEpochIndex.
Get Multiple Reports
- Asleep.Reports.getReports :Gets a list of Report that are within the range of the date you entered.
fun getReports(
fromDate: String,
toDate: String,
orderBy: String = "DESC",
offset: Int = 0,
limit: Int = 20,
reportsListener: ReportsListener?)
| Parameter Name | Type | Description |
|---|---|---|
| fromDate | String (YYYY-MM-DD) | View start date |
| toDate | String (YYYY-MM-DD) | View last date |
| orderBy = "DESC" | String | DESC: descending order, ASC: ascending order |
| offset = 0 | Int | number of skipped Report |
| limit = 20 | Int | max number of Report (0~100) |
| reportsListener | ReportsListener? | Report list callback listener |
- Asleep.Reports.ReportsListener
interface ReportsListener {
fun onSuccess(reports: List<SleepSession>?)
fun onFail(errorCode: Int, detail: String)
}- If success, onSuccess() is called.
data class SleepSession(
val sessionId: String?,
val lastReceivedSeqNum: Int?,
val sessionEndTime: String?,
val sessionStartTime: String?,
val state: String?,
val timeInBed: Int?,
val createdTimezone: String,
val unexpectedEndTime: String?
)| Parameter Name | Type | Description | Version |
|---|---|---|---|
| sessionId | String? | Sleep session ID | |
| lastReceivedSeqNum | Int? | The sequence number of the last uploaded audio file | |
| sessionEndTime | String? | Session end time | |
| sessionStartTime | String? | Session start time | |
| state | String? | Sleep session state (OPEN, CLOSED or COMPLETE) | |
| timeInBed | Int? | The time from the start of the sleep measurement to the end of the sleep measurement | |
| createdTimezone | String | Timezone of session creation (Timezone List) | |
| unexpectedEndTime | String? | Abnormal session termination time. This assign the next initAsleepConfig time. |
- When getReport() is called with a sessionId, it acquires a comprehensive report.
- If failure, onFail() is called.
| Parameter Name | Type | Description |
|---|---|---|
| errorCode | Int | Error Code Number |
| domain | String | Error Domain |
| detail | String | errorCode Message |
Average-stats
- Asleep.Reports.getAverageReport
- You can check the average sleep metrics for a specific period of time.
fun getAverageReport(fromDate: String, toDate: String, averageReportListener: AverageReportListener?)| Parameter Name | Type | Description |
|---|---|---|
| fromDate | String | The starting time for the period you want to check the average |
| toDate | String | The ending time for the period you want to check the average |
| averageReportListener | AverageReportListener | Average Report callback listener |
- Asleep.Reports.AverageReportListener
interface AverageReportListener {
fun onSuccess(averageReport: AverageReport?)
fun onFail(errorCode: Int, detail: String)
}- If success, onSuccess() is called.
AverageReport
data class AverageReport (
val period: Period,
val peculiarities: List<String>,
val averageStats: AverageStats?,
val neverSleptSessions: List<NeverSleptSessions>,
val sleptSessions: List<SleptSessions>
)| Parameter Name | Type | Description |
|---|---|---|
| period | Period | Timezone |
| peculiarities | List<String> | Special considerations when calculating the average of sleep sessions |
| averageStats | AverageStats? | An object containing the averages of sleep metrics for "sleptSessions" |
| neverSleptSessions | List<NeverSleptSession> | A list of sessions during which it is determined that no sleep occurred at all during the measurement time. |
| sleptSessions | List<SleptSession> | A list of sessions during which it is determined that sleep occurred during the measurement time. |
Period
| Parameter Name | Type | Description |
|---|---|---|
| timezone | String | Requested timezone (e.g., UTC, Asia/Seoul) |
| startDate | String | Requested start date |
| endDate | String | Requested end date |
NeverSleptSessions
| Parameter Name | Type | Description |
|---|---|---|
| id | String | Session ID |
| startTime | String | Session start time (e.g., 2022-08-01T01:31:17+09:00) |
| endTime | String | Session end time (e.g., 2022-08-01T01:31:17+09:00) |
| completedTime | String | Time of session analysis completion (e.g., 2022-08-01T01:31:17+09:00) |
SleptSessions
| Parameter Name | Type | Description |
|---|---|---|
| id | String | Session ID |
| createdTimezone | String | Timezone of session creation (Timezone List) |
| startTime | String | Session start time (e.g., 2022-08-01T01:31:17+09:00) |
| endTime | String | Session end time (e.g., 2022-08-01T01:31:17+09:00) |
| completedTime | String | Time of session analysis completion (e.g., 2022-08-01T01:31:17+09:00) |
| sleepEfficiency | Float | Percentage of time actually slept during sleep measurement |
| sleepLatency | Int? | Time to fall asleep |
| sleepTime | String? | Time to fall asleep after sleep staging start |
| wakeupLatency | Int? | Time to wake up and end sleep measurement |
| wakeTime | String? | Wake time |
| lightLatency | Int? | Time to first light sleep stage |
| remLatency | Int? | Time to first REM sleep stage |
| timeInWake | Int | Wake time during sleep |
| timeInSleepPeriod | Int | Sleep measurement time excluding sleep onset and wake periods |
| timeInSleep | Int | Actual sleep time (deep, light, rem stages) |
| timeInBed | Int | Total time from sleep measurement start to end |
| timeInRem | Int? | Total REM sleep time |
| timeInLight | Int? | Total light sleep time |
| timeInDeep | Int? | Total deep sleep time |
| wakeRatio | Float | Rate of waking time during sleep stage |
| sleepRatio | Float | Sleep ratio during sleep stage |
| remRatio | Float? | REM sleep ratio |
| lightRatio | Float? | Light sleep ratio |
| deepRatio | Float? | Deep sleep ratio |
| sleepCycle | Int? | Average duration of one sleep cycle |
| sleepCycleCount | Int? | Number of sleep cycles |
| wasoCount | Int? | Number of 'wake' occurrences during sleep |
| longestWaso | Int? | Duration of longest 'wake' period |
| timeInSnoring | Int? | Total snoring time |
| timeInNoSnoring | Int? | Total non-snoring time |
| snoringRatio | Float? | Percentage of time spent snoring |
| noSnoringRatio | Float? | Percentage of time not snoring |
| snoringCount | Int? | Number of snoring episodes |
Delete Report
When session data is deleted from the Asleep server upon a request, it becomes difficult to provide specific evidence for the deleted sessions during subsequent billing usage analysis.
- Asleep.deleteReport :Delete sessionId Report.
fun deleteReport(sessionId: String, deleteReportListener: DeleteReportListener)| Parameter Name | Type | Description |
|---|---|---|
| sessionId | String | Delete sessionId value |
| deleteReportListener | DeleteReportListener | Report delete callback listener |
- Asleep.Reports.DeleteReportListener
interface DeleteReportListener {
fun onSuccess(sessionId: String?)
fun onFail(errorCode: Int, detail: String)
}- If success, onSuccess() is called.
| Parameter Name | Type | Description |
|---|---|---|
| sessionId | String? | delete sessionId value |
- If failure, onFail() is called.
| Parameter Name | Type | Description |
|---|---|---|
| errorCode | Int | Error Code Number |
| domain | String | Error Domain |
| detail | String | errorCode Message |
Reanalyze
- Reanalyzes a session that has already ended. If you specify an analysis range (start and end time), only that range is analysed again. For example, use it when the user corrects the "time they fell asleep ~ time they woke up" after the measurement has ended.
Asleep.Reports.reanalyze()
val reports = Asleep.createReports(asleepConfig)
// Specify the analysis range
reports?.reanalyze(sessionId, analysisStartTime, analysisEndTime,
object : Reports.ReanalyzeListener {
override fun onSuccess(sessionId: String) { }
override fun onFail(errorCode: Int, detail: String) { }
})
// Reanalyze the whole measurement
reports?.reanalyze(sessionId, object : Reports.ReanalyzeListener {
override fun onSuccess(sessionId: String) { }
override fun onFail(errorCode: Int, detail: String) { }
})| Parameter Name | Type | Description |
|---|---|---|
| sessionId | String | The session ID to reanalyze |
| analysisStartTime | Date | Analysis start time |
| analysisEndTime | Date | Analysis end time. It must be later than analysisStartTime |
| reanalyzeListener | ReanalyzeListener | Reanalyze callback listener |
Asleep.Reports.ReanalyzeListener
interface ReanalyzeListener {
fun onSuccess(sessionId: String)
fun onFail(errorCode: Int, detail: String)
}Please Note
onSuccessmeans that the reanalysis request has been accepted. Get the updated result withgetReport(sessionId), and check whether the analysis is finished withsession.state == "COMPLETE".- The analysis range is decided again on every request. If you call
reanalyze(sessionId, listener)without a range, the range you specified before is not kept and the whole measurement is analysed again. To keep the range, pass the same range again. - If you request the same range again, the server does nothing and returns success. The app cannot tell "newly analysed" from "already analysed", so specify a different range if you want to change the result.
AsleepConfigmust have a userId. If it does not, the request is not sent andonFail(30000)is called.
Changing the period with a reanalysis does not bring the recording files back.Recording files are selected when the first analysis completes, against the period analysed at that time, and the files outside that period are deleted then. A reanalysis only sends a request to the server and never touches the files on the device, so recordings that were already deleted do not come back.
- Widening the period: there are no recordings for the part that was added
- Moving to a period that does not overlap the first one: there are no recordings at all
- Narrowing to a part of the first period: only the files that were kept in the first place are available
audio_segments.jsonstill lists a row for every segment of the whole recording; only the file path is empty for the segments that were not kept. An app cannot tell "no recording was ever made here" apart from "the recording was cleaned up".If you need the recordings for a wider period, request that period when you stop the measurement.
Error codes
| Code | Name | Description |
|---|---|---|
| 11009 | ERR_INVALID_PARAMETER | The start time is later than or equal to the end time (check before the request) |
| 30000 | ERR_REANALYZE_FAILED | Failed to reanalyze, network error, no userId |
| 30400 | ERR_REANALYZE_BAD_REQUEST | Invalid start or end time |
| 30401 | ERR_REANALYZE_UNAUTHORIZED | Unauthorized |
| 30403 | ERR_REANALYZE_FORBIDDEN | No permission to reanalyze |
| 30404 | ERR_REANALYZE_NOT_FOUND | The session does not exist |
| 30409 | ERR_REANALYZE_CONFLICT | Cannot reanalyze now (already being reanalysed, etc.) |
| 30410 | ERR_REANALYZE_GONE | The data retention period has expired |
| 30422 | ERR_REANALYZE_UNPROCESSABLE | The session is still being measured |
| 30500 | ERR_REANALYZE_SERVER_ERROR | Server error |
Avoid retrying indefinitely when you receive
30409. It can be returned not only while a reanalysis is in progress, but also for a session that cannot be reanalysed at all. If you retry, limit it to about 2 to 3 times, and treat it as a failure after that.
Updated about 1 month ago
