Wialon for developers User guide API reference events get

get

To retrieve loaded event data from the session, use the events/get method.

Before calling this method, load events into the session using the events/load method.

If you passed the selector parameter in events/load and received the required events in the selector object of its response, you can skip this method.

Endpoint

Use the events/get method with the following selector formats.

Retrieve events with a type selector

Use the type selector to return events of the specified detector within the period from timeFrom to timeTo.

Copied!
svc=events/get&params={
  "selector": {
    "type": <text>,
    "timeFrom": <uint>,
    "timeTo": <uint>,
    "detalization": <uint>
  }
}

Retrieve events with an expression selector

Use the expr selector to return events selected by an expression. An expression can select loaded detector intervals that meet a condition, explicit time ranges, or a combination of them. The timeFrom and timeTo parameters limit the period from which the events are selected.

Copied!
svc=events/get&params={
  "selector": {
    "expr": <text>,
    "timeFrom": <uint>,
    "timeTo": <uint>,
    "detalization": <uint>
  }
}

For example, trips{s>100} selects trip events where the speed is greater than 100. For expression syntax, see Expression-based intervals.

Retrieve events with an index selector

Use an array of selectors to request a range of events by index. To find the index of a particular event, retrieve the detector events by type, then use the event index in the returned array. Indexing starts at 0.

Copied!
svc=events/get&params={
  "selector": [
    {
      "type": <text>,
      "filter1": <long>,
      "indexFrom": <uint>,
      "indexTo": <uint>,
      "detalization": <uint>
    },
    ...
  ]
}

Parameters

Parameter Applies to Description
selector All selector formats Required. Determines the events to return.
type Type selector, index selector Required. Name of a event detector type loaded into the session. In a type selector, use * to return events from all loaded detectors. In an index selector, specify one detector name.
expr Expression selector Required instead of type. Expression that selects intervals within the specified time period. See below.
timeFrom Type selector, expression selector Required. Beginning of the time period, UNIX time.
timeTo Type selector, expression selector Required. End of the time period, UNIX time.
detalization All selector formats Required. Output flags. See below.
indexFrom Index selector Required. Index of the first requested event.
indexTo Index selector Required. Index of the last requested event.
filter1 Index selector Required. ID used as the key of the event array for the selected detector. See detector-specific IDs in events/check_updates.

The eco_driving event detector isn’t available in Wialon Local.

Flags

Flag Description
0x1 Basic event data: start and end positions, times, and event service flags.
0x2 Detector-specific data.
0x4 Parameters from the message associated with the event.
0x8 Additional detail data when available: track for trips and speedings, and data for instant and differential sensor events.
0x10 Detailed message data for supported detectors.
0x20 Formatted detector values.
0x40 Group expression-selector results by their intersection intervals.
0x80 Summary calculations for expression-selector results.
0x100 Include extended events.

Expression-based intervals

To select intervals within the timeFrom–timeTo period, specify an expression in the "expr":<text> parameter instead of using the "type":<text> parameter. An expression can refer to loaded detector events, explicit time ranges, or a combination of them. You can use the following expression formats:

Operator Description Example
* Selects the complete requested time period. *
{} Used for selecting detector intervals that meet a condition. trips{s>100}
- Used for specifying a custom interval in the start-end format, UNIX-time. 1451953325-1451953525
| Combines intervals or expressions. (1615849200-1615935599|1615935601-1616022000)
& Returns the intersection of two expressions. trips[0]&1451953325-1451953525
~ Excludes intervals from the requested time period. ~1451953325-1451953525
() Groups an expression. (trips[0]|1451953325-1451953525)
[] Selects a detector-specific ID. If no ID is specified, the first loaded ID for the detector is used. sensors[3]

For example, the following expression returns events from the trips detector, which uses the fixed detector-specific ID 0, and from sensors with ID 8 that overlap with one or both of the two custom time intervals:

Copied!
(trips[0]|sensors[8])&(1784550000-1784560000|1784570000-1784580000)

