Sensor

The three kinds of sensor a tracker can carry, and the operations that manage them.

A sensor turns what a device reports into something meaningful. The device sends a raw input, such as a voltage on a wire or a value on the CAN bus, and the sensor says what that input means, what units it is in, and how to convert it.

Sensors come in three kinds, and which fields apply depends on which kind you are creating:

A metering sensor reads a continuous quantity, such as fuel level or temperature.
A discrete input reads a two-state input, such as ignition on or off.
A virtual sensor derives its value from another input rather than from a wire of its own.

Two constraints apply across all of them. A discrete input number, and a metering sensor's input name, can each be used only once per tracker, and reusing one returns error 232. The number of sensors sharing a sensor_type is also capped, reported as error 270. For a walkthrough, see how to retrieve sensor and counter data.

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 ID.
sensor_type - metering sensor type.
name - string, max 100 characters.
input_name - string, max 64 characters. The source input field the sensor reads.
divider - double. Factor the raw value is divided by.
accuracy - double. From 0.0 to 100.0 in steps of 0.25.
units - string. Free-text unit label.
units_type - enum. Unit type for the sensor.
parameters - optional object with additional parameters.
- parent_ids - optional int array. Component sensors of a composite sensor.
- volume - optional double. Volume for a composite sensor.
- min - optional double. Lowest acceptable raw value.
- max - optional double. Highest acceptable raw value.
- max_lowering_by_time - optional double. Largest legitimate drop per hour.
- max_lowering_by_mileage - optional double. Largest legitimate drop per 100 km.
- ignore_drains_in_move - optional boolean, default false. When true, fuel drains are not detected while the vehicle moves.
- ignore_refuels_in_move - optional boolean, default false. When true, refuels are not detected while the vehicle moves.
- refuel_gap_minutes - optional int, default 5. Minutes after movement starts during which refuels are still detected.
- custom_field_name - optional boolean, default false. Whether input_name holds a value the user entered rather than a known field. This applies only when the tracker model reports the has_custom_fields feature.

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. Sensor ID.
sensor_type - discrete sensor type.
name - string, max 100 characters.
input_number - int from 1 to 8. The physical input the sensor is wired to.

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 ID.
sensor_type - virtual sensor type. Use virtual_ignition for virtual ignition and state for everything else.
name - string, max 100 characters.
input_name - string, max 64 characters. The source input field name.
custom_field_name - optional boolean, default false. Whether input_name holds a value the user entered rather than a known field. This applies only when the tracker model reports the has_custom_fields feature.
parameters - optional object with additional parameters.
- calc_method - enum. How the value is calculated: in_range, identity, or bit_index.
- range_from - double. Lower bound of the range. Used only with the in_range method.
- range_to - double. Upper bound of the range. Used only with the in_range method.
- bit_index - int from 1 upwards. Which bit of the source value to read. Used only with the bit_index method.
- value_titles - optional mapping that gives sensor values readable titles.
  - value - string, max 64 characters. The sensor value.
  - title - string, max 64 characters. The title shown for that value.

Virtual sensor type values

state - custom virtual sensor
virtual_ignition - virtual ignition sensor

Virtual sensors carry their own rules:

A tracker can have only one virtual sensor of type virtual_ignition.
The in_range method needs range_from, range_to, or both.
The bit_index method needs bit_index.
There can be at most 100 value titles.
Values must be unique within value_titles.

API actions

API base path: /tracker/sensor.

List sensors for several trackers

post

/tracker/sensor/batch_list

The many-tracker form of sensor/list. Available to demo accounts.

Authorizations

AuthorizationstringRequired

Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.

Body

trackersinteger[] · max: 500Required

Tracker IDs. At most 500, and the limit may change.

Example: [11,12]

Responses

200

Sensors per tracker

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

400

Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.

application/json

403

Error 217: one of the listed trackers does not exist or is blocked. Error 221: too many IDs were passed.

application/json

default

Error response object

application/json

post/tracker/sensor/batch_list

POST /v2/tracker/sensor/batch_list HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "trackers": [
    11,
    12
  ]
}

