What Verdigris measures

The Data API (v4) returns time series for the levels of the hierarchy. This page explains each measurement in plain terms and where it is available.

At a glance

Unit notes: power at breaker, panel and building level is documented in watts; the single-circuit power endpoint documents watts (real), volt-amperes (apparent) and volt-amperes-reactive (reactive).

Measurements in plain language

Energy is the total work done over a time interval, like a utility meter reading for that period. Use it for consumption, cost allocation, baselining, and measuring the effect of an HVAC change. real energy (Wh) is the energy actually consumed. apparent energy (VAh) is based on apparent power; it is not supported for the daily interval.

Power is the average rate of energy use in the interval. Use it for load shape (how demand rises and falls during the day), peak demand, and spotting when a machine turns on. Real power is what does useful work; apparent power is what the electrical system must carry; reactive power is the part that does no useful work but loads the system.

Current is the electrical current (amps) flowing through a circuit. Use it to see if a load is running and how hard, independent of voltage.

Voltage is the electrical supply level (volts) at a circuit. Use it to check supply quality and to see sags or swells.

Power factor is the ratio of useful power to apparent power, ranging from -1 to 1. Values well below 1 mean the load is drawing power inefficiently. A negative value may indicate current flowing in reverse, from sources such as solar panels or battery banks.

Total harmonic distortion (THD) measures how distorted the electrical waveform is. It is available at panel level and is used to screen for power-quality issues.

Waveforms are the raw shape of the current or voltage signal at a circuit over a time range, for deep diagnosis rather than trending.

Pro Capture events are event summaries per panel (or all panels in a building) over a time range, with the corresponding waveforms retrievable per panel. These are different from Signals events in API v3 (see Signals and Events).

Control returns time series that building management systems (BMS) report, such as a chiller temperature. Each record has a control name, a device ID and a value. This can be combined with electrical data to see how setpoints and equipment behavior relate.

Weather returns temperature (in degrees Celsius), and optionally humidity and dew point, for a building, at hourly or daily resolution. Weather forecasts cannot be requested more than 10 days into the future.

Forecast returns forecasted energy for buildings as a set of quantiles (q1, q5, q10 up to q99) for each timestamp, so you get a range of likely outcomes rather than a single number.

Time resolution

Start and end times must line up with the interval (for example, 15-minute data must start on a 15-minute boundary), and daily intervals are aligned to the building's time zone.

Other things worth knowing

• Requests can be made for one entity or in a batch for many entities at once.
• Results can be returned as JSON or CSV, with timestamps as epoch milliseconds or ISO 8601 text, optionally shown in a time zone you choose. The time zone only changes how the timestamp is displayed.
• Circuit calls offer advanced override options (override_phase, override_sensor_orientation) meant only for troubleshooting suspected wiring or sensor problems. Misuse can produce erroneous data.

Next

• Signals and Events