Wialon for developers User guide API reference events get_last

get_last

To retrieve the current state of an active event or the last known state of a completed event, use the events/get_last method.

Unlike events/get, this method doesn’t require events to be loaded into the session and doesn’t return event history. Unlike events/check_updates, it doesn’t require you to add the item to the session with events/update_items.

Endpoint

Copied!
svc=events/get_last&params={
  "itemId": <long>,
  "type": <text>,
  "filter1": <long>,
  "filter2": <text>,
  "detalization": <uint>,
  "measure": <uint>,
  "lang": <text>
}

Parameters

The request must contain the itemId parameter. All other parameters are optional.

Parameter Description
itemId Unit ID or resource ID. The resource ID is required for the resource_drivers detector (driver-assignment events).
type Names of the event detectors to query. Specify one detector, several detectors separated by commas (for example, trips,sensors), or use the wildcards * and ? (for example, sens*). The default value is *, which returns the state of all available detectors. You can use a detector key from that response as the value in a following request.
filter1 Detector filter. Use it only when you request one detector in the type parameter. For sensor-based detectors (sensors, lls, ev, filling, theft, fuel_level, charge, battery_level), specify a sensor ID, or 0 for all sensors of this type. For resource_drivers, specify a driver ID, or 0 for all drivers. For trips, counters, speedings, health_check, and eco_driving, use 0. The default value is 0.
filter2 Additional detector filter by name. It works only for detectors that register events for a specific sensor or driver: sensor-based detectors (filter by the sensor name) and resource_drivers (filter by the driver name). For trips, counters, speedings, health_check, and eco_driving, the value is ignored. Specify one name, or several names separated by commas, and use the wildcards * and ? if needed, for example, Fuel*,Tank?. This filter is applied only when filter1 is 0. The default value is an empty string ("").
detalization Output flags. Must be specified in decimal format. The default value is 7 (0x7), which returns basic event data, detector-specific data, and parameters of the message associated with the event. See below.
measure Measurement system: 0 for metric (SI), 1 for US, 2 for imperial, 3 for metric with gallons. If the parameter isn’t specified, the value set for the current session is used (the two lowest bits of the flags parameter of render/set_locale). If no value is set in the session, the value 0 is used.
lang Language (2-character code, for example, en or es). If the parameter isn’t specified, the value set for the current session is used (see the language parameter of render/set_locale). If no value is set in the session, the value en is used.

Flags

Flag Description
0x1 Basic event data: times, coordinates, and event service flags.
0x2 Detector-specific data.
0x4 Parameters from the message associated with the event.
0x8 Additional event data when supported by the detector.
0x10 Detailed message data when supported by the detector.
0x20 Formatted detector values.
0x100 Additional events registered by the fuel_level and battery_level detectors with the values collected since the previous event. Not required for most integrations.

Response

If the request is completed successfully, the response contains an object keyed by detector type. Otherwise, an error code is returned.

The data structure inside each key depends on the detector and the requested flags.

Common structure

With the 0x1 flag, the trips and counters detectors return their data directly, in the following structure. Other detectors group event objects by a detector-specific ID, as shown in the examples.

Copied!
{
  "<detector_type>": {
    "from": {
      "t": <uint>,
      "y": <double>,
      "x": <double>
    },
    "to": {
      "t": <uint>,
      "y": <double>,
      "x": <double>
    },
    "m": <uint>,
    "f": <uint>
  }
}
Field Description
from Event start data: t for UNIX time, y for latitude, and x for longitude.
to Last processed message data: t for UNIX time, y for latitude, and x for longitude.
m Last processed message time, UNIX time.
f Event service flags.

For a private position, the x and y values are returned as 0.

The other flags return the same data as the corresponding flags of events/check_updates: detector-specific data (0x2), parameters of the message associated with the event (0x4), additional detail data (0x8), detailed message data (0x10), and formatted values (0x20). For the resource_drivers detector, the returned fields are described in the example below.

Error codes

Error code Description
1 Invalid or obsolete request SID.
4 Parameter validation error.
5 Events are disabled.
7 The event service is unavailable, the item can’t be retrieved, or the user doesn’t have the View object and its basic properties right to the specified unit or resource.

Examples

The following examples show how to retrieve event states for different use cases.

Retrieving all detector states for a unit

To retrieve the state of all available detectors for a unit, specify only the unit ID:

Copied!
svc=events/get_last&params={
  "itemId": <unit_id>
}

The response is an object keyed by each available detector type:

Copied!
{
  "<detector_type>": {
    "...": "..."
  }
}

Retrieving states of several detectors

To retrieve the states of several detectors at once, list them in the type parameter separated by commas. In the following request, the states of the trips and sensors detectors are requested, and the sensors are filtered by name with filter2:

Copied!
svc=events/get_last&params={
  "itemId": <unit_id>,
  "type": "trips,sensors",
  "filter2": "Temperature 1,Temperature 2",
  "detalization": 39
}

The response contains one object for each requested detector. The sensors detector groups its data by sensor ID, and the trips detector returns its data directly:

Copied!
{
  "trips": { "...": "..." },
  "sensors": {
    "<sensor_id>": { "...": "..." }
  }
}

Retrieving the current fuel level state

To retrieve the fuel level state for all fuel level sensors of a unit, specify the unit ID and the fuel_level detector. Use detalization 39 (0x27) to include basic event data, detector-specific data, message parameters, and formatted values:

