Reports

Create Reports

  • Asleep.createReports :Generate Reports to get results for sleep tracking.
fun createReports(asleepConfig: AsleepConfig?): Reports?
Parameter NameTypeDescription
asleepConfigAsleepConfig?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 NameTypeDescription
sessionIdStringWhen Sleep Tracking stops, sessionId value
reportListenerReportListenerReport 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 NameTypeDescription
idStringSleep session id
stateStringSleep session state (OPEN, CLOSED or COMPLETE)
startTimeStringStart time of the analysis range. If no range is set, it is the same as the tracking start time
endTimeString?End time of the analysis range. If no range is set, it is the same as the tracking end time
sleepStagesList<Int>?Sleep stages
breathStagesList<Int>?Breath stability stages
snoringStagesList<Int>?Snoring
createdTimezoneStringTimezone in which the session was created
unexpectedEndTimeString?End time when the session ended unexpectedly
sleepStageProbsList<List<Float>>?Probability values per sleep stage
snoringStageProbsList<List<Float>>?Probability values per snoring stage
breathStageProbsList<List<Float>>?Probability values per breath stage
measurementStartTimeString?The time at which the tracking (recording) actually started, regardless of the analysis range
measurementEndTimeString?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 NameTypeDescription
breathingIndexFloat?Breathing index
breathingPatternString?Breathing pattern
deepRatioFloat?Deep sleep ratio
lightRatioFloat?Light sleep ratio
remRatioFloat?REM sleep ratio
sleepEfficiencyFloat?Percentage of time actually slept during measurement
sleepLatencyInt?Time to fall asleep
sleepRatioFloat?Sleep ratio during sleep stage
sleepTimeString?Time the user fell asleep
stableBreathRatioFloat?Percentage of stable breathing time
timeInBedInt?Total time from sleep measurement start to end
timeInDeepInt?Total deep sleep time
timeInLightInt?Total light sleep time
timeInRemInt?Total REM sleep time
timeInSleepInt?Actual sleep time
timeInSleepPeriodInt?Sleep measurement time excluding sleep onset and wake periods
timeInStableBreathInt?Total stable breathing time
timeInUnstableBreathInt?Total unstable breathing time
timeInWakeInt?Wake time during sleep
unstableBreathRatioFloat?Percentage of unstable breathing time
wakeRatioFloat?Rate of waking time during sleep stage
wakeTimeString?Wake time
wakeupLatencyInt?Time to wake up and end sleep measurement
sleepCycleInt?Average duration of one sleep cycle
sleepCycleCountInt?Number of sleep cycles
wasoCountInt?Number of 'wake' occurrences during sleep
longestWasoInt?Duration of longest 'wake' period
unstableBreathCountInt?Number of unstable breathing episodes
lightLatencyInt?Time from sleep onset to the first light sleep
remLatencyInt?Time from sleep onset to the first REM sleep
deepLatencyInt?Time from sleep onset to the first deep sleep
sleepIndexInt?Sleep index
timeInSnoringInt?Total snoring time
timeInNoSnoringInt?Total non-snoring time
snoringRatioFloat?Percentage of time spent snoring
noSnoringRatioFloat?Percentage of time not snoring
snoringCountInt?Number of snoring episodes
sleepCycleTimeList<String>?List of sleep cycle times
Parameter NameTypeDescription
timezoneStringRequested timezone (e.g., UTC, Asia/Seoul)
startDateStringRequested start date
endDateStringRequested end date

AverageStats

Parameter NameTypeDescription
startTimeStringSession start time
endTimeStringSession end time
sleepTimeStringTime to fall asleep after sleep staging start
wakeTimeStringWake time
sleepLatencyIntTime to fall asleep
wakeupLatencyIntTime to wake up and end sleep measurement
timeInBedIntTotal time from sleep measurement start to end
timeInSleepPeriodIntSleep measurement time excluding sleep onset and wake periods
timeInSleepIntActual sleep time (deep, light, rem stages)
timeInWakeIntWake time during sleep
timeInLightInt?Total light sleep time
timeInDeepInt?Total deep sleep time
timeInRemInt?Total REM sleep time
sleepEfficiencyFloat?Percentage of time actually slept during measurement
wakeRatioFloat?Rate of waking time during sleep stage
sleepRatioFloat?Sleep ratio during sleep stage
lightRatioFloat?Light sleep ratio
deepRatioFloat?Deep sleep ratio
remRatioFloat?REM sleep ratio
wasoCountInt?Number of 'wake' occurrences during sleep
longestWasoInt?Duration of longest 'wake' period
sleepCycleCountInt?Number of sleep cycles
timeInSnoringInt?Total snoring time
timeInNoSnoringInt?Total non-snoring time
snoringRatioFloat?Percentage of time spent snoring
noSnoringRatioFloat?Percentage of time not snoring
snoringCountInt?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 analysis is 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 NameTypeDescription
startEpochIndexIntThe first epoch number of the analysis range (based on the whole measurement, inclusive)
endEpochIndexIntThe number after the last epoch of the analysis range (exclusive)
epochDurationsList<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
totalEpochCountIntNumber of epochs of the whole measurement
epochCountIntNumber of epochs included in the range
contains(seq)BooleanWhether 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 the startEpochIndex + 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 NameTypeDescription
fromDateString (YYYY-MM-DD)View start date
toDateString (YYYY-MM-DD)View last date
orderBy = "DESC"StringDESC: descending order, ASC: ascending order
offset = 0Intnumber of skipped Report
limit = 20Intmax number of Report (0~100)
reportsListenerReportsListener?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 NameTypeDescriptionVersion
sessionIdString?Sleep session ID
lastReceivedSeqNumInt?The sequence number of the last uploaded audio file
sessionEndTimeString?Session end time
sessionStartTimeString?Session start time
stateString?Sleep session state (OPEN, CLOSED or COMPLETE)
timeInBedInt?The time from the start of the sleep measurement to the end of the sleep measurement
createdTimezoneStringTimezone of session creation (Timezone List)
unexpectedEndTimeString?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 NameTypeDescription
errorCodeIntError Code Number
domainStringError Domain
detailStringerrorCode 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 NameTypeDescription
fromDateStringThe starting time for the period you want to check the average
toDateStringThe ending time for the period you want to check the average
averageReportListenerAverageReportListenerAverage 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 NameTypeDescription
periodPeriodTimezone
peculiaritiesList<String>Special considerations when calculating the average of sleep sessions
averageStatsAverageStats?An object containing the averages of sleep metrics for "sleptSessions"
neverSleptSessionsList<NeverSleptSession>A list of sessions during which it is determined that no sleep occurred at all during the measurement time.
sleptSessionsList<SleptSession>A list of sessions during which it is determined that sleep occurred during the measurement time.