Response

If the request is completed successfully, the response contains the requested detector results. Otherwise, an error code is returned.

Most detectors return event arrays keyed by a detector-specific ID (for example, a sensor ID, driver ID, or eco driving criterion ID). For the IDs used by each detector, see detector-specific IDs. The trips and counters detectors return their data directly, without grouping by ID, and speedings always uses the single ID 0.

Unless noted otherwise, values in the response (sensor, fuel, distance, speed, altitude, and mileage) use the measurement system set when loading events with events/load. Values in seconds, bytes, KiB, km/h, and UNIX time aren’t converted.

0x1 flag

Returns basic event data.

Copied!
"<type_name>": {
  "<detector_specific_id>": [
    {
      "from": {
        "t": <uint>,  /* event interval start time (UNIX time) */
        "y": <double>,/* latitude */
        "x": <double> /* longitude */
      },
      "to": {
        "t": <uint>,  /* event interval end time (UNIX time) */
        "y": <double>,/* latitude */
        "x": <double> /* longitude */
      },
      "m": <uint>,    /* last processed message time */
      "f": <uint>     /* event service flags */
    },
    ...
  ]
}

0x2 flag

Returns detector-specific data. The following examples show an event object; it’s returned in the array keyed by its detector-specific ID.

Sensor detectors

The ignition detector returns the following structure:

Copied!
"ignition": {
  "<sensor_id>": {
    "state": <double>,  /* state: 0 for off, 1 for on */
    "type": 1,          /* sensor type: switcher sensor */
    "hours": <uint>,    /* engine hours for all history, in seconds */
    "switches": <uint>, /* number of switches for all history */
    "value": <double>   /* last sensor value */
  }
}

The sensors detector returns one of the following structures depending on the sensor type:

Copied!
"sensors": {
  "<sensor_id1>": {
    "state": <double>,      /* state: 0 for off, 1 for on */
    "type": 1,              /* sensor type: switcher sensor */
    "hours": <uint>,        /* engine hours for all history, in seconds */
    "switches": <uint>,     /* number of switches for all history */
    "value": <double>       /* last sensor value */
  },
  "<sensor_id2>": {
    "type": 2,              /* sensor type: instant sensor */
    "counter": <uint>,      /* number of consecutive messages in the event */
    "summary": <double>,    /* sum of values in the event */
    "total_counter": <uint>,/* total number of messages in all history */
    "total_summary": <double>,/* total value sum in all history */
    "value": <double>       /* last value; if -348201.3876, the value is unknown */
  },
  "<sensor_id3>": {
    "type": 3,              /* sensor type: differential sensor */
    "counter": <double>,    /* sum of values in the event */
    "total_counter": <double>,/* sum of values in the history */
    "value": <double>       /* last value; if -348201.3876, the value is unknown */
  },
  "<sensor_id4>": {
    "type": 4,              /* sensor type: analog sensor */
    "value": <double>       /* last value; if -348201.3876, the value is unknown */
  }
}

Fuel level detectors

The lls, filling, theft, and fuel_level detectors return the same structure.

Copied!
"lls": {
  "<sensor_id>": {
    "value": <double>,     /* last calculated fuel level */
    "raw_value": <double>, /* last raw sensor value */
    "filled": <double>,    /* fuel volume change: positive for filling, negative for theft */
    "timeDiff": <uint>,    /* time of the message with the maximum volume difference, UNIX time */
    "latDiff": <double>,   /* latitude of that message */
    "lonDiff": <double>    /* longitude of that message */
  }
}

Battery detectors

The battery_level detector returns the processed and raw values of the battery level.

Copied!
"battery_level": {
  "<sensor_id>": {
    "value": <double>,     /* last calculated battery level */
    "raw_value": <double>  /* last raw sensor value */
  }
}

The charge detector returns the following structure:

