가이드 문서
Dashboard Sign InEN
Start typing to search…
These docs are for v1.0. Click to read the latest docs for v3.0.

Get Single Session

특정 세션의 수면 분석 데이터를 요청합니다.

1. Request

1.1 URL

GET https://api.asleep.ai/data/v2/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

FieldTypeRequiredDescription
session_idStringO데이터를 요청하고자 하는 세션의 id

Example

curl "https://api.asleep.ai/data/v2/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)

세션의 상태와 계약 조건에 따라 object와 object 내부 구성 요소들의 nullable이 결정됩니다.

  • if state != COMPLETE: stat object는 null
  • if state == COMPLETE && validity != VALID: stat object는 null

Field

Type

Description

timezone

String

타임존

validity

String

해당 수면 세션의 분석이 유효한지 여부
업로드된 오디오 파일들 일부가 유효하지 않거나, 유실된 비율이 일정 이상일 경우 분석이 부정확하여 이를 표시해주는 필드

IN_PROGRESS: 세션이 OPEN인 경우
INVALID:TOO_MANDY_DEFECTS_IN_SLEEP_STAGES: 수면 단계 분석 결과가 충분하지 않음
INVALID:TOO_MANY_DEFECTS_IN_OSA_STAGES: 호흡 안정도 분석 결과가 충분하지 않음
VALID: 분석이 유효

session

Session Object

세션 분석 정보

stat

Stat Object?

분석 통계 정보

2.1.2 Session Object

  • if state == OPEN: session_end_time은 null
    • if 실시간 분석 사용 안할 경우: sleep_stages는 null
    • if 호흡 안정도 분석 사용 안할 경우: osa_stages는 null
  • if state != OPEN
    • if 호흡 안정도 분석 사용 안할 경우: osa_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 일 경우)

sleep_stages

[Sleep Stages]?

수면 단계 리스트

osa_stages

[OSA Stages]?

호흡 안정도 단계 리스트

2.1.3 Sleep Stages

sleep stage (수면 단계)는 -1,0,1,2,3 중 하나의 정수로 표현되며 숫자 하나는 30초 구간의 수면 단계를 나타냅니다. 각 숫자의 의미는 아래 표와 같습니다

  • 계약 조건이 수면 단계 2레벨인 경우에는 0 (wake), 1 (sleep)
numbersleep stage
-1error (invalid audio, analysis error, etc)
0wake
1light sleep
2deep sleep
3REM sleep

2.1.4 OSA Stages

osa stage (호흡 안정 단계)는 -1,0,1 중 하나의 정수로 표현되며 숫자 하나는 30초 구간의 수면 단계를 나타냅니다. 각 숫자의 의미는 아래 표와 같습니다

numberosa stage
-1error (invalid audio, analysis error, etc)
0stable
1unstable

2.1.5 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 값은 null
    • if 호흡 안정도 분석 사용 안할 경우: 해당 기능이 제공되지 않으므로 time_in_stable_breath, time_in_unstable_breath, stable_breath_ratio, unstable_breath_ratio, breathing_pattern, estimated_ahi 값은 null
    • if 모든 stage가 wake인 경우(never slept session): 잠을 자지 않은 것이므로 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, estimated_ahi 모두 null

Field

Type

Description

Example

sleep_efficiency

float (0~1 범위 소수점 둘째자리)

수면 측정 시간 중 실제로 잠든 시간의 비율

0.84

sleep_latency

int (seconds)?

잠들때까지 걸린 시각

1800

sleep_time

String (YYYY-MM-DDThh:mm:ss+-hh:mm)?

수면 측정 시작 후 잠들기 까지 걸린 시간

2022-08-01T00:30:00+09:00

wakeup_latency

int (seconds)?

잠에서 깨어난 후 수면 측정을 종료하기까지 걸린 시간

1800

wake_time

String (YYYY-MM-DDThh:mm:ss+-hh:mm)?

잠에서 깨어난 시각

2022-08-01T07:30:00+09:00

time_in_wake

int (seconds)

수면 도중에 깬 시간

2700

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_bed

int (seconds)

수면 측정 시작 시각부터 수면 측정 종료 시각 까지의 시간

28800

time_in_rem

