Sensor actions¶

Contains API calls to interact with sensors.

Sensor sub-types¶

Metering sensor¶

{
    "type": "metering",
    "id": 860250,
    "sensor_type": "temperature",
    "name": "OBD Coolant temperature",
    "input_name": "obd_coolant_t",
    "divider": 1.0,
    "accuracy": 0.0,
    "units": "",
    "units_type": "celsius",
    "parameters": {
      "parent_ids": [123042, 123566],
      "volume": 0.7,
      "min": 0.0,
      "max": 12.0,
      "max_lowering_by_time": 120.0,
      "max_lowering_by_mileage": 120.0,
      "ignore_drains_in_move": true,
      "ignore_refuels_in_move": false,
      "refuel_gap_minutes": 11,
      "custom_field_name": false
    }
}

• type - string. Always "metering".
• id - int. Sensor's id.
• sensor_type - metering sensor type. Type of the sensor.
• name - string, max size 100. A name of sensor.
• input_name - string, max size 64.
• divider - double.
• accuracy - double. The minimum=0.0, maximum=100.0 with step 0.25.
• units - string.
• units_type - enum. Units type for a sensor.
• parameters - optional object with additional parameters.
  • parent_ids - optional array of parent_ids for composite sensor.
  • volume - double. Optional. Volume for composite sensor.
  • parent_ids - optional. int array. Array of parent_ids for composite sensor.
  • volume - optional. Double. Volume for composite sensor.
  • min - optional. Double. Min acceptable raw value for a sensor.
  • max - optional. Double. Max acceptable raw value for a sensor.
  • max_lowering_by_time - optional. Double. Maximum legal value lowering per hour.
  • max_lowering_by_mileage - optional. Double. Maximum legal value lowering per 100 km.
  • ignore_drains_in_move - optional. Boolean. Default is false. If true, the fuel drains will not be detected during movement.
  • ignore_refuels_in_move - optional. Boolean. Default is false. If true, the refuels will not be detected during movement.
  • refuel_gap_minutes - optional. Integer. Default is 5. The time in minutes after the start of the movement, refuels will be detected during movement.
  • custom_field_name - optional. Boolean. Default false. The parameter determines whether the input_name field is a custom value was entered by user. This makes sense only if the tracker model has the feature has_custom_fields.

Metering sensor type values¶

• fuel
• temperature
• rpm
• custom
• fuel_consumption
• instant_consumption
• power
• speed
• flow_meter
• acceleration

Discrete input¶

{
  "type": "discrete",
  "id": 888951,
  "sensor_type": "ignition",
  "name": "Ignition",
  "input_number": 4
}

• type - string. Always "discrete".
• id - int. An ID of a sensor.
• sensor_type - discrete sensor type. Type of the sensor.
• name - string, max size 100.
• input_number - int, [1..8]. Assigned input number.

Discrete sensor type values¶

• ignition
• sos_button
• power
• engine
• car_alarm
• door
• charge
• detach
• custom

Virtual sensor¶

{
  "type": "virtual",
  "id": 1700049,
  "sensor_type": "virtual_ignition",
  "name": "Virtual Ignition",
  "input_name": "board_voltage",
  "custom_field_name": false,
  "parameters": {
    "calc_method": "in_range",
    "range_from": 13.4,
    "value_titles": [{
        "value": "0",
        "title": "Off"
    }, {
        "value": "1",
        "title": "On"
    }]
  }
}

• type - string. Always "virtual".
• id - int. Sensor's id.
• sensor_type - virtual sensor type. Type of the sensor. "virtual_ignition" for virtual ignition or "state" for others.
• name - string, max size 100. A name of sensor.
• input_name - string, max size 64. A source input field name (identifier).
• custom_field_name - optional. Boolean. Default false. The parameter determines whether the input_name field is a custom value was entered by user. This makes sense only if the tracker model has the feature has_custom_fields.
• parameters - optional object with additional parameters.
  • calc_method - enum. A method of sensor value calculation. One of this: "in_range", "identity", "bit_index".
  • range_from - double. Low bound of range. It is used only with "in_range" calc method.
  • range_to - double. High bound of range. It is used only with "in_range" calc method.
  • bit_index - int, [1..N]. A bit index in input field source value. It is used only with "bit_index" calc method.
  • value_titles - mapping for bind special titles for sensor values, if it is necessary.
    • value - string, max size 64. Sensor value.
    • title - string, max size 64. Title for the sensor value.

Virtual sensor type values¶

• state
• virtual_ignition

Some requirements:

• There can be only one virtual sensor with type virtual_ignition for tracker.
• One or both field range_from and range_to must be present for the calc method "in_range".
• Field bit_index must be present for the calc method "bit_index".
• There can be no more than 100 value titles.
• All values must be unique within value_titles.

Described work with virtual sensors in our instructions.

API actions¶

API base path: /tracker/sensor.

batch_list¶

List tracker sensors bound to trackers with specified identifiers (parameter trackers).

There exists a similar method for working with a single tracker - list.

Parameters¶

Examples¶

curl -X POST 'https://api.navixy.com/v2/tracker/sensor/batch_list' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "trackers": [204104, 181451]}'

https://api.navixy.com/v2/tracker/sensor/batch_list?hash=a6aa75587e5c59c32d347da438505fc3&trackers=[204104, 181451]

Response¶

Contains a map, where keys are IDs from trackers parameter and values are lists of sensor objects.

