Wialon help center

Wialon ecosystem

Wialon Hosting

Web version Mobile version What's new

Wialon Local

Web version Mobile version What's new

Wialon Platform

User guide Quick start What's new

Wialon for developers

API documentation Expert articles What's new

More solutions by Wialon

Other sources of information

Wialon for developers User guide API reference events check_updates

check_updates

To get event updates for all units added to the session, use the events/check_updates method.

Before calling this method, add units to the session using the events/update_units method.

Endpoint

Copied!
svc=events/check_updates&params={
    "lang": <text>,
    "measure": <uint>,
    "detalization": <uint>
}

Parameters

All parameters are optional.

Parameter Description Default value
lang Language (2-character code). en
measure Measurement system:

  • 0 for SI;
  • 1 for US;
  • 2 for imperial.
 0
detalization Output flags (see below). Must be specified in decimal format. 7

Output 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 Extended detector detail data for supported detectors.
0x10 Detailed message data for supported detectors.
0x20 Formatted detector values.

Sensor type

Type value Description Event registration
1 Switcher sensors:

  • engine operation;
  • digital;
  • engine efficiency;
  • private mode;
  • real-time motion sensor;
  • alarm trigger;
  • counter (switch to ON/OFF).
 Events are active while the value is non-zero.
2 Instant sensors:

  • odometer;
  • relative engine hours;
  • instant fuel consumption;
  • counter (instant).
 Events are active while the value is non-zero.
3 Differential sensors:

  • mileage;
  • engine hours;
  • impulse fuel consumption;
  • absolute fuel consumption;
  • counter (differential, differential with overflow).
 Events are active while the calculated counter is non-zero.
4 Analog sensors:

  • temperature;
  • engine RPM;
  • voltage;
  • weight;
  • accelerometer;
  • fuel level impulse sensor;
  • temperature coefficient;
  • custom sensor;
  • driver;
  • trailer;
  • tag (passenger).
 Provides the current sensor state only; the sensors detector doesn’t register interval events for this type.

Response

The response is grouped by unit ID. For each unit, the response contains an array of detector objects:

Copied!
{
    "<unit_id_1>": [
        { "<detector_name>": { ... } },
        { "<detector_name>": { ... } },
        ...
    ],
    "<unit_id_2>": [ ... ]
}

Each call returns event updates since the previous events/check_updates call in the same session. The method returns an empty object when there are no new updates.

Unless noted otherwise, values in the response (sensor, fuel, distance, speed, altitude, and mileage) use the measurement system from the measure parameter. Values in seconds, bytes, KiB, km/h, and UNIX time aren’t converted.

The structure of each detector object depends on the enabled output flags. Combine flags in the detalization parameter as needed. The sections below describe each flag separately.

0x1 flag

Returns basic data for each event. The response structure depends on the detector. The ignition, sensors, lls, filling, theft, fuel_level, ev, charge, and battery_level detectors group their data by sensor ID. The eco_driving detector groups its data by eco driving ID, health_check by incident ID, and speedings uses ID 0. Detectors such as trips and counters return their data directly, without grouping.

For detectors that group data by ID, <detector_specific_id> is a detector-specific ID used as the object key. For ignition, sensors, lls, filling, theft, fuel_level, ev, charge, and battery_level, it is the unit sensor ID. For eco_driving, it is the eco driving criterion ID. For health_check, it identifies an incident condition.

The eco_driving detector isn’t available in Wialon Local.

For detectors that group data by ID, the structure is as follows:

Copied!
{
    "<detector_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>,       /* time of the last message associated with the event */
            "f": <uint>        /* event service flags */
        }
    }
}

For detectors that return data directly, such as trips and counters, the <detector_specific_id> level is not included:

Copied!
{
    "<detector_name>": {
        "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>,       /* time of the last message associated with the event */
        "f": <uint>        /* event service flags */
    }
}

For a private start or end position, for example when private mode hides the unit location, the x and y values are returned as 0.

0x2 flag

Returns detector-specific data. For ignition and sensors, the data returned for each unit sensor depends on its sensor event type. The type field in both objects shows the sensor event type.

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