Copied!
"charge": {
  "<sensor_id>": {
    "charge": <double>,  /* charge volume change */
    "timeDiff": <uint>,  /* time of the message with the maximum charge difference, UNIX time */
    "latDiff": <double>, /* latitude of that message */
    "lonDiff": <double>  /* longitude of that message */
  }
}

The ev detector returns either the battery_level or charge structure, depending on the event.

resource_drivers

The detector groups assignment intervals by driver ID and returns each interval as a separate object. The current state is returned as well when the current event is requested. A current state can have state 1 while the driver is still assigned. In this case, the end time in the 0x1 response is the time of the latest update, not the actual end time of the assignment. It can also have state 0 after the driver was unassigned. In this case, the to object shows the last processed message, not another unassignment; use the event history to get the actual unassignment time.

Copied!
"resource_drivers": {
  "<driver_id>": [
    {
      "state": <uint>,             /* driver state: 0 for unassigned, 1 for assigned */
      "aflags": <uint>,            /* assignment flags */
      "unit_id": <long>,           /* ID of the unit to which the driver is assigned, the unit from which the driver was unassigned, or 0 */
      "propitem_cr_time": <uint>,  /* driver creation time, UNIX time */
      "switched_to": <long>,       /* 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 */
      "real_time_from": <uint>,    /* actual assignment start time, UNIX time */
      "validate_sensor_id": <uint> /* ID of the sensor used to validate the automatic assignment and the unassignment which follows it; 0 when validation isn't used */
    }
  ]
}

Use propitem_cr_time to check whether the driver is the current one or a driver that was deleted and created again with the same ID.

The from.t value in the 0x1 response is the start of the returned event interval. The real_time_from value is the actual start time of the continuous assignment. These values can differ when one assignment is represented by several event intervals, for example when a long assignment is split or a repeated manual assignment starts a new interval. If the assignment isn’t split, real_time_from normally matches from.t.

The event service flags of the base event, including the flags for private positions, silent events, nonsequenced events, and recalculated events, are returned in the f field with the 0x1 flag, not in the detector-specific object.

The detector doesn’t return a separate marker for an assignment marked as false. Such actions are stored separately, and the matching automatic assignment actions are excluded when the events are recalculated.

Manual assignments, unassignments, and ignore actions that affect resource_drivers events are registered, viewed, and deleted using resource/driver_actions_register, resource/driver_actions_list, and resource/driver_actions_cleanup.

The aflags field describes how the assignment started and ended. A completed interval usually contains one flag for its start and one for its end, so the flags are combined.

Flag Description
0x1 The assignment ended because the driver was switched to another unit. The ID of that unit is returned in switched_to.
0x2 The assignment started because 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.

The resource_drivers detector is available for resources only. To load its events, pass the resource ID in the itemId parameter of events/load.

trips

The detector returns its data directly, without grouping by ID.

Copied!
"trips": {
  "state": <uint>,       /* trip state: 0 for parking, 1 for trip, 2 for stop */
  "max_speed": <uint>,   /* maximum speed during the trip */
  "curr_speed": <uint>,  /* current speed */
  "avg_speed": <uint>,   /* average speed based on distance */
  "distance": <uint>,    /* GPS mileage during the trip */
  "odometer": <uint>,    /* total distance for all trips in the history */
  "course": <uint>,      /* course */
  "altitude": <uint>,    /* altitude */
  "pos_flags": <uint>    /* position flags: 1 for a sensor error, 2 when the sensor shows no movement */
}

speedings

The detector uses the single detector-specific ID 0.

Copied!
"speedings": {
  "0": {
    "max_speed": <uint>,  /* maximum speed during the event */
    "last_speed": <uint>, /* speed in the last message of the event */
    "limit": <uint>       /* speed limit used to detect the event */
  }
}

counters

The detector returns its data directly, without grouping by ID.

Copied!
"counters": {
  "engine_hours": <uint>, /* engine hours counter, in seconds */
  "mileage": <uint>,      /* mileage counter */
  "bytes": <uint>         /* GPRS traffic counter, in bytes */
}

eco_driving