Period

Parameter NameTypeDescription
timezoneStringRequested timezone (e.g., UTC, Asia/Seoul)
startDateStringRequested start date
endDateStringRequested end date

NeverSleptSessions

Parameter NameTypeDescription
idStringSession ID
startTimeStringSession start time (e.g., 2022-08-01T01:31:17+09:00)
endTimeStringSession end time (e.g., 2022-08-01T01:31:17+09:00)
completedTimeStringTime of session analysis completion (e.g., 2022-08-01T01:31:17+09:00)

SleptSessions

Parameter NameTypeDescription
idStringSession ID
createdTimezoneStringTimezone of session creation (Timezone List)
startTimeStringSession start time (e.g., 2022-08-01T01:31:17+09:00)
endTimeStringSession end time (e.g., 2022-08-01T01:31:17+09:00)
completedTimeStringTime of session analysis completion (e.g., 2022-08-01T01:31:17+09:00)
sleepEfficiencyFloatPercentage of time actually slept during sleep measurement
sleepLatencyInt?Time to fall asleep
sleepTimeString?Time to fall asleep after sleep staging start
wakeupLatencyInt?Time to wake up and end sleep measurement
wakeTimeString?Wake time
lightLatencyInt?Time to first light sleep stage
remLatencyInt?Time to first REM sleep stage
timeInWakeIntWake time during sleep
timeInSleepPeriodIntSleep measurement time excluding sleep onset and wake periods
timeInSleepIntActual sleep time (deep, light, rem stages)
timeInBedIntTotal time from sleep measurement start to end
timeInRemInt?Total REM sleep time
timeInLightInt?Total light sleep time
timeInDeepInt?Total deep sleep time
wakeRatioFloatRate of waking time during sleep stage
sleepRatioFloatSleep ratio during sleep stage
remRatioFloat?REM sleep ratio
lightRatioFloat?Light sleep ratio
deepRatioFloat?Deep sleep ratio
sleepCycleInt?Average duration of one sleep cycle
sleepCycleCountInt?Number of sleep cycles
wasoCountInt?Number of 'wake' occurrences during sleep
longestWasoInt?Duration of longest 'wake' period
timeInSnoringInt?Total snoring time
timeInNoSnoringInt?Total non-snoring time
snoringRatioFloat?Percentage of time spent snoring
noSnoringRatioFloat?Percentage of time not snoring
snoringCountInt?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 NameTypeDescription
sessionIdStringDelete sessionId value
deleteReportListenerDeleteReportListenerReport delete callback listener
  • Asleep.Reports.DeleteReportListener
interface DeleteReportListener {
    fun onSuccess(sessionId: String?)
    fun onFail(errorCode: Int, detail: String)
}
  • If success, onSuccess() is called.
Parameter NameTypeDescription
sessionIdString?delete sessionId value
  • If failure, onFail() is called.
Parameter NameTypeDescription
errorCodeIntError Code Number
domainStringError Domain
detailStringerrorCode 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 NameTypeDescription
sessionIdStringThe session ID to reanalyze
analysisStartTimeDateAnalysis start time
analysisEndTimeDateAnalysis end time. It must be later than analysisStartTime
reanalyzeListenerReanalyzeListenerReanalyze callback listener

Asleep.Reports.ReanalyzeListener

interface ReanalyzeListener {
    fun onSuccess(sessionId: String)
    fun onFail(errorCode: Int, detail: String)
}

Please Note

  • onSuccess means that the reanalysis request has been accepted. Get the updated result with getReport(sessionId), and check whether the analysis is finished with session.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.
  • AsleepConfig must have a userId. If it does not, the request is not sent and onFail(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.json still 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

CodeNameDescription
11009ERR_INVALID_PARAMETERThe start time is later than or equal to the end time (check before the request)
30000ERR_REANALYZE_FAILEDFailed to reanalyze, network error, no userId
30400ERR_REANALYZE_BAD_REQUESTInvalid start or end time
30401ERR_REANALYZE_UNAUTHORIZEDUnauthorized
30403ERR_REANALYZE_FORBIDDENNo permission to reanalyze
30404ERR_REANALYZE_NOT_FOUNDThe session does not exist
30409ERR_REANALYZE_CONFLICTCannot reanalyze now (already being reanalysed, etc.)
30410ERR_REANALYZE_GONEThe data retention period has expired
30422ERR_REANALYZE_UNPROCESSABLEThe session is still being measured
30500ERR_REANALYZE_SERVER_ERRORServer 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.


Did this page help you?