Get Single Session
특정 세션의 수면 분석 데이터를 요청합니다.
1. Request
1.1 URL
GET https://api.asleep.ai/data/v3/sessions/{session_id}
1.2 Header
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| x-api-key | String | O | - | API Key |
| x-user-id | String | O | - | 발급받은 user id |
| timezone | String | X | UTC | 분석 결과의 시간대를 해당 timezone으로 변경해서 반환 예. UTC, Asia/Seoul |
1.3 Path parameter
| Field | Type | Required | Description |
|---|---|---|---|
| session_id | String | O | 데이터를 요청하고자 하는 세션의 id |
Example
curl "https://api.asleep.ai/data/v3/sessions/{session_id}" -XGET \
-H "x-api-key: <YOUR_API_KEY>" \
-H "x-user-id: <USER_ID>"
2. Response
2.1 200 OK
- 세션 상세 정보 조회 성공
2.1.1 Body (result field)
세션의 상태와 계약 조건에 따라 stat object의 nullable이 결정됩니다.
if peculiarities == IN_PROGRESS or NO_REALTIME_POLLING or TOO_SHORT_FOR_ANALYSIS or TOO_MANY_DEFECTS_IN_SLEEP_STAGES: stat object는 null
| Field | Type | Description |
|---|---|---|
| timezone | String | 타임존 (Timezone List) |
| peculiarities | List | 해당 수면 세션의 특이사항이 있을 경우 이를 설명해주는 필드. 해당 필드는 여러 개의 라벨을 포함할 수 있음.IN_PROGRESS: 세션이 OPEN, CLOSED인 경우NEVER_SLEPT: 분석 결과 세션 측정시간 동안 전혀 잠을 자지 않았다고 판단 되는 경우TOO_SHORT_FOR_ANALYSIS: 측정시간이 너무 짧아 유효한 분석을 할 수 없는 경우 (현재 20분 미만)TOO_LONG_FOR_ANALYSIS: 분석은 정상적으로 되었지만, 세션 측정 시간이 너무 길어 신뢰하기 어려운 경우 (현재 24시간 초과)TOO_MANY_DEFECTS_IN_SLEEP_STAGES: 오디오 업로드 누락 등의 이유로 오류율이 높아 수면 분석 결과가 충분하지 않은 경우NO_BREATHING_STABILITY: 고객의 계약 조건상 호흡 안정 분석을 지원하지 않는 경우NO_REALTIME_POLLING: 고객의 계약 조건상 실시간으로 수면 정보를 확인할 수 없는 경우 |
| missing_data_ratio | float(0~1 범위 소수점 둘째자리) | 오디오 업로드 누락 등의 이유로 인한 수면 분석 결과 오류율 |
| session | Session Object | 세션 분석 정보 |
| stat | Stat Object? | 분석 통계 정보 |
2.1.2 Session Object
if state == OPEN: session_end_time은 nullif peculiarities == NO_REALTIME_POLLING: sleep_stages는 nullif peculiarities == NO_BREATHING_STABILITY: breath_stages는 null
| Field | Type | Description |
|---|---|---|
| id | String | session id |
| state | String (OPEN,CLOSED,COMPLETE) | 세션의 상태OPEN: 진행 중인 세션으로, 오디오 업로드가 가능한 상태CLOSED: 세션 종료 요청이 보내져 종료된 세션. 오디오 파일 업로드 불가능. 업로드된 수면 오디오에 대한 분석이 계속 진행중인 상태COMPLETE: 세션 종료 후 모든 수면 분석이 완료된 상태 |
| start_time | String (YYYY-MM-DDThh:mm:ss+-hh:mm) | 세션 시작 시각 예) 2022-08-01T01:31:17+09:00 (요청 타임존이 Asia/Seoul 일 경우) |
| end_time | String (YYYY-MM-DDThh:mm:ss+-hh:mm)? | 세션 종료 시각 예) 2022-08-01T01:31:17+09:00 (요청 타임존이 Asia/Seoul 일 경우) |
| unexpected_end_time | String (YYYY-MM-DDThh:mm:ss+-hh:mm)? | 비정상 세션 종료 시각. 앱 크래시 등으로 세션이 정상적으로 진행 및 종료되지 못했을 경우, 나중에 클라이언트가 unexpected 파라미터를 1로 하여 세션을 종료시킬 경우 해당 시간이 기록됨. 이 경우 end_time은 마지막까지 업로드된 오디오 파일의 순서 번호를 기준으로 계산됨. 따라서 null이 아닐 경우 비정상 세션. |
| created_timezone | String | 세션이 생성된 타임존 (Timezone List) |
| sleep_stages | [Sleep Stages]? | 수면 단계 리스트 |
| breath_stages | [Breath Stages]? | 호흡 안정도 단계 리스트 |
| snoring_stages | [Snoring Stages]? | 코골이 단계 리스트 |
2.1.3 Sleep Stages
sleep stage (수면 단계)는 -1,0,1,2,3 중 하나의 정수로 표현되며 숫자 하나는 30초 구간의 수면 단계를 나타냅니다. 각 숫자의 의미는 아래 표와 같습니다
- 계약 조건이 수면 단계 2레벨인 경우에는 0 (wake), 1 (sleep)
| number | sleep stage |
|---|---|
| -1 | error (invalid audio, analysis error, etc) |
| 0 | wake |
| 1 | light sleep |
| 2 | deep sleep |
| 3 | REM sleep |
2.1.4 Breath Stages
breath stage (호흡 안정 단계)는 -1,0,1 중 하나의 정수로 표현되며 숫자 하나는 30초 구간의 호흡 안정 단계를 나타냅니다. 각 숫자의 의미는 아래 표와 같습니다
| number | breath stage |
|---|---|
| -1 | error (invalid audio, analysis error, etc) |
| 0 | stable |
| 1 | unstable |
2.1.5 Snoring Stages
snoring stage (코골이 단계)는 -1,0,1 중 하나의 정수로 표현되며 숫자 하나는 30초 구간의 코골이 단계를 나타냅니다. 각 숫자의 의미는 아래 표와 같습니다
| number | snoring stage |
|---|---|
| -1 | error (invalid audio, analysis error, etc) |
| 0 | no snoring |
| 1 | snoring |
2.1.6 Stat Object
각 메트릭에 대한 자세한 설명은 Key Concepts을 참조하실 수 있습니다.
if state == COMPLETE일 때if 2단계 수면 분석을 사용할 경우: wake와 sleep 밖에 단계가 없으므로 time_in_rem, time_in_light, time_in_deep, rem_ratio, light_ratio, deep_ratio, light_latency, deep_latency, rem_latency 값은 nullif peculiarities == NO_BREATHING_STABILITY: 해당 기능이 제공되지 않으므로 time_in_stable_breath, time_in_unstable_breath, stable_breath_ratio, unstable_breath_ratio, breathing_pattern, breathing_index, unstable_breath_count 값은 nullif peculiarities == NEVER_SLEPT: 잠을 자지 않은 것이므로 sleep_latency, sleep_time, wakeup_latency, wake_time, wake_ratio, sleep_ratio, rem_ratio, light_ratio, deep_ratio, stable_breath_ratio, unstable_breath_ratio, breathing_pattern, breathing_index, light_latency, deep_latency, rem_latency, sleep_cycle, longest_waso, sleep_index 모두 null
- 새롭게 추가된 메트릭들은 이전 세션들에 대한 데이터를 지원하지 않습니다.
- 메트릭 추가 시점은 https://docs.asleep.ai/changelog 에서 확인 가능합니다.
| Field | Type | Description | Example |
|---|---|---|---|
| sleep_time | String (YYYY-MM-DDThh:mm:ss+-hh:mm)? | 수면 측정 시작 후 잠들기 까지 걸린 시간 | 2022-08-01T00:30:00+09:00 |
| wake_time | String (YYYY-MM-DDThh:mm:ss+-hh:mm)? | 잠에서 깨어난 시각 | 2022-08-01T07:30:00+09:00 |
| sleep_index | int(50 <= sleep_index <= 100)? | (Beta) 테스트 운영 수면 데이터 | 87 |
| sleep_latency | Int (seconds)? | 잠들때까지 걸린 시각 | 1800 |
| wakeup_latency | Int (seconds)? | 잠에서 깨어난 후 수면 측정을 종료하기까지 걸린 시간 | 1800 |
| light_latency | Int(seconds)? | 첫 수면 시작으로부터 첫 번째 light가 발생하기까지의 시간 | 300 |
| deep_latency | Int(seconds)? | 첫 수면 시작으로부터 첫 번째 deep이 발생하기까지의 시 | 600 |
| rem_latency | Int(seconds)? | 첫 수면 시작으로부터 첫 번째 rem이 발생하기까지의 시간 | 900 |
| time_in_bed | Int (seconds) | 수면 측정 시작 시각부터 수면 측정 종료 시각 까지의 시간 | 28800 |
| time_in_sleep_period | Int (seconds) | 수면 측정 시간 중 수면 측정 시작으로부터 잠들기 까지 걸린 시간과 잠에서 깨어난 후로부터 수면 측정을 종료하기까지 걸린 시간을 제외한 시간 (time_in_bed - sleep_latency - wakeup_latency) | 27000 |
| time_in_sleep | Int (seconds) | 수면 측정 시간 중 실제로 수면 중이었던 시간 이 시간이 deep, light, rem의 3단계로 구분됨 | 24300 |
| time_in_wake | Int (seconds) | 수면 도중에 깬 시간 | 2700 |
| time_in_light | Int (seconds)? | 수면 단계가 light 로 진행된 총 시간 | 5400 |
| time_in_deep | Int (seconds)? | 수면 단계가 deep로 진행된 총 시간 | 5400 |
| time_in_rem | Int (seconds)? | 수면 단계가 rem 으로 진행된 총 시간 | 13500 |
| time_in_stable_breath | Int (seconds)? | 호흡 안정 구간이었던 총 시간 | 24300 |
| time_in_unstable_breath | Int (seconds)? | 호흡 불안정 구간이었던 총 시간 | 2700 |
| time_in_snoring | Int? | 코골이가 발생한 총 시간 | 5400 |
| time_in_no_snoring | Int? | 코골이가 발생하지 않은 총 시간 | 23400 |
| sleep_efficiency | float (0~1 범위 소수점 둘째자리) | 수면 측정 시간 중 실제로 잠든 시간의 비율 | 0.84 |
| sleep_ratio | float (0~1 범위 소수점 둘째자리)? | 수면 단계 도중 깨지 않고 잔 시간의 비율 | 0.9 |
| wake_ratio | float (0~1 범위 소수점 둘째자리)? | 수면 단계 도중 중간에 깬 시간의 비율 | 0.1 |
| light_ratio | float (0~1 범위 소수점 둘째자리)? | 수면 단계 도중 light 수면의 비율 | 0.2 |
| deep_ratio | float (0~1 범위 소수점 둘째자리)? | 수면 단계 도중 deep 수면의 비율 | 0.2 |
| rem_ratio | float (0~1 범위 소수점 둘째자리)? | rem sleep 비율 | 0.5 |
| stable_breath_ratio | float (0~1 범위 소수점 둘째자리)? | 수면 단계 도중 호흡 안정 구간이었던 시간의 비율 | 0.9 |
| unstable_breath_ratio | float (0~1 범위 소수점 둘째자리)? | 수면 단계 도중 호흡 불안정 구간이었던 시간의 비율 | 0.1 |
| snoring_ratio | float (0~1 범위 소수점 둘째자리)? | 수면 단계 도중 코골이었던 시간의 비율 | 0.3 |
| no_snoring_ratio | float (0~1 범위 소수점 둘째자리)? | 수면 단계 도중 코골이가 아니었던 시간의 비율 | 0.7 |
| breathing_index | float (0~1 범위 소수점 둘째자리)? | 호흡 불안정 레벨을 판단하기 위한 값 | 29.7 |
| breathing_pattern | String (STABLE_BREATH,MILDLY_UNSTABLE_BREATH,MODERATELY_UNSTABLE_BREATH, SEVERELY_UNSTABLE_BREATH)? | 호흡 불안정의 단계STABLE_BREATH: 안정MILDLY_UNSTABLE_BREATH: 조금 불안정MODERATELY_UNSTABLE_BREATH: 불안정SEVERELY_UNSTABLE_BREATH: 심한 불안정 | STABLE_BREATH |
| waso_count | Int? | 수면 구간 중 wake가 발생한 횟수 | 10 |
| longest_waso | Int(seconds)? | 수면 구간 중 가장 긴 wake의 시간 | 300 |
| sleep_cycle_count | Int? | 수면 주기의 횟수 | 4 |
| sleep_cycle | Int(seconds)? | 수면 주기 1회당 평균 시간 | 6600 |
| sleep_cycle_time | List of String(YYYY-MM-DDThh:mm:ss+-hh:mm) | 수면 주기 전환 기준 시각 예) [첫번째 수면 주기 시작 시각, 첫번째 수면 주기 종료 시각, 두번째 수면 주기 종료 시각, ..., 마지막 수면 주기 종료 시각] | ["2023-09-05T16:15:00+00:00", "2023-09-05T18:03:00+00:00", "2023-09-05T20:32:30+00:00"] |
| unstable_breath_count | Int? | 불안정 호흡이 발생한 횟수 | 20 |
| snoring_count | Int? | 코골이 구간이 발생한 횟수 | 11 |
{
"detail": "OK",
"result": {
"timezone": "UTC",
"peculiarities": [],
"missing_data_ratio": 0.02,
"session": {
"id": "20230101000000_e5rsv",
"state": "COMPLETE",
"start_time": "2023-01-01T00:00:00+00:00",
"end_time": "2023-01-01T00:20:00+00:00",
"unexpected_end_time": null,
"created_timezone": "UTC",
"sleep_stages": [
1,
1,
0,
1,
3,
1,
1,
2,
2,
0,
3,
1,
3,
1,
3,
1,
0,
0,
3,
2,
0,
1,
0,
0,
0,
0,
2,
0,
2,
2,
2,
2,
1,
3,
1,
1,
2,
2,
3,
3
],
"breath_stages": [
1,
0,
0,
1,
1,
1,
0,
1,
0,
1,
1,
1,
1,
0,
0,
1,
0,
1,
1,
1,
1,
1,
1,
0,
0,
1,
0,
1,
0,
1,
1,
1,
1,
1,
1,
0,
0,
1,
0,
1
],
"snoring_stages": [
1,
0,
0,
1,
1,
1,
0,
1,
0,
1,
1,
1,
1,
0,
0,
1,
0,
1,
1,
1,
1,
1,
1,
0,
0,
1,
0,
1,
0,
1,
1,
1,
1,
1,
1,
0,
0,
1,
0,
1
]
},
"stat": {
"sleep_time": "2023-01-01T00:00:00+00:00",
"wake_time": "2023-01-01T00:20:00+00:00",
"sleep_index": 85,
"sleep_latency": 0,
"wakeup_latency": 0,
"light_latency": 300,
"deep_latency": 600,
"rem_latency": 900,
"time_in_bed": 1200,
"time_in_sleep_period": 1200,
"time_in_sleep": 900,
"time_in_wake": 300,
"time_in_light": 360,
"time_in_deep": 300,
"time_in_rem": 240,
"time_in_stable_breath": 420,
"time_in_unstable_breath": 780,
"time_in_snoring": 5400,
"time_in_no_snoring": 23400,
"sleep_efficiency": 0.75,
"sleep_ratio": 0.75,
"wake_ratio": 0.25,
"light_ratio": 0.3,
"deep_ratio": 0.25,
"rem_ratio": 0.2,
"stable_breath_ratio": 0.35,
"unstable_breath_ratio": 0.65,
"snoring_ratio": 0.3,
"no_snoring_ratio": 0.7,
"breathing_index": 64.83,
"breathing_pattern": "SEVERELY_UNSTABLE_BREATH",
"waso_count": 10,
"longest_waso": 300,
"sleep_cycle_count": 4,
"sleep_cycle": 6600,
"sleep_cycle_time": [
"2023-01-01T16:43:03+00:00",
"2023-01-01T17:47:03+00:00",
"2023-01-01T19:24:33+00:00",
"2023-01-01T20:38:33+00:00",
"2023-01-01T21:55:33+00:00"
],
"unstable_breath_count": 20,
"snoring_count": 11
}
}
}
2.2 400 Bad Request
timezone이 잘못 들어온 경우
{
"detail": "The invalid timezone is provided"
}
x-user-id가 잘못된 경우
{
"detail": "The format of x-user-id is invalid"
}
session_id가 잘못된 형식인 경우
{
"detail": "The format of sleep session id 20230608020315_hz82 is not valid"
}
2.3 404 Not Found
session_id에 해당되는 세션을 찾지 못한 경우
{
"detail": "Unable to find the sleep session of id {session_id}"
}
Updated 3 months ago