int (seconds)?

수면 단계가 rem 으로 진행된 총 시간

13500

time_in_light

int (seconds)?

수면 단계가 light 로 진행된 총 시간

5400

time_in_deep

int (seconds)?

수면 단계가 deep로 진행된 총 시간

5400

time_in_stable_breath

int (seconds)?

호흡 안정 구간이었던 총 시간

24300

time_in_unstable_breath

int (seconds)?

호흡 불안정 구간이었던 총 시간

2700

wake_ratio

float (0~1 범위 소수점 둘째자리)?

수면 단계 도중 중간에 깬 시간의 비율

0.1

sleep_ratio

float (0~1 범위 소수점 둘째자리)?

수면 단계 도중 깨지 않고 잔 시간의 비율

0.9

rem_ratio

float (0~1 범위 소수점 둘째자리)?

rem sleep 비율

0.5

light_ratio

float (0~1 범위 소수점 둘째자리)?

수면 단계 도중 light 수면의 비율

0.2

deep_ratio

float (0~1 범위 소수점 둘째자리)?

수면 단계 도중 deep 수면의 비율

0.2

stable_breath_ratio

float (0~1 범위 소수점 둘째자리)?

수면 단계 도중 호흡 안정 구간이었던 시간의 비율

0.9

unstable_breath_ratio

float (0~1 범위 소수점 둘째자리)?

수면 단계 도중 호흡 불안정 구간이었던 시간의 비율

0.1

breathing_pattern

String (VERY_STABLE,STABLE,UNSTABLE, VERY_UNSTABLE)?

호흡 불안정의 단계

VERY_STABLE: 매우 안정
STABLE: 안정
UNSTABLE: 불안정
VERY_UNSTABLE: 매우 불안정

STABLE

estimated_ahi

float (0~1 범위 소수점 둘째자리)?

호흡 불안정 레벨을 판단하기 위한 값

29.7

🚧

의료기기법 안내

서비스 화면 및 마케팅 자료에 수면 무호흡증, 무호흡, 저호흡, AHI 등의 질환 관련 명칭을 사용하면 의료기기법 위반으로 처분될 수 있어, 에이슬립에서는 '호흡 불안정'으로 표시하고 있습니다. 의료기기법 관련한 자세한 내용은 식약처에 문의하십시오.

{
  "detail": "ok",
  "result": {
    "timezone": "UTC",
    "validity": "VALID",
    "session": {
      "id": "20220821093117_hz82a",
      "state": "COMPLETE",
      "start_time": "2022-08-21T09:31:17+00:00",
      "end_time": "2022-08-21T09:56:17+00:00",
      "sleep_stages": [
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1
      ],
      "osa_stages": [
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
      ]
    },
    "stat": {
      "sleep_efficiency": 0.8,
      "sleep_latency": 300,
      "sleep_time": "2022-08-21T09:31:17+00:00",
      "wakeup_latency": 0,
      "wake_time": "2022-08-21T09:31:17+00:00",
      "time_in_wake": 0,
      "time_in_sleep": 1200,
      "time_in_bed": 1500,
      "time_in_sleep_period": 1200,
      "time_in_rem": 0,
      "time_in_light": 1200,
      "time_in_deep": 0,
      "time_in_stable_breath": 1200,
      "time_in_unstable_breath": 0,
      "wake_ratio": 0.0,
      "sleep_ratio": 1.0,
      "rem_ratio": 0.0,
      "light_ratio": 0.0,
      "deep_ratio": 0.0,
      "stable_breath_ratio": 1.0,
      "unstable_breath_ratio": 0.0,
      "breathing_pattern": "VERY_STABLE",
      "estimated_ahi": 0.0
    }
  }
}

2.2 400 Bad Request

  • timezone 이 잘못 들어온 경우
{
	"detail": "The invalid timezone is provided"
}

2.3 404 Not Found

  • session_id에 해당되는 세션을 찾지 못한 경우
{
	"detail": "Unable to find the sleep session of id {session_id}"
}

2.4 422 Unprocessable Entity

  • session_id가 유효하지 않은 경우
{
	"detail": "The format of sleep session id 20230608020315_hz82 is not valid"
}

Updated 13 days ago