Possible objects for sensors:

Copied!
"sensors": {
    "<sensor_id1>": {
        "state": <uint>,           /* 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": <bool>            /* current 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 */
    }
}

The battery_level detector works with battery level sensors. In check_updates, the ev detector returns the same current-event structure as battery_level.

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 */
    }
}
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!
"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 */
    }
}
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>,   /* criterion type: "acceleration", "brake", "turn", "speeding", "sensor", "harsh", "idling". */
        "index": <uint>,            /* criterion index */
        "max_speed": <uint>,        /* maximum speed recorded during the violation, in km/h */
        "mark": <double>            /* penalty points; may be a decimal and depend on the criterion settings and violation duration */
    }
}
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; omitted when the incident isn't associated with a sensor */
    }
}

0x4 flag

Returns available parameters of the message associated with the event. The p object can be omitted or returned as an empty object when no parameters are available.

When returned, the p object uses the grouping described for the 0x1 flag.

Copied!
"<detector_name>": {
    "<detector_specific_id>": {
        "p": {
            "test": 2,
            "foo": "bar",
            "trips": 1
        }
    }
}

For detectors that return data directly, the <detector_specific_id> level is not included:

Copied!
"<detector_name>": {
    "p": {
        "test": 2,
        "foo": "bar",
        "trips": 1
    }
}

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

0x8 flag

Returns additional detail data when available: track for trips and speedings, and data for instant and differential sensor events.

0x10 flag

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

For instant and differential sensors (types 2 and 3), except fuel level sensors, the following response is returned:

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

The v field value depends on the sensor type.

For fuel level sensors, the following response is returned:

Copied!
"lls": {
    "<sensor_id>": {
        "msgs": [
            {
                "tm": <uint>,      /* message time, UNIX-time */
                "v": <double>,     /* processed fuel level */
                "rv": <double>     /* raw sensor value */
            },
            ...
        ]
    },
    ...
}

The filling, theft, and fuel_level detectors use the same detailed-message structure as lls when detailed message data is available.

For trips, the following response is returned:

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

If the position is private, x, y, and c are returned as 0.

For speedings, the following response is returned:

Copied!
"speedings": {
    "0": {
        "msgs": [
            {
                "tm": <uint>, /* message time, UNIX time */
                "x": <double>,/* longitude */
                "y": <double>,/* latitude */
                "c": <uint>,  /* course */
                "s": <uint>,  /* speed */
                "l": <uint>,  /* speed limit */
                "pf": <uint>  /* position flags; omitted when 0 */
            },
            ...
        ]
    }
}

If the position is private, x, y, and c are returned as 0.

0x20 flag

Returns formatted detector values. The output depends on the unit settings and the measure and lang parameters.

The ignition and sensors detectors use the following format object:

Copied!
"<sensor_detector>": {
    "<sensor_id>": {
        "format": {
            "value": <text>,        /* formatted sensor value */
            "custom_value": <text>  /* custom sensor value corresponding to value */
        }
    }
}
Copied!
"trips": {
    "format": {
        "distance": <text>,  /* formatted trip distance */
        "avg_speed": <text>  /* formatted average trip speed */
    }
}
Copied!
"lls": {
    "<sensor_id>": {
        "format": {
            "value": <text>,        /* formatted processed fuel level */
            "raw_value": <text>,    /* formatted raw sensor value */
            "filled": <text>,       /* formatted filled fuel volume; 0 when there is no filling */
            "theft": <text>,        /* formatted stolen fuel volume; 0 when there is no theft */
            "custom_value": <text>  /* custom sensor value corresponding to 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 */
        }
    }
}

In check_updates, the ev detector returns the same format object as battery_level.

Copied!
"charge": {
    "<sensor_id>": {
        "format": {
            "charge": <text>  /* formatted charge volume */
        }
    }
}
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 engine hours; whole hours when no formatting is available */
        "mileage": <text>,             /* formatted mileage */
        "bytes": <uint>                /* GPRS traffic, in KiB */
    }
}

Error codes

If the request isn’t completed, an error code is returned.

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.

Report a mistake

Your message was sent. Thank you!

An error occurred while submitting the form