15.7. Billing Data

GEISA Application Programming Interface

15.7.1. Summary

Billing Data defines meter-register-style metered quantities that are distinct from the continuous Instantaneous Data stream and from Waveform Data. The schema-level billing payload is GeisaBillingQuantities.

Billing quantities cover accumulated summations and demand-oriented register values used for billing or interval accounting use cases.

15.7.2. Billing Data Broadcast

Platforms that support Billing Data publish billing snapshots on:

  • geisa/api/billing/data

The payload is GeisaBillingQuantities. Billing Data is a platform-to- application snapshot stream rather than a high-rate continuous feed. Publication cadence is platform-specific and may reflect meter register update timing, billing or interval windows, demand interval closure, or platform policy.

Applications MUST use payload timestamps and measurement metadata to interpret the billing window or demand interval. Applications MUST NOT infer billing window boundaries solely from MQTT delivery time.

This version defines the Billing Data broadcast topic and payload. It does not define a Billing Data request/response transaction, historical query, application-selected billing interval, or socketed stream.

15.7.3. Billing Payload Model

GeisaBillingQuantities is the outer billing payload. It contains:

  • summation_total as GeisaBillingQuantities_Summation_Total

  • demand_total as GeisaBillingQuantities_Demand_Total

summation_total carries energy and related interval/window-qualified billing quantities such as delivered, received, summed, net, reactive, quadrant-qualified, and apparent-energy values where defined.

demand_total carries maximum-demand style quantities using GeisaTypeMaxDemand. Each max-demand value combines:

  • max-demand-time-us for the recorded maximum-demand timestamp

  • quantity for the fixed-point quantity value

The demand model is used for active, reactive, and apparent demand quantities where defined by the schema.

15.7.4. Value Semantics

  • timestamp-us values use UTC Unix epoch time in microseconds.

  • Electrical integer quantities use the fixed-point micro-unit encoded by each field name.

  • GeisaTypeMeasurementMetadata describes the averaging or integration window and is not the publication cadence.

  • Power factor values are unsigned magnitudes in the range 0.0 through 1.0.

  • Direction and quadrant context comes from active/reactive quantities, power-factor angle fields, and quadrant-qualified field names rather than from power-factor sign.

  • Reactive energy and reactive demand include Q1, Q2, Q3, Q4, and combined quadrant fields where defined.

  • Apparent energy and apparent demand distinguish arithmetic and vectorial quantities where defined.

  • Billing quantities remain separate from instantaneous scalar values and waveform data.

Note

Some jurisdictions, including Canada, may prefer or require vectorial calculations for selected aggregate billing quantities. The GEISA billing payload uses explicit arithmetic and vectorial field names where both calculation methods are defined, so applications can distinguish the calculation basis from the field name rather than relying on a global stream-level setting.

15.7.5. Profile and Example

The maintained schemas repository includes a billing profile overlay and example payload for this model:

  • profiles/geisa-metered-quantities-billing-profile.json

  • examples/metered-quantities-billing-profile-example.json

The current billing profile requires a billing payload with both summation-total and demand-total sections. The required baseline includes delivered active-energy summation, delivered active-power demand, and measurement-period-s metadata for both sections.

15.7.6. MQTT Details

  • QoS: 0 / Unacknowledged

  • Topic: geisa/api/billing/data

15.7.7. API Permissions

  • Application:

    • Subscribe: geisa/api/billing/data

  • Platform:

    • Publish: geisa/api/billing/data

15.7.8. Transaction Data

  • GeisaBillingQuantities

  • GeisaBillingQuantities_Summation_Total

  • GeisaBillingQuantities_Demand_Total

  • GeisaTypeMaxDemand

  • GeisaTypeMeasurementMetadata

As defined in https://github.com/geisa/schemas

GEISA Pyramid