The detector groups the data by eco driving criterion ID.

Copied!
"eco_driving": {
  "<eco_driving_id>": [
    {
      "criterion_type": <text>, /* Eco driving criterion type */
      "index": <uint>,          /* criterion index */
      "max_speed": <uint>,      /* maximum speed during the violation, km/h */
      "mark": <double>          /* calculated penalty; can include decimals */
    }
  ]
}

The eco_driving detector isn’t available in Wialon Local.

health_check

The detector groups the data by incident ID.

Copied!
"health_check": {
  "<incident_id>": [
    {
      "incident_type": <text>, /* health check incident type */
      "duration": <uint>,      /* incident duration, in seconds */
      "sensor_id": <uint>      /* unit sensor ID; not included when the incident isn't associated with a sensor */
    }
  ]
}

0x4 flag

Returns available parameters from the message associated with the event. The p object isn’t included when no parameters are available.

Parameter values can be strings, integers, long integers, or floating-point numbers.

Copied!
"<type_name>": {
  "<detector_specific_id>": [
    {
      "p": {              /* message parameters */
        "<parameter_name>": <any>
      }
    }
  ]
}

0x8 flag

Returns additional detail data when available. For trips and speedings, the track field contains an encoded route in Google notation. For instant and differential sensor events, the data field contains additional event data.

Copied!
{
  "trips": {
    "0": [
      {
        "track": "wspnGgvcv@??oey@kwl@~dtBkeRwjzF??~ja@_qo]??g~g^????????????~bV???????"
      }
    ]
  }
}

0x10 flag

Returns detailed messages for detectors that support them. The msgs array is returned when detailed message data is available.

For instant and differential sensors (types 2 and 3), except fuel level sensors:

Copied!
"sensors": {
  "<sensor_id>": {
    "msgs": [
      {
        "tm": <uint>,  /* message time (UNIX time) */
        "v": <double>  /* value */
      },
      ...
    ]
  },
  ...
}

For fuel level sensors:

Copied!
"lls": {
  "<sensor_id>": {
    "msgs": [
      {
        "tm": <uint>,  /* message time (UNIX time) */
        "v": <double>, /* value */
        "rv": <double> /* raw value */
      },
      ...
    ]
  }
},
...

For trips, the msgs array contains detailed messages from the event interval:

Copied!
"trips": {
  "msgs": [
    {
      "tm": <uint>,    /* message time (UNIX time) */
      "x": <double>,   /* longitude */
      "y": <double>,   /* latitude */
      "c": <uint>,     /* course */
      "z": <int>,      /* altitude */
      "s": <uint>,     /* speed */
      "m": <double>,   /* mileage */
      "pf": <uint>     /* position flags; included when not 0 */
    },
    ...
  ]
}

For private positions, x, y, and c are returned as 0.

For driver assignment events, the following response is returned:

Copied!
"resource_drivers": {
  "<driver_id>": [
    {
      "msgs": [
        {
          "tm": <uint>  /* repeat assignment time, UNIX time */
        },
        ...
      ]
    }
  ]
}

0x20 flag

Returns formatted values. The subsections below describe the format object of each detector.

The eco_driving, health_check, and resource_drivers detectors don’t return a format object for this flag.

Sensor detectors

The ignition detector returns the following format object:

Copied!
"ignition": {
  "<sensor_id>": {
    "format": {
      "value": <text>, /* formatted value, usually "On"/"Off" */
      "custom_value": <text> /* custom formatted value */
    }
  }
}

The sensors detector returns the following format object:

Copied!
"sensors": {
  "<sensor_id>": {
    "format": {
      "value": <text>, /* formatted value; depends on the sensor type and format */
      "custom_value": <text> /* custom formatted value */
    }
  }
}

Fuel level detectors

The lls, filling, theft, and fuel_level detectors return the following format object:

