Retrieve Location Data

This endpoint returns the time-series location data (latitude / longitude) recorded by a device during shipment, along with the most recent battery reading from the same period. Use it to plot a shipment route on a map and to verify the device is still operational while in transit.

Constraints

• The query window (startAt → endAt) must not exceed 5 days.
• startAt must be less than or equal to endAt.
• Some device models do not record location continuously, so expect sparse items for those devices.
• Battery information is best-effort — if no battery measurement was recorded in the requested window, battery is returned as null.
• If the requested endAt is before the device was registered, the request is rejected with T0118.

Request

---

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

Path Variable

Name	Description
serial	Device serial code

Query Parameters

Name	Type	Required	Description
startAt	Unix timestamp(ms)	true	Start time for data retrieval
endAt	Unix timestamp(ms)	true	End time for data retrieval
customerCode	String	false	Customer code

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	List of location records
time	Unix timestamp(ms)	true	Measurement time
latitude	Number	false	Latitude value
longitude	Number	false	Longitude value
battery	Object	false	Latest battery info (null if unknown)
battery.time	Unix timestamp(ms)	false	Time the battery level was recorded
battery.percent	Number	false	Battery level (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
  }
}

When the device has no recorded battery measurement in the requested range, battery is null:

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

Error Responses

- Unauthorized Access to Customer Data

HTTP/1.1 400 Bad Request

{
  "code": "A0016"
}

- Unregistered Device

HTTP/1.1 400 Bad Request

{
  "code": "T0007"
}

- Device Did Not Exist in Requested Date Range

HTTP/1.1 400 Bad Request

{
  "code": "T0118"
}

- Invalid Date Range

HTTP/1.1 400 Bad Request

{
  "code": "E0004"
}

- From Date Greater Than To Date

HTTP/1.1 400 Bad Request

{
  "code": "E0022"
}