Skip to content

Protocol Documentation¤

Table of Contents¤

Top

frequenz/api/common/v1alpha8/grid/provision_duration.proto¤

ProvisionPeriod¤

Represents the time period during which the flexibility market contract is delivered.

This defines the contractual length of a provision period. Valid start times are determined by the combination of duration, flexibility service, delivery area, and market-specific rules

Field Type Label Description
start_time google.protobuf.Timestamp Start UTC timestamp representing the beginning of the provision period.

This timestamp is inclusive. The end of the provision period is derived from start_time and duration.

!!! note "Start Time Constraints" The start time must align with the provision duration and the market rules for the selected FlexServiceType and delivery area.

Unless stricter market-specific rules apply, the following default alignment is used:

  • 15-minute durations must start at :00, :15, :30, or :45. - 30-minute durations must start at :00 or :30. - 60-minute durations must start at :00 past the hour. - 120-minute durations must start on an even UTC hour (00:00, 02:00, 04:00, ...). - 240-minute durations must start on a UTC hour divisible by 4 (00:00, 04:00, 08:00, 12:00, ...). - 1440-minute durations must start at the daily boundary defined by the relevant market rules for the selected delivery area. If no market-specific rule applies, this defaults to 00:00 UTC.

Market-specific rules may further restrict valid start times. For example, a 4-hour product may only support predefined auction blocks, and a full-day product may follow the delivery-day definition of the relevant market. | | duration | ProvisionDuration | | The length of the provision period. |

ProvisionDuration¤

Defines standard provision durations for flexibility services.

A provision duration is the duration of a single provision period. In many markets, this corresponds to the delivery block or service interval for which a flexibility service is contracted, committed, or delivered.

Provision durations are modeled as an enum because only a fixed set of provision periods is supported by the relevant services, markets, and operator integrations. This makes invalid durations unrepresentable and keeps validation behavior consistent across APIs.

!!! note "Duration vs. resolution" This field defines the duration of a single provision period. In market terms, this is often the delivery block or product block for the flexibility service. It does not define the cadence or resolution of telemetry samples, control instructions, or setpoint updates.

Name Number Description
PROVISION_DURATION_UNSPECIFIED 0 UNSPECIFIED: Default value — must not be used in production messages.
PROVISION_DURATION_5_MIN 1 5_MIN: 5-minute delivery window (planned for future reconstruction of ancillary service markets).
PROVISION_DURATION_15_MIN 2 15_MIN: 15-minute delivery window (common in balancing energy markets and secondary regulation).
PROVISION_DURATION_30_MIN 3 30_MIN: 30-minute delivery block (used in some scheduling or redispatch services).
PROVISION_DURATION_60_MIN 4 60_MIN: Hourly provision period (e.g., for day-ahead markets or system dispatch).
PROVISION_DURATION_120_MIN 5 120_MIN: 2-hour blocks, less commonly used but possible in some markets.
PROVISION_DURATION_240_MIN 6 240_MIN: 4-hour block (e.g., German and EU primary regulation tenders).
PROVISION_DURATION_1440_MIN 7 1440_MIN: Full-day delivery period (e.g., capacity or commitment-based products).

Scalar Value Types¤

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)