위치 데이터 조회

배송 중 디바이스가 기록한 시계열 위치 데이터(위도/경도)를 조회합니다. 응답에는 같은 기간 내 가장 최근 배터리 측정값이 함께 포함되어, 지도에 배송 경로를 그리면서 디바이스가 정상 동작 중인지(전력 잔량)도 동시에 확인할 수 있습니다.

제약 사항

• 조회 범위(startAt ~ endAt)는 최대 5일을 넘을 수 없습니다.
• startAt은 endAt보다 작거나 같아야 합니다.
• 일부 디바이스 모델은 위치를 연속적으로 기록하지 않으므로, 해당 디바이스에서는 items가 드물게 반환될 수 있습니다.
• 배터리 정보는 best-effort 입니다 — 조회 기간 내 배터리 측정값이 없으면 battery는 null로 반환됩니다.
• 요청한 endAt이 디바이스 등록 시점 이전이면 T0118로 거부됩니다.

Request

---

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

Path Variable

Name	Description
serial	디바이스 시리얼

Query Parameters

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

Example Request

GET /ext/v2/devices/{serial}/locations?startAt=1738655274000&endAt=1738655274000
Authorization: Bearer token

Response

---

Response Body

Name	Type	Not-null	Description
items	Array	true	위치 데이터 목록
time	Unix timestamp(ms)	true	측정 시간
latitude	Number	true	위도
longitude	Number	true	경도
battery	Object	false	최신 배터리 정보 (없으면 null)
battery.time	Unix timestamp(ms)	false	배터리 기록 시간
battery.percent	Number	false	배터리 잔량 (0–100)

Example Response

HTTP/1.1 200 OK

{
  "items": [
    {
      "latitude": 37.253781,
      "longitude": 127.103773,
      "time": 1719817200000
    },
    {
      "latitude": 37.253781,
      "longitude": 127.103773,
      "time": 1719811800000
    }
  ],
  "battery": {
    "time": 1719817200000,
    "percent": 82
  }
}

조회 범위 내에 배터리 측정 데이터가 없으면 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"
}