The services API is the third sibling domain alongside overhead and underground. It accepts a Universal Service Model (USM) — a typed representation of a transformer source, secondary segments, and service-drop tree — and runs five analysis pillars on it. Each pillar exposes two endpoints: a pure-physics calculator and a compliance check that joins utility-staged limits with regulatory floors.

Endpoints

POST /voltage-drop

Computes per-segment and cumulative voltage drop on a service-drop tree using Ohm’s law with power-factor correction. Returns per-segment drop percentages and a cumulative drop from the transformer to each service point.

curl https://$VERTICAL_AI_BASE_URL/services/voltage-drop \
  -H "Authorization: Bearer $VERTICAL_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "usm": { ... },
    "power_factor": 0.90
  }'

POST /voltage-drop/check

Joins the voltage-drop result with utility-staged service_voltage_drop_limits rules and ANSI C84.1 Range A / Range B floors. Returns a pass | fail verdict per service point, with the governing rule cited. Falls back to Range A 5% when no utility rule is staged.

POST /flicker

Estimates motor-start flicker as ΔV/V at the distribution bus from locked-rotor inrush current and system short-circuit MVA. Returns the flicker magnitude for the given motor starting repetition rate.

POST /flicker/check

Classifies the computed ΔV/V against the IEEE 1453 / GE flicker visibility curve as imperceptible, borderline, or objectionable. Also checks IEC 61000-3-7 short-term Pst and long-term Plt planning levels.

POST /transformer-thermal

Sums the downstream service-point loads on the USM, passes the aggregate to the transformer’s thermal model, and returns hottest-spot temperature (°C), loading condition tier per IEEE C57.91, and the Arrhenius F_AA loss-of-life accelerator for the current loading condition.

POST /transformer-thermal/check

Applies per-utility thermal limits (if staged) against the IEEE C57.91 110 °C hottest-spot design point. Returns pass | fail with the applicable loading tier.

POST /phase-balance

Sums load per phase across all service points on the USM and computes NEMA MG 1 % voltage unbalance for three-phase and split-phase systems. Returns per-phase kVA contributions, the unbalance percentage, and a greedy reassignment plan that suggests service-to-leg moves to flatten the secondary.

The reassignment plan is a reviewed proposal, not a mutation — the caller’s USM is never modified.

POST /phase-balance/check

Flags % unbalance above the NEMA MG 1 threshold (3% three-phase, 10% split-phase by default). Returns existing verdict and the proposed-improvement verdict side by side so the caller can decide whether to accept the reassignment.

POST /route-optimize

Runs Prim’s minimum-spanning-tree (MST) algorithm over the service-point lat/lon coordinates to produce the minimum-length secondary route from a transformer through every service point. Optionally runs /voltage-drop on the recommended topology before returning so conductor upsizing decisions can be made from real numbers.

{
  "source": { "lat": 37.78, "lon": -122.41 },
  "service_points": [
    { "id": "sp-01", "lat": 37.7802, "lon": -122.4108, "load_kva": 8.5 },
    { "id": "sp-02", "lat": 37.7805, "lon": -122.4115, "load_kva": 12.0 }
  ],
  "conductor": "1/0 AAC",
  "check_voltage_drop": true
}

Universal Service Model

All endpoints consume and produce the same USM shape — a typed, normalized representation of:

  • transformer_source — kVA rating, impedance, primary/secondary voltage, X/R ratio
  • secondary_segments[] — conductor spec, length, impedance per unit length, from/to node IDs
  • service_drops[] — connected service point, conductor, load kVA, power factor, phase assignment, service entrance voltage

The USM is the service-side sibling to the Universal Pole Model (overhead) and Universal Vault Model (underground). A ServiceNetworkRef on a UPM links the pole-side transformer to the downstream USM so engineers walking from a pole into its services keep full engineering context.

Standards

StandardPillar
ANSI C84.1-2016Voltage drop — Range A ±5% / Range B ±10% at service entrance
IEEE 1453-2015 / IEC 61000-3-7Flicker — visibility curve + Pst 1.0 / Plt 0.65 planning levels
IEEE C57.91-2011Transformer thermal — hottest-spot model + Arrhenius loss-of-life
NEMA MG 1Phase balance — 3% three-phase / 10% split-phase unbalance thresholds
NEC Article 220 / 230Load calculation and service entrance references

Regulatory floors apply when no utility rule is staged. Per-utility service_voltage_drop_limits entries (ingested via the Standards API) override the floors where they are tighter.

See also