측정 데이터 조회

배송 중 디바이스가 기록한 시계열 측정 데이터(온도, 습도, 가속도, 기울기, 조도 등)를 조회합니다. measurementTypes 쿼리 파라미터로 필요한 측정 타입만 선택할 수 있습니다. 응답에는 같은 기간 내 가장 최근 배터리 측정값이 함께 포함되어, 한 번의 호출로 센서 측정값과 디바이스 전력 상태를 동시에 확인할 수 있습니다.

비실시간 디바이스의 경우, 배송이 완료된 후(디바이스가 회수되어 데이터가 업로드된 이후)에만 측정 데이터를 조회할 수 있습니다.

제약 사항

• 조회 범위(startAt ~ endAt)는 최대 5일을 넘을 수 없습니다.
• startAt은 endAt보다 작거나 같아야 합니다.
• 배터리 정보는 best-effort 입니다 — 조회 기간 내 배터리 측정값이 없으면 battery는 null로 반환됩니다.
• 요청한 endAt이 디바이스 등록 시점 이전이면 T0118로 거부됩니다.

Request

---

GET https://openapi.willog.io/ext/v2/devices/{serial}/measurements

Path Variable

Name	Description
serial	디바이스 시리얼

Query Parameters

Name	Type	Required	Description
startAt	Unix timestamp(ms)	true	조회 범위 시작 시간
endAt	Unix timestamp(ms)	true	조회 범위 마지막 시간
customerCode	String	false	고객사 코드
measurementTypes	Array	true	조회할 측정 타입

Measurement Types

Name	Description
TEMPERATURE	온도
HUMIDITY	습도
ACC	가속도
ACCX	가속도 X축
ACCY	가속도 Y축
ACCZ	가속도 Z축
TILTX	기울기 X축
TILTY	기울기 Y축
TILTZ	기울기 Z축
EXP	조도(Lux)

Example Request

GET /ext/v2/devices/{serial}/measurements?startAt=1738655274000&endAt=1738655274000&measurementTypes=TEMPERATURE&measurementTypes=HUMIDITY
Authorization: Bearer token

Response

---

Response Body

Name	Type	Not-null	Description
items	Array	true	측정 데이터 목록
time	Unix timestamp(ms)	true	측정 시간
temperature	Number	false	온도
humidity	Number	false	습도
acc	Number	false	가속도
accx	Number	false	가속도 X
accy	Number	false	가속도 Y
accz	Number	false	가속도 Z
tiltx	Number	false	기울기 X
tilty	Number	false	기울기 Y
tiltz	Number	false	기울기 Z
battery	Object	false	최신 배터리 정보 (없으면 null)
battery.time	Unix timestamp(ms)	false	배터리 기록 시간
battery.percent	Number	false	배터리 잔량 (0–100)

Example Response

HTTP/1.1 200 OK

{
  "items": [
    {
      "time": 1738655274000,
      "temperature": 36.5,
      "humidity": 56
    }
  ],
  "battery": {
    "time": 1738655274000,
    "percent": 81
  }
}

조회 범위 내에 배터리 측정 데이터가 없으면 battery는 null 입니다:

{
  "items": [ ... ],
  "battery": null
}

Error Responses

- customerCode에 대한 권한 없음

HTTP/1.1 400 Bad Request

{
  "code": "A0016"
}

- 등록되지 않은 Device

HTTP/1.1 400 Bad Request

{
  "code": "T0007"
}

- 조회 기간에 디바이스가 존재하지 않음

HTTP/1.1 400 Bad Request

{
  "code": "T0118"
}

- 측정 데이터 조회 범위 초과

HTTP/1.1 400 Bad Request

{
  "code": "E0004"
}

- 시작일이 종료일보다 큼

HTTP/1.1 400 Bad Request

{
  "code": "E0022"
}