{
  "success": true,
  "result": {
    "ANY_ADDITIONAL_PROPERTY": [
      {
        "type": "metering",
        "id": 860250,
        "name": "OBD Coolant temperature",
        "sensor_type": "temperature",
        "input_name": "obd_coolant_t",
        "input_number": 4,
        "divider": 1,
        "accuracy": 0,
        "units": "text",
        "units_type": "celsius",
        "group_type": "sum",
        "custom_field_name": true,
        "parameters": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    ]
  }
}

Errors

These errors come in addition to the general error codes:

217 - One of the listed trackers does not exist or is blocked.
221 - Too many IDs were passed.

Required sub-user rights: tracker_update.

Create a sensor

post

/tracker/sensor/create

Add a sensor to a tracker.

A discrete input number, or a metering sensor's input name, can only be used once per tracker; reusing one is error 232. The number of sensors sharing a sensor_type is also capped, reported as error 270.

Requires the tracker_update right.

Authorizations

AuthorizationstringRequired

Body

tracker_idintegerRequired

ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked.

Example: 123456

Responses

200

The created sensor

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

idintegerOptional

ID of the new sensor.

Example: 937

400

Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.

application/json

403

Error 208: the tracker exists but is blocked, normally because its tariff ended. Error 219: the tracker is a clone. Error 232: that input number or input name is already used on this tracker. Error 270: too many sensors of this type.

application/json

default

Error response object

application/json

post/tracker/sensor/create

POST /v2/tracker/sensor/create HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 328

{
  "tracker_id": 123456,
  "sensor": {
    "type": "metering",
    "id": 860250,
    "name": "OBD Coolant temperature",
    "sensor_type": "temperature",
    "input_name": "obd_coolant_t",
    "input_number": 4,
    "divider": 1,
    "accuracy": 0,
    "units": "text",
    "units_type": "celsius",
    "group_type": "sum",
    "custom_field_name": true,
    "parameters": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
}

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

Errors

These errors come in addition to the general error codes:

208 - The tracker exists but is blocked, normally because its tariff ended.
219 - The tracker is a clone.
232 - That input number or input name is already used on this tracker.
270 - Too many sensors of this type.

Required sub-user rights: tracker_update.

Delete a sensor

post

/tracker/sensor/delete

Remove a sensor from a tracker.

Requires the tracker_update right.

Authorizations

AuthorizationstringRequired

Body

tracker_idintegerRequired

ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked.

Example: 123456

sensor_idinteger · min: 1Required

Sensor ID.

Example: 234567

Responses

200

The sensor was deleted

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

400

Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.

application/json

403

Error 201: the sensor does not exist or belongs to another user. Error 208: the tracker exists but is blocked, normally because its tariff ended. Error 219: the tracker is a clone.

application/json

default

Error response object

application/json

post/tracker/sensor/delete

POST /v2/tracker/sensor/delete HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 40

{
  "tracker_id": 123456,
  "sensor_id": 234567
}

{
  "success": true
}

Errors

These errors come in addition to the general error codes:

201 - The sensor does not exist or belongs to another user.
208 - The tracker exists but is blocked, normally because its tariff ended.
219 - The tracker is a clone.

List a tracker's sensors

post

/tracker/sensor/list

Get every sensor configured on one tracker. Available to demo accounts, and reachable from a fuel-server session as well as a normal one.

Authorizations

AuthorizationstringRequired

Body

tracker_idintegerRequired

ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked.

Example: 123456

Responses

200

The sensors

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

400

Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.

application/json

403

Error 208: the tracker exists but is blocked, normally because its tariff ended.

application/json

default

Error response object

application/json

post/tracker/sensor/list

POST /v2/tracker/sensor/list HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 21

{
  "tracker_id": 123456
}

{
  "success": true,
  "list": [
    {
      "type": "metering",
      "id": 860250,
      "name": "OBD Coolant temperature",
      "sensor_type": "temperature",
      "input_name": "obd_coolant_t",
      "input_number": 4,
      "divider": 1,
      "accuracy": 0,
      "units": "text",
      "units_type": "celsius",
      "group_type": "sum",
      "custom_field_name": true,
      "parameters": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ]
}

Errors

These errors come in addition to the general error codes:

208 - The tracker exists but is blocked, normally because its tariff ended.

Required sub-user rights: tracker_update.

Update a sensor

post

/tracker/sensor/update

Replace a sensor's configuration. Send the full object including its id.

Requires the tracker_update right.

Authorizations

AuthorizationstringRequired

Body

tracker_idintegerRequired

ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked.

Example: 123456

Responses

200

The sensor was updated

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

400

Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.

application/json

403

Error 201: the sensor does not exist or belongs to another user. Error 208: the tracker exists but is blocked, normally because its tariff ended. Error 219: the tracker is a clone. Error 232: that input number or input name is already used on this tracker.

application/json

default

Error response object

application/json

post/tracker/sensor/update

POST /v2/tracker/sensor/update HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 328

{
  "tracker_id": 123456,
  "sensor": {
    "type": "metering",
    "id": 860250,
    "name": "OBD Coolant temperature",
    "sensor_type": "temperature",
    "input_name": "obd_coolant_t",
    "input_number": 4,
    "divider": 1,
    "accuracy": 0,
    "units": "text",
    "units_type": "celsius",
    "group_type": "sum",
    "custom_field_name": true,
    "parameters": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
}

{
  "success": true
}

Errors

These errors come in addition to the general error codes:

201 - The sensor does not exist or belongs to another user.
208 - The tracker exists but is blocked, normally because its tariff ended.
219 - The tracker is a clone.
232 - That input number or input name is already used on this tracker.

Important. This operation deletes the sensors of the target trackers, and some sensor data can be lost.

Required sub-user rights: tracker_update.

Copy sensors between trackers

post

/tracker/sensor/batch_copy

Copy every sensor from one tracker onto others.

This deletes the target trackers' existing sensors first, and their historical sensor data can be lost with them. There is no merge mode and no undo. All trackers involved must share the same model, reported as error 272.

Requires the tracker_update right.

Authorizations

AuthorizationstringRequired

Body

base_tracker_idintegerRequired

Tracker to copy the sensors from.

Example: 123456

trackersinteger[]Required

Trackers to copy onto. Their existing sensors are deleted.

Example: [12345,54321]

Responses

200

The sensors were copied

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

400

Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.

application/json

403

Error 201: no tracker with this ID belongs to the account. Error 272: the base tracker and one of the targets have different models.

application/json

default

Error response object

application/json

post/tracker/sensor/batch_copy

POST /v2/tracker/sensor/batch_copy HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "base_tracker_id": 123456,
  "trackers": [
    12345,
    54321
  ]
}

{
  "success": true
}

Errors

These errors come in addition to the general error codes:

201 - No tracker with this ID belongs to the account.
272 - The base tracker and one of the targets have different models.

Read sensor history

post

/tracker/sensor/data/read

Get a sensor's recorded readings over a period. Available to demo accounts, and reachable from a fuel-server session.

Metering and virtual sensors only; a discrete input answers error 228. The period is capped by the platform's report time span, thirty days by default.

Authorizations

AuthorizationstringRequired

Body

tracker_idintegerRequired

ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked.

Example: 123456

sensor_idinteger · min: 1Required

Sensor ID.

Example: 234567

fromstringRequired

Start of the period.

Example: 2022-02-28 00:00:00

tostringRequired

End of the period. Must be after from.

Example: 2022-03-28 23:59:00

raw_databooleanOptional

Optional. Default false. Return values without calibration or multiplication applied. Affects metering sensors only.

Responses

200

The readings

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

400

Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.

application/json

403

Error 201: no tracker with this ID belongs to the account. Error 211: the period is longer than the platform allows. Error 228: the sensor is neither metering nor virtual.

application/json

default

Error response object

application/json

post/tracker/sensor/data/read

POST /v2/tracker/sensor/data/read HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 112

{
  "tracker_id": 123456,
  "sensor_id": 234567,
  "from": "2022-02-28 00:00:00",
  "to": "2022-03-28 23:59:00",
  "raw_data": true
}

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

Errors

These errors come in addition to the general error codes:

201 - No tracker with this ID belongs to the account.
211 - The period is longer than the Navixy platform allows.
228 - The sensor is neither metering nor virtual.

Sensor

Sensor sub-types

Metering sensor

Metering sensor type values

Discrete input

Discrete sensor type values

Virtual sensor

Virtual sensor type values

API actions

List sensors for several trackers

Errors

Create a sensor

Errors

Delete a sensor

Errors

List a tracker's sensors

Errors

Update a sensor

Errors

Copy sensors between trackers

Errors

Read sensor history

Errors

More in this section

Sensor calibration data

Sensor inputs