Copied!
"lls": {
  "<sensor_id>": {
    "format": {
      "value": <text>,   /* formatted value; depends on the sensor type and format */
      "raw_value": <text>,/* formatted raw value */
      "filled": <text>,  /* fuel filled */
      "theft": <text>,   /* fuel drained */
      "custom_value": <text> /* custom formatted value */
    }
  }
}

Battery detectors

The battery_level detector returns the following format object:

Copied!
"battery_level": {
  "<sensor_id>": {
    "format": {
      "value": <text>,        /* formatted battery level */
      "raw_value": <text>,    /* formatted raw sensor value */
      "custom_value": <text>  /* custom sensor value corresponding to value */
    }
  }
}

The charge detector returns the following format object:

Copied!
"charge": {
  "<sensor_id>": {
    "format": {
      "charge": <text>  /* formatted charge volume */
    }
  }
}

The ev detector returns either the battery_level or charge format object, depending on the event.

For battery level sensors, the value and raw_value fields of the format object take the show_as_percentage key of the sensor configuration into account. If the key is set to 1 and battery_capacity is greater than 0, the fields return the battery level as a percentage of the capacity, with the percent sign included. Otherwise, they return the level in kWh.

The percentage applies to the formatted values of the 0x20 flag only. The charge field, the numeric values returned with the 0x2 flag, and the data in reports and notifications are always in kWh.

trips

The detector returns the following format object:

Copied!
"trips": {
  "format": {
    "distance": <text>,   /* formatted trip distance */
    "avg_speed": <text>   /* formatted average trip speed */
  }
}

speedings

The detector returns the following format object:

Copied!
"speedings": {
  "0": {
    "format": {
      "last_speed": <text>, /* formatted speed in the last message */
      "limit": <text>,      /* formatted speed limit */
      "max_speed": <text>   /* formatted maximum speed during the event */
    }
  }
}

counters

The detector returns the following format object:

Copied!
"counters": {
  "format": {
    "engine_hours": <text | uint>,  /* formatted value of the engine hours counter */
    "mileage": <text>,       /* formatted value of the mileage counter */
    "bytes": <uint>          /* formatted value of the GPRS traffic counter, in KiB */
  }
}

0x40 flag

For expression selectors, returns an array grouped by the intervals produced when evaluating the expression. See Expression-based intervals.

Copied!
[
  {
    "tf": <uint>,  /* expression interval start (UNIX time) */
    "tt": <uint>,  /* expression interval end (UNIX time) */
    "d": {          /* detector results for the expression interval */
      "<type_name>": {
        "<sensor_id>": [
          { }  
        ]
      }
    }
  }
]

0x80 flag

For expression selectors, returns aggregate values calculated from the events selected by the expression, for each detector and detector-specific ID. Without the 0x40 flag, the results are returned in the top-level summary object. When 0x40 is also specified, each interval’s d object contains its own summary object. This flag is ignored for type and index selectors.

The summary fields depend on the detector:

  • trips and speedings: number and total duration of events, number of messages, and speed statistics; trips also returns total distance.
  • Instant and differential sensors: number and total value of events, or initial and final values.
  • lls, filling, theft, and fuel_level: total fillings and thefts, initial and final fuel levels, and consumption.
  • battery_level, charge, and ev: initial and final levels, consumption, or total charge, depending on the detector.
  • counters: initial and final engine hours, mileage, and GPRS traffic.
  • Other detectors, including ignition, health_check, eco_driving, and switcher or analog sensors: number and total duration of events.

For example, a speedings summary can contain:

Copied!
{
  "summary": {
    "speedings": {
      "0": {
        "countIvals": <uint>,    /* number of speeding events */
        "sumSeconds": <uint>,    /* total event duration, in seconds */
        "countMessages": <uint>, /* number of messages in the events */
        "avgSpeed": <uint>,      /* average speed */
        "maxSpeed": <uint>,      /* maximum speed */
        "minSpeed": <uint>       /* minimum speed */
      }
    }
  }
}

Error codes

Error code Description
1 Invalid or obsolete request SID.
4 Parameter validation error.
7 The event service is unavailable.

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