Message structure and attributes
Complete reference for NGP message attributes: location, events, cell towers, Wi-Fi, sensors, I/O, and custom fields.
NGP messages are JSON objects transmitted one per request. Each message must contain two mandatory attributes: device_id and message_time. For transport connection parameters and body encoding requirements, see Transport layer.
message_time must not be earlier than the timestamp of the most recently received message for this device. Messages with an out-of-order timestamp will be discarded by the platform.
Fields with no availability tag work in all versions. Fields with restricted availability are marked:
1.2+— requires"version": "1.2"in the messageon demand— requires a separate arrangement with Navixy; not available for standard integrations
Minimum valid message
{
"message_time": "2026-02-05T06:00:11Z",
"device_id": "1112312212"
}Minimum message to be stored by the platform
The platform requires a valid location with at least 3 satellites before saving a data point. The device_id must already be registered on the platform.
{
"message_time": "2026-02-05T06:00:11Z",
"device_id": "1112312212",
"location": {
"latitude": 34.15929687705282,
"longitude": -118.4614133834839,
"satellites": 3
}
}Attributes
The table below lists all pre-defined attributes, organized by category. In addition to these, the protocol allows custom attributes. See Custom attributes.
The platform validates all incoming messages. Messages with invalid JSON or out-of-range field values are silently discarded.
Basic attributes
message_time
Timestamp
Root
Yes
Date and time the message was sent by the device (ISO 8601 UTC).
device_id
String
Root
Yes
Unique device identifier. Maximum 64 characters.
version
String
Root
No
NGP version of this message. Defaults to 1.0 if omitted.
Location
location
Object
Root
No
Device position. May be determined by GNSS (satellite), LBS (cell towers), or a third-party positioning service.
└─ latitude
Float
location
No
Latitude in decimal degrees (−90.0 to 90.0).
└─ longitude
Float
location
No
Longitude in decimal degrees (−180.0 to 180.0).
└─ altitude
Float
location
No
Altitude above sea level in meters (−1000 to 10000).
└─ gnss_time
Timestamp
location
No
Time when the position fix was acquired by the device.
└─ fix_type
String
location
No
Position fix type. Possible values: HAS_FIX (default), NO_FIX, LAST_KNOWN_POSITION, FIX_2D, FIX_3D.
└─ satellites
Integer
location
No
Number of GNSS satellites used for the fix (0–64).
└─ hdop
Float
location
No
Horizontal dilution of precision. Lower is more accurate.
└─ vdop
Float
location
No
Vertical dilution of precision. Lower is more accurate.
└─ pdop
Float
location
No
3D position dilution of precision, combining horizontal and vertical.
└─ speed
Float
location
No
Device speed in km/h (positive values only).
└─ heading
Integer
location
No
Direction of movement in degrees, clockwise from north (1–360).
└─ source_type
String
location
No
Positioning source. Possible values: GNSS (satellite), LBS (cell tower-based), ATLAS (third-party positioning service). Defaults to GNSS when omitted.
1.2+
└─ precision
Integer
location
No
Location accuracy in meters. Recommended for LBS and ATLAS positions.
1.2+
Event information
event_id
Integer
Root
No
Platform event identifier. See Predefined event identifiers for standard values. Custom events start at 10,000.
Mobile cells
mobile_cells
Array [Object]
Root
No
List of visible cell towers. Used to provide data for network-based positioning (LBS) when GNSS is unavailable.
└─ mcc
Integer
mobile_cells
Yes
Mobile Country Code. Identifies the country of the mobile network.
└─ mnc
Integer
mobile_cells
Yes
Mobile Network Code. Identifies the mobile operator within the country.
└─ lac
Integer
mobile_cells
Yes
Location Area Code. Identifies the area within the mobile network.
└─ cell_id
Integer
mobile_cells
Yes
Unique identifier of the cell tower.
└─ rssi
Integer
mobile_cells
No
Signal strength from the cell tower in dBm (negative values).
└─ type
String
mobile_cells
No
Radio access technology. Possible values: GSM (default), CDMA, WCDMA, LTE, NR.
Wi-Fi points
wifi_points
Array [Object]
Root
No
List of visible Wi-Fi access points. Used alongside mobile_cells to improve network-based positioning accuracy.
└─ mac
String
wifi_points
Yes
MAC address of the access point. Colon-delimited bytes, e.g. 12:33:FF:45:04:33.
└─ rssi
Integer
wifi_points
Yes
Signal strength in dBm (negative values).
└─ age
Integer
wifi_points
No
Milliseconds since this access point was last detected.
└─ channel
Integer
wifi_points
No
Radio channel number used by the access point.
Device motion and status
is_moving
Boolean
Root
No
true if the device is currently moving, false if stationary.
hardware_mileage
Float
Root
No
Cumulative mileage counted by the device hardware, in kilometers.
battery_voltage
Float
Root
No
Built-in battery voltage in volts.
battery_level
Integer
Root
No
Built-in battery charge level as a percentage (0–100).
board_voltage
Float
Root
No
External power supply voltage in volts.
Input/Output status
input_status
Integer
Root
No
State of discrete inputs as a bitmask. Bit 0 = input 1, bit 1 = input 2, and so on. A set bit means the input is active.
output_status
Integer
Root
No
State of outputs as a bitmask. Bit 0 = output 1, bit 1 = output 2, and so on. A set bit means the output is active.
Sensor data
analog_n
Float
Root
No
Analog input voltage in volts. n is the sensor index from 1 to 16, e.g. analog_1, analog_2.
temperature_internal
Float
Root
No
Temperature from the built-in hardware sensor, in degrees Celsius.
temperature_n
Float
Root
No
External temperature sensor reading in degrees Celsius. n is the sensor index from 1 to 16, e.g. temperature_1, temperature_2.
humidity_internal
Float
Root
No
Relative humidity from the built-in hardware sensor, as a percentage.
humidity_n
Float
Root
No
External relative humidity sensor reading as a percentage. n is the sensor index from 1 to 16, e.g. humidity_1.
fuel_level_n
Float
Root
No
Fuel level from a fuel sensor, in liters or as a percentage. n is the sensor index from 1 to 16, e.g. fuel_level_1.
fuel_temperature_n
Float
Root
No
Fuel temperature from a fuel sensor, in degrees Celsius. n is the sensor index from 1 to 16, e.g. fuel_temperature_1.
impulse_counter_n
Integer
Root
No
Impulse counter reading. n is the counter index from 1 to 16, e.g. impulse_counter_1.
Identification data
hardware_key
String
Root
No
Driver or asset identifier, typically read via RFID, iButton, or similar method.
vin
String
Root
No
Vehicle Identification Number (VIN).
Custom data
custom_attributes
Array [Object]
Root
No
Structured custom attribute array with metadata. Requires "version": "1.1a" and a separate arrangement with Navixy.
on demand
└─ type
String
custom_attributes
Yes
Attribute name.
on demand
└─ id
Integer
custom_attributes
No
Attribute order number.
on demand
└─ value
Mixed
custom_attributes
Yes
Attribute value. Any JSON type.
on demand
└─ units
String
custom_attributes
No
Unit of measurement, e.g. rpm, percent.
on demand
Location source and accuracy
source_type identifies where the position coordinates came from. When omitted, the platform treats the location as GNSS by default. Declaring the source explicitly lets the platform apply the correct processing logic — for example, skipping satellite-count validation for LBS positions.
precision reports the estimated accuracy of the resolved coordinates in meters. It is optional but recommended for LBS and ATLAS positions, where accuracy can vary significantly. The platform can use this value to determine whether the accuracy is sufficient for a given use case.
Both fields require "version": "1.2" in the message.
The precision value of 800 indicates the resolved coordinates are accurate within approximately 800 meters.
Message example
A complete telemetry message from a GPS device with GNSS positioning:
Custom attributes
The protocol allows you to extend messages with device-specific or application-specific data that has no pre-defined attribute. Custom attributes are added directly to the root of the message object.
Any field name not listed in the attributes table above is treated as a custom attribute and passed through to the platform unchanged. Common use cases include hardware-specific telemetry fields such as avl_io_1, flex_id, or engine_rpm. This format requires no version declaration and covers most integration needs.
Structured custom attributes
For integrations that need typed metadata alongside sensor values, NGP supports an alternative format: the custom_attributes array. Each entry carries a type (attribute name), value, and optional id (ordering) and units fields. This is useful when units of measurement, attribute ordering, or typed metadata are required by the receiving system.
For most integrations, the simple custom_* format above is sufficient and preferable. Use custom_attributes only when the structured metadata is a specific requirement of your integration.
Both formats can coexist in the same message. custom_attributes requires "version": "1.1a" and a separate arrangement with Navixy — it is not available for standard integrations.
Continue reading to learn about Predefined event identifiers in Navixy Generic Protocol.
Last updated
Was this helpful?