{
  "success": true,
  "result": {
    "11": [
      {
        "id": 1,
        "type": "discrete",
        "sensor_type": "fuel",
        "name": "Main tank",
        "input_name": "fuel_level",
        "group_type": null,
        "divider": 1,
        "accuracy": 0.0,
        "units": null,
        "units_type": "litre"
      }
    ]
  }
}

Errors¶

• 217 - List contains nonexistent entities - if one of trackers either does not exist or is blocked.
• 221 - Device limit exceeded - if too many IDs were passed in trackers parameter.

create¶

Creates a sensor.

required sub-user rights: tracker_update.

Parameters¶

Examples¶

curl -X POST 'https://api.navixy.com/v2/tracker/sensor/create' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "tracker_id": 123456, "sensor": {"type": "metering", "id": 860250,"sensor_type": "temperature", "name": "OBD Coolant temperature", "input_name": "obd_coolant_t", "divider": 1.0, "accuracy": 0.0, "units": "", "units_type": "celsius"}'

Response¶

{
    "success": true,
    "id": 937
}

• id - int. An ID of created sensor.

Errors¶

• 232 - Input already in use – if given input number (for discrete input) or input name (for metering sensor) already in use.
• 208 - Device blocked – if tracker exists but was blocked due to tariff restrictions, or some other reason.
• 219 - Not allowed for clones of the device – if tracker is clone.
• 270 - Too many sensors of same type - the number of tracker's sensors, having same sensor_type is limited.

delete¶

Deletes a sensor with sensor_id from the database.

required sub-user rights: tracker_update.

Parameters¶

Examples¶

curl -X POST 'https://api.navixy.com/v2/tracker/sensor/delete' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "tracker_id": 123456, "sensor_id": 23456}'

https://api.navixy.com/v2/tracker/sensor/delete?hash=a6aa75587e5c59c32d347da438505fc3&tracker_id=123456&sensor_id=23456

Response¶

{ "success": true }

Errors¶

• 201 - Not found in the database - if sensor with a sensor_id does not exist or owned by another user.
• 208 – Device blocked - if tracker exists but was blocked due to tariff restrictions or some other reason.
• 219 – Not allowed for clones of the device - if tracker is a clone.

list¶

List tracker sensors bound to tracker with specified ID (tracker_id parameter).

Parameters¶

Examples¶

curl -X POST 'https://api.navixy.com/v2/tracker/sensor/list' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "tracker_id": 123456}'

https://api.navixy.com/v2/tracker/sensor/list?hash=a6aa75587e5c59c32d347da438505fc3&tracker_id=123456

Response¶

{
   "success": true,
   "list": [{
    "type": "metering",
    "id": 860250,
    "sensor_type": "temperature",
    "name": "OBD Coolant temperature",
    "input_name": "obd_coolant_t",
    "divider": 1.0,
    "accuracy": 0.0,
    "units": "",
    "units_type": "celsius" 
   }]
}

• list - list of sensor objects. See sensor object description.

Errors¶

• 208 - Device blocked – if tracker exists but was blocked due to tariff restrictions, or some other reason.

update¶

Updates sensor.

required sub-user rights: tracker_update.

Parameters¶

Example¶

curl -X POST 'https://api.navixy.com/v2/tracker/sensor/update' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "tracker_id": 123456, "sensor": {"type": "metering", "id": 860250, "sensor_type": "temperature", "name": "OBD Coolant temperature", "input_name": "obd_coolant_t", "divider": 1.0, "accuracy": 0.0, "units": "", "units_type": "celsius"}'

Response¶

{ "success": true }

Errors¶

• 201 - Not found in the database – if sensor does not exist or owned by another user.
• 232 - Input already in use – if given input number (for discrete input) or input name (for metering sensor) already in use.
• 208 - Device blocked – if tracker exists but was blocked due to tariff restrictions, or some other reason.
• 219 - Not allowed for clones of the device – if tracker is a clone.

batch_copy¶

Copies sensors from one tracker to another.

required sub-user rights: tracker_update.

Parameters¶

Example¶

curl -X POST 'https://api.navixy.com/v2/tracker/sensor/batch_copy' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "base_tracker_id": 123456, "trackers": [56789, 54321]}'

Response¶

{
    "success": true
}

Errors¶

• 201 – Not found in the database - if there is no tracker with such ID belonging to authorized user.
• 272 – Trackers must have the same model - if base tracker and one of target trackers has a different model.

data/read¶

Gets all metering or virtual sensor readings with values and time per requested period. It can't be used with discrete sensor.

Parameters¶

Example¶

curl -X POST 'https://api.navixy.com/v2/tracker/sensor/data/read' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "tracker_id": 123456, "sensor_id": 1456789, "from": "2022-02-28 00:00:00", "to": "2022-03-28 23:59:00"}'

Response¶

{
  "success": true,
  "list": [
    {
      "value": 100500,
      "get_time": "2022-02-28 00:00:00"
    },
    {
      "value": 100501,
      "get_time": "2022-02-28 00:00:30"
    }
  ]
}

• value - a value of sensor data. It can be double, int or string depending on the sensor type.
• get_time - time when value was received.

Errors¶

• 201 – Not found in the database - if there is no tracker with such ID belonging to authorized user.
• 211 – Requested time span is too big - if interval between "from" and "to" is too big. Maximum period is maxReportTimeSpan.
• 228 – Not supported by the sensor - if sensor is not a metering or virtual sensor.