Skip to content

Physical Properties

Every measured quantity exposed by our APIs — in equipment metadata, device channels, alarms, and measurement messages — is described by three fields, always used together:

  • physical_value — the pure physical property being measured, as you'd find it described in a science textbook (e.g. Temperature, Humidity).
  • physical_extension — describes what is measured more precisely, if the sensor hardware can determine it. When the hardware has no further detail about what it's measuring (e.g. a general-purpose temperature sensor that doesn't know whether it's in air, water, or a product), the extension is Unknown. Realtime API alarm messages name this field physical_value_extension.
  • physical_unit — the unit the value is expressed in (e.g. °C, %rF).

Across current endpoints and message types, each physical_value/physical_extension pair has a single, consistent meaning, so no per-property special-casing is needed. Legacy endpoints use some different combinations — see the note below.

Mapping Table

physical_value physical_extension physical_unit What it measures
Temperature Unknown °C or °F General-purpose temperature.
Temperature Product Temperature °C or °F Temperature measured in or on a product (e.g. food), rather than the surrounding air.
Temperature Dew Point °C or °F The temperature at which moisture in the air starts to condense.
Humidity Unknown %rF Relative humidity — how much moisture the air holds as a percentage of what it can hold at that temperature.
Density Absolute Humidity g/m³ Absolute humidity — the actual mass of water vapor per cubic meter of air, independent of temperature.
Unknown Door Contact number Whether a monitored door or lid is open or closed.
Irradiance Unknown mW/m² The intensity of radiant energy, such as sunlight, hitting a surface.
Flue gas values CO2 carbon dioxide ppm Carbon dioxide (CO2) concentration in flue gas, in parts per million.
Pressure Absolute Pressure hPa Absolute air or gas pressure, not adjusted for altitude or a reference value.
Illuminance Unknown lx The intensity of light as perceived by the human eye.
Illuminance sum Unknown Lxh Total light exposure accumulated over a period of time.

Legacy Endpoint Naming

Some legacy endpoints use different physical_value/physical_extension combinations than the ones documented above:

  • Temperature - Air Temperature (legacy) is equivalent to Temperature - Unknown (current endpoints).
  • Door - Door Contact (legacy) is equivalent to Unknown - Door Contact (current endpoints).

De-duplicate and normalize these combinations when migrating from legacy to current endpoints.