Wialon API: Get a Unit's Last Position and Message

“How do I get a unit’s last update time?” was the most-viewed developer question on the Wialon forum, and it ran to ninety replies before it settled. The reason it was hard is not that the API hides the answer. It is that Wialon distinguishes between the last known position and the last known message, most integrations want one while asking for the other, and the two only agree when every message a device sends happens to carry a GPS fix. This page covers the unit data-flag table, how to fetch units and their state in one call, and how to watch for changes instead of polling for them.

Select what comes back with data flags

Requests that return units accept a flags value, and the response contains only the blocks those flags select. The complete table, from Data format: Units:

The reference states one thing explicitly that costs more time than anything else in the table: all flags are only used in DEC format. The documentation writes them in hexadecimal and the request takes decimal, so 0x400 goes in as 1024 and a request built by copying the hex string silently selects the wrong blocks rather than failing.

The all-flags value exists and is a trap on any real account, because it returns every block of every unit — sensors, counters, maintenance, command lists, custom fields — for every item in the result set. Requesting 1025 rather than everything is the difference between a response you can parse and one you wait for.

Decide whether you need the last position or the last message

Flag 1024 returns two things, and understanding why they differ is the whole point of this page:

{
  "pos": {
    "t": 1754870400,
    "y": 52.2297,
    "x": 21.0122,
    "z": 113,
    "s": 0,
    "c": 180,
    "sc": 9
  },
  "lmsg": { }
}

The pos object is the last known position: t is time in UTC, y latitude, x longitude, z altitude, s speed, c course, and sc satellite count. The lmsg object is the last known message, and its shape depends on the message type. These two diverge whenever a device reports something without a GPS fix, which happens constantly in normal operation — an ignition event, a sensor reading, a driver code or a keepalive updates lmsg and leaves pos exactly where it was.

That divergence decides which field answers your question. If you are asking when the platform last heard from a unit, which is the liveness question most monitoring integrations actually care about, read lmsg. If you are asking where a unit is and when it was there, read pos.t. Using pos.t as a heartbeat marks a parked vehicle as offline while it is still reporting normally, and using lmsg as a position timestamp puts a vehicle on the map at a location it left hours ago. Both mistakes produce a system that looks correct in testing and disagrees with reality in the field.

Two related flags are worth knowing before you build a status view. Flag 2097152 returns a connection state as a boolean, which answers whether a device is connected right now without inferring it from timestamps at all. Flag 4194304 returns pos alone without lmsg, and is cheaper when coordinates are all you need.

Fetch every unit in one call rather than one call per unit

The core/search_items command returns a set of items with the flags you ask for, which is how you retrieve every unit and its last position in a single request:

svc=core/search_items&params={
  "spec":{
    "itemsType":"avl_unit",
    "propName":"sys_name",
    "propValueMask":"*",
    "sortType":"sys_name"
  },
  "force":1,
  "flags":1025,
  "from":0,
  "to":0
}

The value 1025 is 1 combined with 1024 — base properties plus last message and position, in decimal. The parameters, from the search reference:

Two details from the reference shape how this behaves in practice. The propName, propType and propValueMask fields are evaluated in threes, so a multi-criteria search must supply the same number of entries in each or the criteria misalign. And force set to 0 is a genuine cache rather than a hint, which is convenient while developing and actively misleading when you are polling to detect changes. Where the choice exists, search by sys_unique_id rather than by sys_name, because the IMEI is stable while the name is whatever the customer last typed into the interface.

Subscribe to state changes instead of polling for them

Polling core/search_items on a timer is the obvious approach and the wrong one at any scale, because it re-reads every unit on the account to discover the few that changed, against a session that permits ten simultaneous API requests in total. Wialon’s own mechanism is to subscribe: core/update_data_flags adds items to the session with a set of flags, and subsequent changes arrive through avl_evts.

svc=core/update_data_flags&params={
  "spec":[{
    "type":"type",
    "data":"avl_unit",
    "flags":1025,
    "mode":0,
    "max_items":1000
  }]
}

Mode 2 carries a consequence worth remembering, documented in the item events reference: removing the base flag removes the item from the session entirely rather than merely trimming what is reported for it. The polling ceiling on the receiving side is published as no more than 10 avl_evts requests during 10 seconds, so an event loop running once per second is already at the limit before anything else on the session competes with it.

The question that prompted this page, “How to get Unit Last update date and time”, drew 66,629 views across 90 replies on the Wialon forum before the board was taken offline. Every thread URL now redirects to the help.wialon.com root, and captured pages survive for roughly 61% of threads in the Wayback Machine.

Subscribing keeps you current. It does not keep you covered: Wialon Hosting removes unit history past 400 days by default, so a question asked next year about last year has nothing to read. Mirroring the data somewhere you control is a separate decision from how you read it live, and FleetSQL is our managed answer to it.

• Read lmsg for liveness and pos.t for location, and never substitute one for the other.
• Write flag values in decimal, because the documentation prints hex and the API rejects it.
• Subscribe through core/update_data_flags rather than polling search, and keep the event loop inside 10 requests per 10 seconds.