> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-api/user-api/resources/tracking/tracker/sensor.md). # 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](/docs/navixy-api/user-api/guides/data-retrieval/sensor-data.md). ## Sensor sub-types ### Metering sensor ```json { "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](#metering-sensor-type-values). * `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](/docs/navixy-api/general/api-conventions.md#data-types). 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](/docs/navixy-api/user-api/resources/tracking/tracker.md#post-tracker-list_models) 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 ```json { "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](#discrete-sensor-type-values). * `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 ```json { "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](#virtual-sensor-type-values). 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](/docs/navixy-api/user-api/resources/tracking/tracker.md#post-tracker-list_models) reports the `has_custom_fields` feature. * `parameters` - optional object with additional parameters. * `calc_method` - [enum](/docs/navixy-api/general/api-conventions.md#data-types). 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 > The many-tracker form of \`sensor/list\`. Available to demo accounts. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Trackers","description":"Trackers, the devices the platform tracks, together with the geo links that share their live location with people outside the account. Resources under the /tracker/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"schemas":{"Sensor":{"type":"object","description":"A sensor on a tracker. `type` selects which of three shapes this is: a **metering** sensor reads a continuous quantity, a **discrete** input reads an on/off line, and a **virtual** sensor derives a value from another input rather than measuring anything itself.","properties":{"type":{"type":"string","description":"Which kind of sensor this is.","enum":["metering","discrete","virtual"]},"id":{"type":"integer","description":"Sensor ID."},"name":{"type":"string","description":"Sensor name.","maxLength":100},"sensor_type":{"type":"string","description":"The sensor's subtype, drawn from a different set for each `type`. Metering: `fuel`, `temperature`, `rpm`, `custom`, `fuel_consumption`, `instant_consumption`, `power`, `speed`, `flow_meter`, `acceleration`. Discrete: `ignition`, `sos_button`, `power`, `engine`, `car_alarm`, `door`, `charge`, `detach`, `custom`. Virtual: `virtual_ignition` or `state`."},"input_name":{"type":"string","description":"Source input field name. Metering and virtual sensors only.","maxLength":64},"input_number":{"type":"integer","description":"Assigned input number. **Discrete inputs only.**","minimum":1,"maximum":8},"divider":{"type":"number","description":"Divider applied to the raw value. Metering sensors only."},"accuracy":{"type":"number","description":"Rounding accuracy, in steps of 0.25. Metering sensors only.","minimum":0,"maximum":100},"units":{"type":"string","description":"User label for the units."},"units_type":{"type":"string","description":"Unit of measurement. Metering sensors only."},"group_type":{"type":["string","null"],"description":"Aggregation method for this metering sensor when grouped. `sum` adds the values of grouped sensors; `avg` averages them. Required (non-null) for composite sensors; defaults to `sum` for non-composite metering sensors. Only meaningful on sensors of `type` `metering`.","enum":["sum","avg"]},"custom_field_name":{"type":"boolean","description":"Default `false`. Whether `input_name` is a value the user typed rather than one the protocol defines. Only meaningful when the tracker model reports `has_custom_fields`."},"parameters":{"type":"object","description":"Extra settings, which differ by `type`.\n\nMetering sensors take `parent_ids` and `volume` for composites, `min` and `max` bounds on the raw value, `max_lowering_by_time` and `max_lowering_by_mileage` to cap legitimate drops, and `ignore_drains_in_move`, `ignore_refuels_in_move` and `refuel_gap_minutes` to control fuel event detection during movement.\n\nVirtual sensors take `calc_method`, one of `in_range`, `identity` or `bit_index`; `range_from` and `range_to` for `in_range`, at least one of which is required; `bit_index` for `bit_index`; and up to 100 `value_titles`, each a unique `value` with a display `title`.","additionalProperties":true}},"required":["type"]}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/tracker/sensor/batch_list":{"post":{"tags":["Trackers"],"summary":"List sensors for several trackers","description":"The many-tracker form of `sensor/list`. Available to demo accounts.","operationId":"trackerSensorBatchList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"trackers":{"type":"array","description":"Tracker IDs. At most 500, and the limit may change.","items":{"type":"integer"},"maxItems":500}},"required":["trackers"]}}}},"responses":{"200":{"description":"Sensors per tracker","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"result":{"type":"object","description":"Sensor lists keyed by tracker ID.","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/Sensor"}}}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"403":{"description":"Error 217: one of the listed trackers does not exist or is blocked. Error 221: too many IDs were passed.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#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 > 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. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Trackers","description":"Trackers, the devices the platform tracks, together with the geo links that share their live location with people outside the account. Resources under the /tracker/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"schemas":{"Sensor":{"type":"object","description":"A sensor on a tracker. `type` selects which of three shapes this is: a **metering** sensor reads a continuous quantity, a **discrete** input reads an on/off line, and a **virtual** sensor derives a value from another input rather than measuring anything itself.","properties":{"type":{"type":"string","description":"Which kind of sensor this is.","enum":["metering","discrete","virtual"]},"id":{"type":"integer","description":"Sensor ID."},"name":{"type":"string","description":"Sensor name.","maxLength":100},"sensor_type":{"type":"string","description":"The sensor's subtype, drawn from a different set for each `type`. Metering: `fuel`, `temperature`, `rpm`, `custom`, `fuel_consumption`, `instant_consumption`, `power`, `speed`, `flow_meter`, `acceleration`. Discrete: `ignition`, `sos_button`, `power`, `engine`, `car_alarm`, `door`, `charge`, `detach`, `custom`. Virtual: `virtual_ignition` or `state`."},"input_name":{"type":"string","description":"Source input field name. Metering and virtual sensors only.","maxLength":64},"input_number":{"type":"integer","description":"Assigned input number. **Discrete inputs only.**","minimum":1,"maximum":8},"divider":{"type":"number","description":"Divider applied to the raw value. Metering sensors only."},"accuracy":{"type":"number","description":"Rounding accuracy, in steps of 0.25. Metering sensors only.","minimum":0,"maximum":100},"units":{"type":"string","description":"User label for the units."},"units_type":{"type":"string","description":"Unit of measurement. Metering sensors only."},"group_type":{"type":["string","null"],"description":"Aggregation method for this metering sensor when grouped. `sum` adds the values of grouped sensors; `avg` averages them. Required (non-null) for composite sensors; defaults to `sum` for non-composite metering sensors. Only meaningful on sensors of `type` `metering`.","enum":["sum","avg"]},"custom_field_name":{"type":"boolean","description":"Default `false`. Whether `input_name` is a value the user typed rather than one the protocol defines. Only meaningful when the tracker model reports `has_custom_fields`."},"parameters":{"type":"object","description":"Extra settings, which differ by `type`.\n\nMetering sensors take `parent_ids` and `volume` for composites, `min` and `max` bounds on the raw value, `max_lowering_by_time` and `max_lowering_by_mileage` to cap legitimate drops, and `ignore_drains_in_move`, `ignore_refuels_in_move` and `refuel_gap_minutes` to control fuel event detection during movement.\n\nVirtual sensors take `calc_method`, one of `in_range`, `identity` or `bit_index`; `range_from` and `range_to` for `in_range`, at least one of which is required; `bit_index` for `bit_index`; and up to 100 `value_titles`, each a unique `value` with a display `title`.","additionalProperties":true}},"required":["type"]}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/tracker/sensor/create":{"post":{"tags":["Trackers"],"summary":"Create a sensor","description":"Add a sensor to a tracker.\n\nA 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.\n\nRequires the `tracker_update` right.","operationId":"trackerSensorCreate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tracker_id":{"type":"integer","description":"ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked."},"sensor":{"allOf":[{"$ref":"#/components/schemas/Sensor"}],"description":"The sensor to create, without `id`."}},"required":["tracker_id","sensor"]}}}},"responses":{"200":{"description":"The created sensor","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"id":{"type":"integer","description":"ID of the new sensor."}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"403":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#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 > Remove a sensor from a tracker.\ > \ > Requires the \`tracker\_update\` right. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Trackers","description":"Trackers, the devices the platform tracks, together with the geo links that share their live location with people outside the account. Resources under the /tracker/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/tracker/sensor/delete":{"post":{"tags":["Trackers"],"summary":"Delete a sensor","description":"Remove a sensor from a tracker.\n\nRequires the `tracker_update` right.","operationId":"trackerSensorDelete","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tracker_id":{"type":"integer","description":"ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked."},"sensor_id":{"type":"integer","description":"Sensor ID.","minimum":1}},"required":["tracker_id","sensor_id"]}}}},"responses":{"200":{"description":"The sensor was deleted","$ref":"#/components/responses/OK"},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"403":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#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 > Get every sensor configured on one tracker. Available to demo accounts, and reachable from a fuel-server session as well as a normal one. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Trackers","description":"Trackers, the devices the platform tracks, together with the geo links that share their live location with people outside the account. Resources under the /tracker/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"schemas":{"Sensor":{"type":"object","description":"A sensor on a tracker. `type` selects which of three shapes this is: a **metering** sensor reads a continuous quantity, a **discrete** input reads an on/off line, and a **virtual** sensor derives a value from another input rather than measuring anything itself.","properties":{"type":{"type":"string","description":"Which kind of sensor this is.","enum":["metering","discrete","virtual"]},"id":{"type":"integer","description":"Sensor ID."},"name":{"type":"string","description":"Sensor name.","maxLength":100},"sensor_type":{"type":"string","description":"The sensor's subtype, drawn from a different set for each `type`. Metering: `fuel`, `temperature`, `rpm`, `custom`, `fuel_consumption`, `instant_consumption`, `power`, `speed`, `flow_meter`, `acceleration`. Discrete: `ignition`, `sos_button`, `power`, `engine`, `car_alarm`, `door`, `charge`, `detach`, `custom`. Virtual: `virtual_ignition` or `state`."},"input_name":{"type":"string","description":"Source input field name. Metering and virtual sensors only.","maxLength":64},"input_number":{"type":"integer","description":"Assigned input number. **Discrete inputs only.**","minimum":1,"maximum":8},"divider":{"type":"number","description":"Divider applied to the raw value. Metering sensors only."},"accuracy":{"type":"number","description":"Rounding accuracy, in steps of 0.25. Metering sensors only.","minimum":0,"maximum":100},"units":{"type":"string","description":"User label for the units."},"units_type":{"type":"string","description":"Unit of measurement. Metering sensors only."},"group_type":{"type":["string","null"],"description":"Aggregation method for this metering sensor when grouped. `sum` adds the values of grouped sensors; `avg` averages them. Required (non-null) for composite sensors; defaults to `sum` for non-composite metering sensors. Only meaningful on sensors of `type` `metering`.","enum":["sum","avg"]},"custom_field_name":{"type":"boolean","description":"Default `false`. Whether `input_name` is a value the user typed rather than one the protocol defines. Only meaningful when the tracker model reports `has_custom_fields`."},"parameters":{"type":"object","description":"Extra settings, which differ by `type`.\n\nMetering sensors take `parent_ids` and `volume` for composites, `min` and `max` bounds on the raw value, `max_lowering_by_time` and `max_lowering_by_mileage` to cap legitimate drops, and `ignore_drains_in_move`, `ignore_refuels_in_move` and `refuel_gap_minutes` to control fuel event detection during movement.\n\nVirtual sensors take `calc_method`, one of `in_range`, `identity` or `bit_index`; `range_from` and `range_to` for `in_range`, at least one of which is required; `bit_index` for `bit_index`; and up to 100 `value_titles`, each a unique `value` with a display `title`.","additionalProperties":true}},"required":["type"]}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/tracker/sensor/list":{"post":{"tags":["Trackers"],"summary":"List a tracker's sensors","description":"Get every sensor configured on one tracker. Available to demo accounts, and reachable from a fuel-server session as well as a normal one.","operationId":"trackerSensorList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tracker_id":{"type":"integer","description":"ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked."}},"required":["tracker_id"]}}}},"responses":{"200":{"description":"The sensors","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"$ref":"#/components/schemas/Sensor"}}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"403":{"description":"Error 208: the tracker exists but is blocked, normally because its tariff ended.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes): * 208 - The tracker exists but is blocked, normally because its tariff ended. *** *Required sub-user rights:* `tracker_update`. ## Update a sensor > Replace a sensor's configuration. Send the full object including its \`id\`.\ > \ > Requires the \`tracker\_update\` right. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Trackers","description":"Trackers, the devices the platform tracks, together with the geo links that share their live location with people outside the account. Resources under the /tracker/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"schemas":{"Sensor":{"type":"object","description":"A sensor on a tracker. `type` selects which of three shapes this is: a **metering** sensor reads a continuous quantity, a **discrete** input reads an on/off line, and a **virtual** sensor derives a value from another input rather than measuring anything itself.","properties":{"type":{"type":"string","description":"Which kind of sensor this is.","enum":["metering","discrete","virtual"]},"id":{"type":"integer","description":"Sensor ID."},"name":{"type":"string","description":"Sensor name.","maxLength":100},"sensor_type":{"type":"string","description":"The sensor's subtype, drawn from a different set for each `type`. Metering: `fuel`, `temperature`, `rpm`, `custom`, `fuel_consumption`, `instant_consumption`, `power`, `speed`, `flow_meter`, `acceleration`. Discrete: `ignition`, `sos_button`, `power`, `engine`, `car_alarm`, `door`, `charge`, `detach`, `custom`. Virtual: `virtual_ignition` or `state`."},"input_name":{"type":"string","description":"Source input field name. Metering and virtual sensors only.","maxLength":64},"input_number":{"type":"integer","description":"Assigned input number. **Discrete inputs only.**","minimum":1,"maximum":8},"divider":{"type":"number","description":"Divider applied to the raw value. Metering sensors only."},"accuracy":{"type":"number","description":"Rounding accuracy, in steps of 0.25. Metering sensors only.","minimum":0,"maximum":100},"units":{"type":"string","description":"User label for the units."},"units_type":{"type":"string","description":"Unit of measurement. Metering sensors only."},"group_type":{"type":["string","null"],"description":"Aggregation method for this metering sensor when grouped. `sum` adds the values of grouped sensors; `avg` averages them. Required (non-null) for composite sensors; defaults to `sum` for non-composite metering sensors. Only meaningful on sensors of `type` `metering`.","enum":["sum","avg"]},"custom_field_name":{"type":"boolean","description":"Default `false`. Whether `input_name` is a value the user typed rather than one the protocol defines. Only meaningful when the tracker model reports `has_custom_fields`."},"parameters":{"type":"object","description":"Extra settings, which differ by `type`.\n\nMetering sensors take `parent_ids` and `volume` for composites, `min` and `max` bounds on the raw value, `max_lowering_by_time` and `max_lowering_by_mileage` to cap legitimate drops, and `ignore_drains_in_move`, `ignore_refuels_in_move` and `refuel_gap_minutes` to control fuel event detection during movement.\n\nVirtual sensors take `calc_method`, one of `in_range`, `identity` or `bit_index`; `range_from` and `range_to` for `in_range`, at least one of which is required; `bit_index` for `bit_index`; and up to 100 `value_titles`, each a unique `value` with a display `title`.","additionalProperties":true}},"required":["type"]}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/tracker/sensor/update":{"post":{"tags":["Trackers"],"summary":"Update a sensor","description":"Replace a sensor's configuration. Send the full object including its `id`.\n\nRequires the `tracker_update` right.","operationId":"trackerSensorUpdate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tracker_id":{"type":"integer","description":"ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked."},"sensor":{"allOf":[{"$ref":"#/components/schemas/Sensor"}],"description":"The full sensor object, including `id`."}},"required":["tracker_id","sensor"]}}}},"responses":{"200":{"description":"The sensor was updated","$ref":"#/components/responses/OK"},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"403":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#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. *** {% hint style="danger" %} **Important.** This operation deletes the sensors of the target trackers, and some sensor data can be lost. {% endhint %} *Required sub-user rights:* `tracker_update`. ## Copy sensors between trackers > 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. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Trackers","description":"Trackers, the devices the platform tracks, together with the geo links that share their live location with people outside the account. Resources under the /tracker/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/tracker/sensor/batch_copy":{"post":{"tags":["Trackers"],"summary":"Copy sensors between trackers","description":"Copy every sensor from one tracker onto others.\n\n**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.\n\nRequires the `tracker_update` right.","operationId":"trackerSensorBatchCopy","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"base_tracker_id":{"type":"integer","description":"Tracker to copy the sensors from."},"trackers":{"type":"array","description":"Trackers to copy onto. **Their existing sensors are deleted.**","items":{"type":"integer"}}},"required":["base_tracker_id","trackers"]}}}},"responses":{"200":{"description":"The sensors were copied","$ref":"#/components/responses/OK"},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"403":{"description":"Error 201: no tracker with this ID belongs to the account. Error 272: the base tracker and one of the targets have different models.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#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 > 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. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Trackers","description":"Trackers, the devices the platform tracks, together with the geo links that share their live location with people outside the account. Resources under the /tracker/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"schemas":{"SensorDataPoint":{"type":"object","description":"One recorded sensor reading.","properties":{"value":{"description":"The reading. Double, integer or string depending on the sensor."},"get_time":{"type":"string","description":"When the value was received."}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/tracker/sensor/data/read":{"post":{"tags":["Trackers"],"summary":"Read sensor history","description":"Get a sensor's recorded readings over a period. Available to demo accounts, and reachable from a fuel-server session.\n\n**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.","operationId":"trackerSensorDataRead","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tracker_id":{"type":"integer","description":"ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked."},"sensor_id":{"type":"integer","description":"Sensor ID.","minimum":1},"from":{"type":"string","description":"Start of the period."},"to":{"type":"string","description":"End of the period. Must be after `from`."},"raw_data":{"type":"boolean","description":"Optional. Default `false`. Return values without calibration or multiplication applied. Affects metering sensors only."}},"required":["tracker_id","sensor_id","from","to"]}}}},"responses":{"200":{"description":"The readings","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"$ref":"#/components/schemas/SensorDataPoint"}}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"403":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#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. ## More in this section #### Sensor calibration data | Endpoint | Method | What it does | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ----------------------------------- | | [`/tracker/sensor/calibration_data/read`](/docs/navixy-api/user-api/resources/tracking/tracker/sensor/calibration_data.md#post-tracker-sensor-calibration_data-read) | POST | Read calibration data | | [`/tracker/sensor/calibration_data/update`](/docs/navixy-api/user-api/resources/tracking/tracker/sensor/calibration_data.md#post-tracker-sensor-calibration_data-update) | POST | Replace calibration data | | [`/tracker/sensor/calibration_data/upload_omnicomm`](/docs/navixy-api/user-api/resources/tracking/tracker/sensor/calibration_data.md#post-tracker-sensor-calibration_data-upload_omnicomm) | POST | Upload an Omnicomm calibration file | #### Sensor inputs | Endpoint | Method | What it does | | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | --------------------------------------- | | [`/tracker/sensor/input_name/list`](/docs/navixy-api/user-api/resources/tracking/tracker/sensor/input_name.md#post-tracker-sensor-input_name-list) | POST | List all sensor inputs and state fields | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://navixy.com/docs/navixy-api/user-api/resources/tracking/tracker/sensor.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.