frequenz-api-common 0.8.4__tar.gz → 0.8.8__tar.gz

{frequenz_api_common-0.8.4 → frequenz_api_common-0.8.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frequenz-api-common
-Version: 0.8.4
+Version: 0.8.8
 Summary: Frequenz common gRPC API and bindings
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License-Expression: MIT

frequenz_api_common-0.8.8/RELEASE_NOTES.md

@@ -0,0 +1,17 @@
+# Frequenz Common API Release Notes
+
+## Summary
+
+This release includes addition a new definition of balancing group in 
+v1alpha8 and moved market location definition to the `grid` submodule.
+
+## Upgrading
+
+## New Features
+
+- Added `BalancingGroup` to 
+  "frequenz/api/common/v1alpha8/grid/balancing_group.proto"
+
+## Bug Fixes
+
+<!-- Here goes notable bug fixes that are worth a special mention or explanation -->

frequenz_api_common-0.8.8/proto/frequenz/api/common/v1alpha8/grid/balancing_group.proto

@@ -0,0 +1,24 @@
+// Frequenz definitions balancing groups.
+//
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.grid;
+
+import "frequenz/api/common/v1alpha8/grid/delivery_area.proto";
+
+// Identifies a balancing group by its market code.
+//
+// This message identifies the balancing group itself. It does not include the
+// delivery area in which the balancing group is used.
+message BalancingGroup {
+  // The balancing group code.
+  string code = 1;
+
+  // The type of market code used to identify the balancing group.
+  EnergyMarketCodeType code_type = 2;
+}

frequenz_api_common-0.8.8/proto/frequenz/api/common/v1alpha8/grid/market_location.proto

@@ -0,0 +1,141 @@
+// Frequenz definitions of market locations.
+//
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.grid;
+
+import "frequenz/api/common/v1alpha8/market/market_area.proto";
+
+// Identifies the type of external market identifier used to reference
+// a Market Location in a specific regulatory regime.
+//
+// The identifier type defines the format, validation rules, and semantics
+// of the identifier value. Jurisdictional applicability is modeled separately
+// via MarketArea.
+//
+// !!! note "Identifier regimes, not countries"
+//     Some identifier types (e.g. EAN, ESI_ID) are used across multiple
+//     jurisdictions. This enum models identifier formats, not geography.
+//
+enum MarketLocationIdType {
+  // UNSPECIFIED: Default unspecified value — must not be used.
+  MARKET_LOCATION_ID_TYPE_UNSPECIFIED = 0;
+
+  // MALO_ID: Germany – Marktlokations-ID (MaLo-ID).
+  MARKET_LOCATION_ID_TYPE_MALO_ID = 1;
+
+  // ZAEHLPUNKT: Austria – Zählpunktbezeichnung (Semantically similar to
+  // Germany’s MaLo-ID).
+  MARKET_LOCATION_ID_TYPE_ZAEHLPUNKT = 2;
+
+  // MPAN: United Kingdom – Meter Point Administration Number.
+  MARKET_LOCATION_ID_TYPE_MPAN = 3;
+
+  // POD: Italy — Point of Delivery.
+  MARKET_LOCATION_ID_TYPE_POD = 4;
+
+  // CUPS: Spain — Código Universal de Punto de Suministro.
+  MARKET_LOCATION_ID_TYPE_CUPS = 5;
+
+  // PRM: France — Point de Référence et Mesure (PRM).
+  MARKET_LOCATION_ID_TYPE_PRM = 6;
+
+  // EAN: Continental Europe (e.g. FR (legacy), NL, BE, PL, CZ, HU, ...) —
+  // European Article Number.
+  MARKET_LOCATION_ID_TYPE_EAN = 7;
+
+  // GSRN: Nordic countries (e.g., DK, SE, NO, FI) — GS1 Global Service
+  // Relation Number.
+  MARKET_LOCATION_ID_TYPE_GSRN = 8;
+
+  // ESI_ID: United States – Electric Service Identifier.
+  MARKET_LOCATION_ID_TYPE_ESI_ID = 9;
+
+  // NMI: Australia – National Metering Identifier.
+  MARKET_LOCATION_ID_TYPE_NMI = 10;
+
+  // ICP: New Zealand — Installation Control Point.
+  MARKET_LOCATION_ID_TYPE_ICP = 11;
+
+  // SPN: Japan — Supply Point Number (需要地点特定番号).
+  MARKET_LOCATION_ID_TYPE_SPN = 12;
+
+  // OTHER: Generic meter identifier for markets not modeled explicitly yet.
+  MARKET_LOCATION_ID_TYPE_OTHER = 99;
+}
+
+// Opaque identifier in its original market format as received from the
+// source system (MSCONS, DataHub, CSV, manual entry, etc.).
+//
+// The service accepts both formatted and already-normalized values.
+// Formatting characters (spaces, hyphens, prefixes) are ignored during
+// validation. Validation is performed exclusively on a canonical
+// normalized form derived from the input value, based on the type.
+//
+// Clients MUST NOT rely on formatting differences to distinguish identifiers.
+//
+// Examples:
+//   - "01234567890" (Germany MaLo)
+//   - "18 1066 1234 567 8901 234" (UK MPAN with spaces)
+//   - "NEM12-03456-A" (AU NMI with hyphens)
+message MarketLocationIdValue {
+  // Official market location identifier.
+  string value = 1;
+}
+
+// Market-standard identifier describing a Market Location.
+//
+// A Market Location is a jurisdiction-specific point of metering used for
+// regulatory processes such as settlement, billing, supplier switching,
+// balancing-group reconciliation, and DSO/TSO reporting. Different markets
+// use incompatible identifier formats—varying in length, character sets,
+// checksum rules, and decomposition.
+//
+// This message encapsulates the official, market-issued identifier used to
+// reference such a point. Examples:
+//   • Germany:  MaLo-ID (Marktlokations-ID)
+//   • UK:       MPAN (Meter Point Administration Number)
+//   • US:       ESI-ID (Electric Service Identifier)
+//   • Australia NMI (National Metering Identifier)
+//
+// Different markets use incompatible identifier formats—varying in length,
+// character sets, checksum rules, and presentation formatting (spaces,
+// hyphens, prefixes).
+//
+// !!! example "Example values for different markets"
+//     The following examples illustrate how the fields may be populated for
+//     different jurisdictions:
+//
+//     | Market:Type     | Official ID         | Normalized Value
+//     | --------------- | ------------------- | -----------------------------
+//     | DE:MALO_ID      | "12345678901"     | "12345678901"
+//     | UK:MPAN         | "18 1066 1234 567 8901 234" | "18106612345678901234"
+//     | US_ERCOT:ESI_ID | "10443720000012345" | "10443720000012345"
+//     | AU:NMI          | "NEM12-03456-A"     | "NEM1203456A"
+//
+//     In each case, `value` preserves the original format as provided by the
+//     market operator, while `normalized_value` is an implementation-specific
+//     cleaned representation suitable for validation, indexing, and
+//     comparisons.
+//
+message MarketLocationId {
+  // Official market location identifier.
+  MarketLocationIdValue id = 1;
+
+  // Identifies what type of official market identifier `id` represents.
+  MarketLocationIdType type = 2;
+}
+
+// Identifies a Market Location.
+message MarketLocationSelector {
+  // Regulatory jurisdiction in which this Market Location is registered.
+  frequenz.api.common.v1alpha8.market.MarketArea market_area = 1;
+
+  // Official market identifier (MaLo-ID, MPAN, ESI-ID, ...).
+  MarketLocationId market_location_id = 2;
+}

frequenz_api_common-0.8.8/proto/frequenz/api/common/v1alpha8/market/market_area.proto

@@ -0,0 +1,123 @@
+// Frequenz definitions of market areas.
+//
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.market;
+
+// Defines the jurisdiction in which a Market Location is registered.
+//
+// A Market Area represents the regulatory jurisdiction and market regime that
+// governs identifier formats, settlement periods, and metering conventions
+// for a Market Location.
+//
+// Identifier formats (MaLo-ID, MPAN, POD, NMI, ESI-ID, …) are modeled
+// separately in MarketLocationIdType.
+//
+// !!! note "Jurisdictions, not operators"
+//     Market areas represent regulatory regimes, not individual exchanges or
+//     TSOs. Where operator-specific behavior matters (e.g. ERCOT vs PJM),
+//     dedicated sub-areas are defined.
+//
+// !!! note "Numeric ranges"
+//     Enum values are grouped by region to preserve ordering, readability,
+//     and backwards-compatible extension.
+//
+enum MarketArea {
+  // UNSPECIFIED: Default unspecified value — must not be used.
+  MARKET_AREA_UNSPECIFIED = 0;
+
+  // ---------------------------------------------------------------------------
+  // Europe [100..199]
+  // ---------------------------------------------------------------------------
+
+  // EU_DE: Germany — MaLo-ID regime (Marktlokation / MaLo-ID).
+  MARKET_AREA_EU_DE = 101;
+
+  // EU_UK: United Kingdom — MPAN regime (Meter Point Administration Number).
+  MARKET_AREA_EU_UK = 102;
+
+  // EU_FR: France — PDL/PRM regime (Point de Livraison/Référence Mesure).
+  MARKET_AREA_EU_FR = 103;
+
+  // EU_IT: Italy — POD regime (Point of Delivery).
+  MARKET_AREA_EU_IT = 104;
+
+  // EU_ES: Spain — CUPS regime (Código Universal de Punto de Suministro).
+  MARKET_AREA_EU_ES = 105;
+
+  // EU_NL: Netherlands — EAN regime (European Article Number).
+  MARKET_AREA_EU_NL = 106;
+
+  // EU_BE: Belgium — EAN regime.
+  MARKET_AREA_EU_BE = 107;
+
+  // EU_CH: Switzerland — EAN regime.
+  MARKET_AREA_EU_CH = 108;
+
+  // EU_AT: Austria — Zählpunktnummer (EAN-based).
+  MARKET_AREA_EU_AT = 109;
+
+  // EU_NORDICS: Nordic region — Elhub / GSRN regime (NO, SE, DK, FI).
+  MARKET_AREA_EU_NORDICS = 110;
+
+  // ---------------------------------------------------------------------------
+  // Asia Pacific [200..299]
+  // ---------------------------------------------------------------------------
+
+  // AP_JP: Japan — country-specific metering / settlement regime.
+  MARKET_AREA_AP_JP = 201;
+
+  // AP_CN: China — country-specific metering / settlement regime.
+  MARKET_AREA_AP_CN = 202;
+
+  // AP_IN: India — country-specific metering / settlement regime.
+  MARKET_AREA_AP_IN = 203;
+
+  // AP_SG: Singapore — country-specific metering / settlement regime.
+  MARKET_AREA_AP_SG = 204;
+
+  // ---------------------------------------------------------------------------
+  // North America [300..399]
+  // ---------------------------------------------------------------------------
+
+  // NA_US_ERCOT: United States — ERCOT regime (ESI-ID).
+  MARKET_AREA_NA_US_ERCOT = 301;
+
+  // NA_US_PJM: United States — PJM regime (ESI-ID).
+  MARKET_AREA_NA_US_PJM = 302;
+
+  // NA_US_ISONE: United States — ISO New England regime (ESI-ID).
+  MARKET_AREA_NA_US_ISONE = 303;
+
+  // NA_US_CAISO: United States — CAISO regime (ESI-ID).
+  MARKET_AREA_NA_US_CAISO = 304;
+
+  // ---------------------------------------------------------------------------
+  // Eurasia [400..499]
+  // ---------------------------------------------------------------------------
+
+  // EURASIA_RU: Russia — country-specific metering / settlement regime.
+  MARKET_AREA_EURASIA_RU = 401;
+
+  // ---------------------------------------------------------------------------
+  // Oceania [500..599]
+  // ---------------------------------------------------------------------------
+
+  // OC_AU: Australia — NMI regime (National Metering Identifier).
+  MARKET_AREA_OC_AU = 501;
+
+  // OC_NZ: New Zealand — ICP regime (Installation Control Point).
+  MARKET_AREA_OC_NZ = 502;
+
+  // ---------------------------------------------------------------------------
+  // Other / not yet modelled [900..999]
+  // ---------------------------------------------------------------------------
+
+  // OTHER: Other or not yet modelled areas.
+  MARKET_AREA_OTHER = 999;
+}

{frequenz_api_common-0.8.4 → frequenz_api_common-0.8.8}/py/frequenz_api_common.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frequenz-api-common
-Version: 0.8.4
+Version: 0.8.8
 Summary: Frequenz common gRPC API and bindings
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License-Expression: MIT

{frequenz_api_common-0.8.4 → frequenz_api_common-0.8.8}/py/frequenz_api_common.egg-info/SOURCES.txt

@@ -46,10 +46,13 @@ proto/frequenz/api/common/v1alpha7/streaming/event.proto
 proto/frequenz/api/common/v1alpha7/type/decimal.proto
 proto/frequenz/api/common/v1alpha7/type/interval.proto
 proto/frequenz/api/common/v1alpha7/type/location.proto
+proto/frequenz/api/common/v1alpha8/grid/balancing_group.proto
 proto/frequenz/api/common/v1alpha8/grid/delivery_area.proto
 proto/frequenz/api/common/v1alpha8/grid/delivery_duration.proto
+proto/frequenz/api/common/v1alpha8/grid/market_location.proto
 proto/frequenz/api/common/v1alpha8/gridpool/gridpool.proto
 proto/frequenz/api/common/v1alpha8/market/energy.proto
+proto/frequenz/api/common/v1alpha8/market/market_area.proto
 proto/frequenz/api/common/v1alpha8/market/power.proto
 proto/frequenz/api/common/v1alpha8/market/price.proto
 proto/frequenz/api/common/v1alpha8/metrics/bounds.proto

frequenz_api_common-0.8.4/RELEASE_NOTES.md

@@ -1,9 +0,0 @@
-# Frequenz Common API Release Notes
-
-## Summary
-
-This release includes a bug fix for a typo in the enum `v1alpha8::microgrid::electrical_components::ElectricalComponentOperationalMode`.
-
-## Bug Fixes
-
-- A typo in the enum `v1alpha8::microgrid::electrical_components::ElectricalComponentOperationalMode` has been fixed. The variant `ELECTRICAL_COMPONENT_OPERATIONAL_MODE_TELEMTRY` has been renamed to `ELECTRICAL_COMPONENT_OPERATIONAL_MODE_TELEMETRY`.