Copied!
svc=events/get_last&params={
  "itemId": <unit_id>,
  "type": "fuel_level",
  "filter1": 0,
  "filter2": "",
  "detalization": 39
}

The response is grouped by sensor ID. With detalization 39 (0x27), it can contain the following fields:

Copied!
{
  "fuel_level": {
    "<sensor_id>": {
      "from": {
        "t": <uint>,
        "y": <double>,
        "x": <double>
      },
      "to": {
        "t": <uint>,
        "y": <double>,
        "x": <double>
      },
      "m": <uint>,
      "f": <uint>,
      "value": <double>,
      "raw_value": <double>,
      "filled": <double>,
      "timeDiff": <uint>,
      "latDiff": <double>,
      "lonDiff": <double>,
      "format": {
        "value": <text>,
        "raw_value": <text>,
        "filled": <text>,
        "theft": <text>,
        "custom_value": <text>
      }
    }
  }
}

Retrieving the current battery level state

To retrieve the current battery level state of an electric vehicle (EV), specify the unit ID and the ev detector. Use detalization 39 (0x27) to include basic event data, detector-specific data, message parameters, and formatted values:

Copied!
svc=events/get_last&params={
  "itemId": <unit_id>,
  "type": "ev",
  "filter1": 0,
  "filter2": "",
  "detalization": 39
}

The response is grouped by sensor ID. For the current state, the ev detector returns the battery level, and the response can contain the following fields:

Copied!
{
  "ev": {
    "<sensor_id>": {
      "from": {
        "t": <uint>,
        "y": <double>,
        "x": <double>
      },
      "to": {
        "t": <uint>,
        "y": <double>,
        "x": <double>
      },
      "m": <uint>,
      "f": <uint>,
      "value": <double>,
      "raw_value": <double>,
      "format": {
        "value": <text>,
        "raw_value": <text>,
        "custom_value": <text>
      }
    }
  }
}

The from, to, m, and f fields are described in the common structure. The value field contains the calculated battery level, and raw_value contains the raw sensor value.

The value and raw_value fields inside the format object return the battery level as a percentage of battery_capacity when the show_as_percentage key is set to 1 in the sensor configuration and battery_capacity is greater than 0. Otherwise, they return the level in kWh. The value and raw_value fields outside the format object always return the level in kWh.

The ev detector is a combined EV battery detector. It returns battery level and charge events in historical event responses. In events/get_last, its current-state response uses the battery-level fields shown above. To request only battery level events, use battery_level. To retrieve historical charge events, use charge with events/load and events/get.

Retrieving the current driver-assignment state

To retrieve the current state of driver assignments, specify the resource ID and the resource_drivers detector. Set filter1 to a driver ID to get the state of one driver, or 0 for all drivers. The detalization value 7 (0x7) returns basic event data, detector-specific data, and parameters from the message associated with the event.

Copied!
svc=events/get_last&params={
  "itemId": <resource_id>,
  "type": "resource_drivers",
  "filter1": 0,
  "filter2": "",
  "detalization": 7
}

The response is grouped by driver ID. Each driver ID has one object that describes the current state of that driver.

Copied!
{
  "resource_drivers": {
    "<driver_id>": {
      "from": {
        "t": <uint>,
        "y": <double>,
        "x": <double>
      },
      "to": {
        "t": <uint>,
        "y": <double>,
        "x": <double>
      },
      "m": <uint>,
      "f": <uint>,
      "state": <uint>,
      "aflags": <uint>,
      "unit_id": <long>,
      "propitem_cr_time": <uint>,
      "real_time_from": <uint>,
      "validate_sensor_id": <uint>,
      "switched_to": <long>
    }
  }
}

The from, to, m, and f fields are described in the common structure. The detector also returns the following fields:

Field Description
state Current driver state: 0 for unassigned or 1 for assigned.
aflags Assignment flags (see below).
unit_id For state 1, ID of the unit to which the driver is assigned. For state 0, ID of the unit from which the driver was unassigned, or 0.
propitem_cr_time Driver creation time, UNIX time. Use it to check whether the driver is the current one or a driver that was deleted and created again with the same ID.
real_time_from Actual assignment start time, UNIX time. If a long assignment was split into several events, this is the start time of the earliest event in the chain.
validate_sensor_id ID of the sensor used to validate the automatic assignment and the unassignment which follows it. The value is 0 when validation isn’t used.
switched_to ID of the unit to which the driver was switched. Returned only when the driver was assigned to another unit without being unassigned from this one.

The aflags field can contain the following flags. The same flags are used in the completed events returned by events/get, so a current state usually contains only the flags that describe how the assignment started.

Flag Description
0x1 The assignment ended when the driver was switched to another unit. The ID of that unit is returned in switched_to.
0x2 The assignment started when the driver was switched from another unit. This ended the previous assignment on that unit.
0x4 The assignment was started manually.
0x8 The assignment was ended manually.
0x10 The assignment starts with state 0 because another exclusive driver was assigned to the same unit.
0x20 The assignment ended because another exclusive driver was assigned to the same unit.

For state 0, the to object doesn’t show the time and place of the unassignment. It shows the last processed message. The unassignment time is the end time of the completed event in the event history, which you can retrieve with events/get.

To change the assignment state manually, use resource/driver_actions_register. To view or delete registered manual actions, use resource/driver_actions_list or resource/driver_actions_cleanup.

If you find a mistake in the text, please select it and press Ctrl+Enter.