How Verdigris models a building
Buildings, panels, breakers, circuits, and how each one feeds the next.
The v3 API describes the physical electrical layout of each site. If you are building a digital twin, this is the skeleton you hang everything else on.
What you can learn about each level
| Level | What v3 tells you |
|---|---|
| Account (organization) | Name and identifiers. |
| Building | Name, slug (a readable identifier), address, geographic location, time zone, floor area and its unit, industry, mains supply frequency, and the top-level panels. |
| Panel | Name, notes, mains supply voltage and phase configuration (1ph, 1ph3w, or 3ph), the panel's current metering status, the breaker that feeds it (its upstream breaker), the panels it feeds (downstream panels), and the gateways attached to it. |
| Breaker | Name, size, whether it is active, the panel it belongs to, and its circuits. |
| Circuit | The phase (A, B, or C) and whether it is active. |
| Data gateway | Serial number, which panel and building it is on, lifecycle state, hardware version and model, connection state, and which sensor channel is attached to which circuit. |
How it maps to a digital twin
- Panel tree: a building lists its top-level panels; each panel lists its downstream panels. Walking that nesting reproduces the electrical distribution tree, from the service entrance down to sub-panels.
- Feeds: a panel's upstream breaker tells you which breaker in the parent panel feeds it, so you can connect panels to the exact breaker, not just to the parent panel.
- Loads: breakers and their circuits are the metered points where loads connect. The phase on each circuit tells you how load is distributed across phases.
- Metering provenance: a gateway can list channel-to-circuit attachments (with clamp size), which tell you which physical sensor produces the data for which circuit. This field is optional and is not always returned.
- Building context: time zone, location, floor area, and industry are useful for normalizing (for example energy per area) and for aligning with weather.
Is the data live or static?
Topology is configuration, not telemetry: it changes when equipment is added, moved, or re-configured. Panels also carry a metering status over time, one of planned, not_metered, active, suspended, archived, or deleted, with a start time, optional end time, and reason. Use it to know whether a panel's data should be expected, and to interpret gaps.
Health of the metering hardwareGateways expose connection and data-health fields (for example
isConnected,lastDataTimestamp,dataUptime24H,dataLatencyMinutes), and a summary view aggregates them across gateways. Use these to distinguish "the equipment is idle" from "the meter is not reporting".
Identifiers
Buildings, panels, breakers and circuits each have a text nanoid and an integer oldid. Buildings can also be addressed by slug. Measurement calls in the Data API use integer IDs.
Topology is read-only
The Verdigris API v3 is read-only. This API only reads topology; it cannot change it. Topology changes over time as equipment is added or re-configured, so re-read it on a schedule to pick up changes.
Next
Updated 27 days ago