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.

Endpoint

Copied!

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

The type selector returns events of the specified detector within the timeFrom–timeTo period. To select intervals based on an expression, replace type with expr; timeFrom and timeTo still limit the period in which the expression is evaluated. To request event records by index, use an array of selectors:

Copied!

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

Parameters

Parameter	Description
`selector`	Selector object for a time or expression query, or an array of index selectors.
`type`	A loaded event detector name, or `*` for all loaded detectors. Use it to retrieve detector events within the specified time period. `eco_driving` is supported. Required in a type or index selector.
`expr`	Expression that selects intervals within the specified time period. Required instead of `type`. See below.
`timeFrom`	Beginning of the time period, UNIX time. Required in a type or expression selector.
`timeTo`	End of the time period, UNIX time. Required in a type or expression selector.
`detalization`	Output flags. Required in every selector (see below).
`indexFrom`	Index of the first requested event. Required in an index selector.
`indexTo`	Index of the last requested event. Required in an index selector.
`filter1`	Detector-specific ID. Required in an index selector. Use an ID returned for the selected detector in the events loaded into the session. For sensor-based detectors, this is a sensor ID; for `eco_driving`, it is the Eco driving criterion ID.

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 supported detectors.
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
`{}`	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`
`\|`	Used as a separator when specifying multiple custom intervals.	`(1615849200-1615935599\|1615935601-1616022000)`
`[]`	Sensor ID. If no ID is specified, the first sensor is used.	`sensors[3]`

Response

If the request is completed successfully, the response contains the requested detector results. Each detector contains event arrays keyed by a detector-specific ID. For sensor-based detectors, this is the sensor ID; for eco_driving, it is the Eco driving criterion ID; detector-level data uses ID 0. Otherwise, an error code is returned.

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>,  /* time (UNIX time) */
        "y": <double>,/* latitude */
        "x": <double> /* longitude */
      },
      "to": {
        "t": <uint>,  /* 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 is returned in the array keyed by its detector-specific ID.

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 */
  }
}

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 */
  }
}

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

Copied!

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

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.

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 */
}

Copied!

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

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 */
    }
  ]
}

Copied!

"health_check": {
  "<detector_specific_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 */
    }
  ]
}

Copied!

"speedings": {
  "max_speed": <uint>,  /* maximum speed during the event */
  "last_speed": <uint>, /* speed in the last message of the event */
  "limit": <uint>       /* speed limit */
}

0x4 flag

Returns available parameters from the message associated with the event. The p object is not 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 */
        "test": 2,
        "foo": "bar",
        "trips": 1
      }
    }
  ]
}

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 sensors with type=2 and type=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, each message object contains tm (time), x (longitude), y (latitude), c (course), z (altitude), s (speed), and m (mileage). The pf position-flags field is included when not 0. For private positions, x, y, and c are returned as 0.

0x20 flag

Returns formatted values.

Copied!

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

Copied!

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

Copied!

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

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 theft */
      "custom_value": <text> /* custom formatted value */
    }
  }
}

The filling, theft, and fuel_level detectors return the same format object as lls.

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 */
    }
  }
}

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.

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 */
    }
  }
}

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 intersection interval.

Copied!

[
  {
    "tf": <uint>,  /* intersection interval start (UNIX time) */
    "tt": <uint>,  /* intersection interval end (UNIX time) */
    "d": {
      "<type_name>": {
        "<sensor_id>": [
          { }  
        ]
      }
    }
  }
]

0x80 flag

Returns supported detector summaries in the top-level summary object.

Copied!

{
  "<type_name>": {
    "<detector_specific_id>": [
      { }
    ]
  },
  "summary": {
    "<type_name>": {
      "<detector_specific_id>": {
        /* detector-specific summary data */
      }
    }
  }
}

Error codes

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

get

Endpoint

Parameters

Flags

Expression-based intervals

Response

0x1 flag

0x2 flag

0x4 flag

0x8 flag

0x10 flag

0x20 flag

0x40 flag

0x80 flag

Error codes

Report a mistake