Metering API v2 (Alpha)¶

Consumptions¶

Retrieve consumptions.

CalculateConsumption¶

Calculate the consumption for a contract in a specific period and a obis code selector.

Input: CalculateConsumptionRequest¶

Field	Type	Rules	Description
*tenant¶	string		The tenant.
*contract¶	string		The contract ID.
*period¶	enpowerx.types.Period		The period in which the consumption is valid in.
*obis_codes¶	string		The OBIS code/s of the consumption point to be considered, represented by a regular expression. If multiple consumptions match the period and obis codes, the `aggregation` method must be specified.
aggregation¶	Aggregation		The aggregation function of the consumption value. This aggregation is only applied if multiple consumptions match the period and obis codes.
time_slices¶	string	repeated	The time slices of the consumption needs to respect. A time slice is specified in the following format: "(hh:mm-hh:mm)@[DAY,...]". This is an example of a time slice containing the entire week: (00:00-23-59)@[MON,TUE,WED,THU,FRI,SAT,SUN].
purpose¶	Purpose		The purpose the consumption used for (defaults to `BILLING`).

Output: CalculateConsumptionResponse¶

Field	Type	Description
consumption¶	Consumption	The consumption.
unit¶	string	The consumption's unit (eg. "kWh").
period¶	enpowerx.types.Period	The period in which the consumption is valid in.

CalculateConsumptionSeries¶

Calculate the consumption series for a contract in a specific period and a obis code selector.

Input: CalculateConsumptionSeriesRequest¶

Field	Type	Rules	Description
*tenant¶	string		The tenant.
*contract¶	string		The contract ID.
*period¶	enpowerx.types.Period		The period in which the consumption is valid in.
*obis_codes¶	string		The OBIS code/s of the consumption point to be considered, represented by a regular expression. If multiple consumptions match the period and obis codes, the `aggregation` method must be specified.
aggregation¶	Aggregation		The aggregation function of the consumption value. This aggregation is only applied if multiple consumptions match the resolution and obis codes.
time_slices¶	string	repeated	The time slices of the consumption needs to respect. A time slice is specified in the following format: "(hh:mm-hh:mm)@[DAY,...]". This is an example of a time slice containing the entire week: (00:00-23-59)@[MON,TUE,WED,THU,FRI,SAT,SUN].
purpose¶	Purpose		The purpose the consumption used for (defaults to BILLING).
resolution¶	google.protobuf.Duration		The time resolution between two consecutive consumption values (defaults to 15min).
weighting¶	CalculateConsumptionSeriesRequest.Weighting		The weighting of the consumption series' values (defaults to `MEAN`).

Output: ConsumptionSeries¶

Field	Type	Rules	Description
consumptions¶	Consumption	repeated	The consumption series' values.
unit¶	string		The consumption's unit (eg. "kWh").
period¶	enpowerx.types.Period		The period in which the consumption is valid in.
resolution¶	google.protobuf.Duration		The time resolution between two consecutive consumption values.

Consumption¶

Field	Type	Description
value¶	enpowerx.types.Decimal	The consumption's value.
billable¶	bool	Indicates if the consumption is billable.
annotations¶	google.protobuf.Struct	The consumption's annotations.
quality¶	Consumption.Quality	The quality of the consumption value.

Aggregation¶

Name	Number	Description
AGGREGATION_UNSPECIFIED	0	The aggregation is unspecified.
INTEGRAL	1	The value is integrated over time. The resulting time unit is `hour`. The signals sampling rate will be respected.
MEAN	2	The value is the mean of the retrieved values.
MEDIAN	3	The value is the median of the retrieved values.
MAXIMUM	4	The value is the maximum of the retrieved values.
MINIMUM	5	The value is the minimum of the retrieved values.
SUM	6	The value is the sum of the retrieved values.

CalculateConsumptionSeriesRequest.Weighting¶

Name	Number	Description
WEIGHTING_UNSPECIFIED	0	The weighting is unspecified.
MEAN	1	The values are weighted according to their mean value.
SLP_H0	2	The values are weighted according to the SLP-H0 profile.

Consumption.Quality¶

Name	Number	Description
QUALITY_UNSPECIFIED	0	The quality is unspecified.
I	1	The consumption is incurred.
P	2	The consumption is a preliminary.
E	3	The consumption is estimated.
M	4	The consumption is missing.

Purpose¶

Name	Number	Description
PURPOSE_UNSPECIFIED	0	The purpose is unspecified.
BILLING	1	The consumption is used for billing.
SIMULATION	2	The consumption is used for simulation.
PROJECTION	3	The consumption is used for projection.
INSTALLMENT	4	The consumption is used for installment plan calculation.

Contracts¶

Manage metering related contract information.

Get¶

Fetch a contract.

Output: Contract¶

Field	Type	Description
*tenant¶	string	The tenant the contract belongs to.
*id¶	string	The contract's ID in the tenant's scope.
market_location¶	MarketLocation	The market location.

ActiveEnergy¶

Field	Type	Rules	Description
*quantity¶	enpowerx.types.Quantity		The quantity value.
*period¶	enpowerx.types.DateRange		The period in which it is valid.

DeliveryAddress¶

Field	Type	Description
*region¶	string	The region the address is located in as a CLDR region code. Example: `DE` for Germany
*postal_code¶	string	A postal code of the city (a city may have more than one). Example: `76131` for Karlsruhe inner city
*city¶	string	The canonical name of the city (there may be more than one per postal code). Example: `Karlsruhe`
*street¶	string	The canonical name of the street. Example: `Kaiserstr.`
*house_number¶	string	The house number. Examples: `32`, `32a`, `32/1`

ElectricityCharacteristics¶

Field	Type	Rules	Description
*delivery_voltage¶	ElectricityCharacteristics.DeliveryVoltage		The delivery voltage at the market location.
*measuring_voltage¶	ElectricityCharacteristics.MeasuringVoltage		The measuring voltage at the market location.

GasCharacteristics¶

Field	Type	Description
*meter_type¶	GasCharacteristics.MeterType	The meter type of the market location.
*meter_size¶	GasCharacteristics.MeterSize	The meter size of the market location.
*pressure¶	GasCharacteristics.Pressure	The pressure used.
*reading_interval¶	GasCharacteristics.ReadingInterval	The interval at which the meter is read.

MarketLocation¶

Field	Type	Rules	Description
*id¶	string		The ID of the market location.
*grid_operator¶	string		The grid operator of the market location.
meter_operator¶	string		The meter operator of the market location.
*address¶	DeliveryAddress		The delivery address of the market location.
*energy_type¶	enpowerx.types.EnergyType		The energy type of the market location.
power_values¶	PowerValue	repeated	Maximum power values communicated by the grid operator.
active_energy¶	ActiveEnergy		Active Energy communicated by the grid operator.
*initial_consumption¶	MarketLocation.InitialConsumption		The initial consumption of the market location.
*history¶	MarketLocation.HistoryEntry	repeated	The history of the market location.

MarketLocation.HistoryEntry¶

Field	Type	Rules	Description
*period¶	enpowerx.types.DateRange		The period of the configuration.
concession_fee_group¶	MarketLocation.ConcessionFeeGroup		The concession fee group of the market location.
*hardware¶	string	repeated	The hardware installed at the market location.
electricity¶	ElectricityCharacteristics		Electricity related data.
gas¶	GasCharacteristics		Gas related data.

MarketLocation.InitialConsumption¶

Field	Type	Rules	Description
*quantity¶	enpowerx.types.Quantity		The quantity of the initial consumption.
*period¶	enpowerx.types.DateRange		The period in which it is valid.

PowerValue¶

Field	Type	Rules	Description
*quantity¶	enpowerx.types.Quantity		The quantity value.
*month_of_year¶	enpowerx.types.MonthOfYear		Month and year to which the value belongs.

ElectricityCharacteristics.DeliveryVoltage¶

Name	Number	Description
DELIVERY_VOLTAGE_UNSPECIFIED	0	The delivery voltage is unspecified.
DELIVERY_VOLTAGE_LOW	1	The delivery voltage is low.
DELIVERY_VOLTAGE_MEDIUM_TO_LOW_TRANSFORMATION	2	The delivery voltage is transformed from medium voltage to low voltage.
DELIVERY_VOLTAGE_MEDIUM	3	The delivery voltage is medium.
DELIVERY_VOLTAGE_HIGH_TO_MEDIUM_TRANSFORMATION	4	The delivery voltage is transformed from high voltage to medium voltage.
DELIVERY_VOLTAGE_HIGH	5	The delivery voltage is high.

ElectricityCharacteristics.MeasuringVoltage¶

Name	Number	Description
MEASURING_VOLTAGE_UNSPECIFIED	0	The measuring voltage is unspecified.
MEASURING_VOLTAGE_LOW	1	The measuring voltage is low.
MEASURING_VOLTAGE_MEDIUM	2	The measuring voltage is medium.
MEASURING_VOLTAGE_HIGH	3	The measuring voltage is high.

GasCharacteristics.MeterSize¶

Name	Number	Description
METER_SIZE_UNSPECIFIED	0	The meter size is unspecified.
METER_SIZE_G10	1	The meter size is G10.
METER_SIZE_G100	2	The meter size is G100.
METER_SIZE_G1000	3	The meter size is G1000.
METER_SIZE_G10000	4	The meter size is G10000.
METER_SIZE_G12500	5	The meter size is G12500.
METER_SIZE_G16	6	The meter size is G16.
METER_SIZE_G160	7	The meter size is G160.
METER_SIZE_G1600	8	The meter size is G1600.
METER_SIZE_G16000	9	The meter size is G16000.
METER_SIZE_G25	10	The meter size is G25.
METER_SIZE_G250	11	The meter size is G250.
METER_SIZE_G2500	12	The meter size is G2500.
METER_SIZE_G4	14	The meter size is G4.
METER_SIZE_G40	15	The meter size is G40.
METER_SIZE_G400	16	The meter size is G400.
METER_SIZE_G4000	17	The meter size is G4000.
METER_SIZE_G6	18	The meter size is G6.
METER_SIZE_G65	19	The meter size is G65.
METER_SIZE_G650	20	The meter size is G650.
METER_SIZE_G6500	21	The meter size is G6500.

GasCharacteristics.MeterType¶

Name	Number	Description
METER_TYPE_UNSPECIFIED	0	The meter type is unspecified.
METER_TYPE_DIAPHRAGM	1	The meter is a diaphragm gas meter (DE: Balgengaszähler).
METER_TYPE_ROTARY_DISPLACEMENT	2	The meter is a rotary displacement gas meter (DE: Drehkolbengaszähler).
METER_TYPE_TURBINE	3	The meter is a turbine gas meter (DE: Turbinenradgaszähler).
METER_TYPE_ULTRASONIC	4	The meter is an ultrasonic gas meter (DE: Ultraschallgaszähler).

GasCharacteristics.Pressure¶

Name	Number	Description
PRESSURE_UNSPECIFIED	0	The pressure is unspecified.
PRESSURE_LOW	1	The pressure is low.
PRESSURE_MEDIUM	2	The pressure is medium.
PRESSURE_HIGH	3	The pressure is high.

GasCharacteristics.ReadingInterval¶

Name	Number	Description
READING_INTERVAL_UNSPECIFIED	0	The reading interval is unspecified.
READING_INTERVAL_HOURLY	1	The reading interval is hourly.
READING_INTERVAL_TWO_TIMES_A_DAY	2	The reading interval is two times per day.
READING_INTERVAL_THREE_TIMES_A_DAY	3	The reading interval is three times per day.

MarketLocation.ConcessionFeeGroup¶

Name	Number	Description
CONCESSION_FEE_GROUP_UNSPECIFIED	0	The concession fee group is unspecified.
CONCESSION_FEE_GROUP_KAS	1	The concession fee group is KAS (DE: "Sonderregelung"). For all special provisions of concession agreements that are not included in the system of the concession fee ordinance.
CONCESSION_FEE_GROUP_SA	2	The concession fee group is SA (DE: "Sondervertragskunde"). Special contract customers < 1 kV according to § 2 (7) and > 1 kV, price according to § 2 (3) (for electricity 0,11 ct/kWh and for gas 0,03 ct/kWh).
CONCESSION_FEE_GROUP_SAS	3	The concession fee group is SAS (DE: "Sondervertragskunde mit abweichendem Preis"). Marking that there is a different price for special contract customers.
CONCESSION_FEE_GROUP_TA	4	The concession fee group is TA (DE: "Tarifkunde"). Tariff customers, for electricity § 2. (2) 1b HT or ET (high concession fee) and for gas § 2 (2) 2b.
CONCESSION_FEE_GROUP_TAS	5	The concession fee group is TAS (DE: "Tarifkunde mit abweichendem Preis"). Marking that there is a different price for tariff customers.
CONCESSION_FEE_GROUP_TK	6	The concession fee group is TK (DE: "Tarifkunde mit ausschließlicher Nutzung von Gas zum Kochen und zur Warmwassererzeugung"). For gas according to concession fee ordinance § 2 (2) 2a for exclusive use for cooking and hot water production.
CONCESSION_FEE_GROUP_TKS	7	The concession fee group is TKS (DE: "Tarifkunde mit anderem Preis"). Marking if another price is to be used according to concession fee ordinance § 2 (2) 2a.

Meters¶

Manage energy meters (a.k.a counters).

List¶

List meters associated with a specific contract.

Input: MeterListRequest¶

Field	Type	Description
*tenant¶	string	The tenant to list meters for.
*contract¶	string	The ID of the contract to list meters for.
active_only¶	bool	Only return currently active meters.

Output: MeterList¶

Field	Type	Rules	Description
meters¶	Meter	repeated	A list of readings sorted anti-chronologically (newest first).

ListMine¶

List meter meters associated with a specific contract of the current customer (identity from OAuth token).

Input: MeterListRequest¶

Field	Type	Description
*tenant¶	string	The tenant to list meters for.
*contract¶	string	The ID of the contract to list meters for.
active_only¶	bool	Only return currently active meters.

Output: MeterList¶

Field	Type	Rules	Description
meters¶	Meter	repeated	A list of readings sorted anti-chronologically (newest first).

GetFromToken¶

Get a specific meter by using a generated one time token.

Input: MeterGetFromTokenRequest¶

Field	Type	Rules	Description
*tenant¶	string		The tenant the meter belongs to.
*token¶	string		A one time token for a specific meter.

Output: MeterTokenContext¶

Field	Type	Description
*meter¶	Meter	The meter received from the token.
*energy_type¶	enpowerx.types.EnergyType	The kind of the energy measured by the meter.
contract¶	string	The ID of the contract the meter belongs to.
customer¶	string	The ID of the customer the meter belongs to.

Meter¶

Field	Type	Rules	Description
*tenant¶	string		The tenant the meter belongs to.
*id¶	string		The meter number in the tenant's scope.
*active_range¶	enpowerx.types.DateRange		The date range when the meter was active. `end` is unset if the meter is currently active.
*registers¶	Meter.RegistersEntry	repeated	A map of registers with OBIS codes as the key.
*type¶	MeterType		The type of the meter.
*data_acquisition_type¶	DataAcquisitionType		The data-acquisition-type of the meter.

Meter.Register¶

Field	Type	Description
*type¶	RegisterType	The type of the register.
*units_digits¶	int32	The number of digits the register has before the decimal point.
*decimal_digists¶	int32	The number of digits the register has after the decimal point.

Meter.RegistersEntry¶

Field	Type	Rules	Description
key¶	string
value¶	Meter.Register

DataAcquisitionType¶

Name	Number	Description
DATA_ACQUISITION_TYPE_UNSPECIFIED	0	Type is not specified
REMOTE_READABLE_METER	1	Remote readable meter (AMR)
MANUAL_READABLE_METER	2	Manual readable meter (MMR)

MeterType¶

Name	Number	Description
METER_TYPE_UNSPECIFIED	0	Type is not specified
ANALOG_HOUSEHOLD_METER	1	Analog household meter (AHZ)
MODERN_MEASUREMENT_DEVICE	2	Modern measurement device (MME)
ELECTRONIC_HOUSEHOLD_METER	3	Electronic household meter (EHZ)

RegisterType¶

Name	Number	Description
REGISTER_TYPE_UNSPECIFIED	0	Type is not specified
SINGLE_TARIFF	1	Single tariff meter
DOUBLE_TARIFF_PEAK	2	aka Hochtarif (HT)
DOUBLE_TARIFF_OFF_PEAK	3	aka Niedertarif (NT)

Readings¶

Submit and retrieve meter readings.

List¶

List meter readings for a specific contract.

Input: ReadingListRequest¶

Field	Type	Rules	Description
*tenant¶	string		The tenant to list readings for.
*contract¶	string		The ID of the contract to list readings for.

Output: ReadingList¶

Field	Type	Rules	Description
meters¶	ReadingList.MetersEntry	repeated	A map of meters with meter numbers as the key.

Add¶

Submit a new reading for a specific meter.

Input: ReadingAddRequest¶

Field	Type	Description
*tenant¶	string	The tenant to submit a reading for.
*contract¶	string	The ID of the contract to submit a reading for.
*meter¶	string	The meter number to submit a reading for.
*reading¶	ReadingAddRequest.Reading	The reading to add.

ListMine¶

List readings for a specific contract of the current customer (identity from OAuth token).

Input: ReadingListRequest¶

Field	Type	Rules	Description
*tenant¶	string		The tenant to list readings for.
*contract¶	string		The ID of the contract to list readings for.

Output: ReadingList¶

Field	Type	Rules	Description
meters¶	ReadingList.MetersEntry	repeated	A map of meters with meter numbers as the key.

AddMine¶

Submit a new reading for a specific meter of the current customer (identity from OAuth token).

Input: ReadingAddRequest¶

Field	Type	Description
*tenant¶	string	The tenant to submit a reading for.
*contract¶	string	The ID of the contract to submit a reading for.
*meter¶	string	The meter number to submit a reading for.
*reading¶	ReadingAddRequest.Reading	The reading to add.

AddFromToken¶

Submit a new reading by using a generated one time token for a specific meter.

Input: ReadingAddFromTokenRequest¶

Field	Type	Rules	Description
*token¶	string		A one time token for a specific meter.
*request¶	ReadingAddRequest		The actual add request.

InvalidReadingImplausibleError¶

The specified reading has an implausible value. You can retry the request if you additionally set ignore_plausibility_check_reason.

Field	Type	Rules	Description
reason¶	InvalidReadingImplausibleError.Reason		The reason why the reading was rejected.

InvalidReadingImpossibleError¶

The specified reading has an impossible value and cannot be accepted.

ReadingAddRequest.Reading¶

Field	Type	Rules	Description
*date¶	google.type.Date		The date when the reading was taken.
*values¶	ReadingAddRequest.Reading.ValuesEntry	repeated	A map of values to submit with OBIS codes as the key.
channel¶	ReadingChannel		How the reading was reported. This is value is ignored when submitting via `AddMine`.
ignore_plausibility_check_reason¶	google.protobuf.StringValue		If set the meter reading(s) will be saved, even if they're not plausible. Specifies the reason why the plausibility check is to be ignored.

ReadingAddRequest.Reading.ValuesEntry¶

Field	Type	Rules	Description
key¶	string
value¶	double

ReadingList.Meter¶

Field	Type	Rules	Description
registers¶	ReadingList.Meter.RegistersEntry	repeated	A map of registers with OBIS codes as the key.

ReadingList.Meter.RegistersEntry¶

Field	Type	Rules	Description
key¶	string
value¶	ReadingList.Register

ReadingList.MetersEntry¶

Field	Type	Rules	Description
key¶	string
value¶	ReadingList.Meter

ReadingList.Reading¶

Field	Type	Description
date¶	google.type.Date	The date when the value was read.
value¶	double	The value that was read.
channel¶	ReadingChannel	How the reading was reported.
origin¶	ReadingOrigin	The origin of the reading.
quality¶	ReadingQuality	The quality of the reading, e.g. if it's estimated.

ReadingList.Register¶

Field	Type	Rules	Description
type¶	RegisterType		The type of the register.
readings¶	ReadingList.Reading	repeated	A list of readings sorted anti-chronologically (newest first).

InvalidReadingImplausibleError.Reason¶

Name	Number	Description
REASON_UNSPECIFIED	0	Reason not specified.
TOO_LOW	1	The value is lower than expected.
TOO_HIGH	2	The value is higher than expected.
OTHER	100	Other reason.

ReadingChannel¶

Name	Number	Description
READING_CHANNEL_UNSPECIFIED	0	No channel specified.
PORTAL	1	Reported via end-user portal.
EMAIL	2	Reported via email.
LETTER	3	Reported via letter.
PHONE	4	Reported via phone call.
MSCONS	5	Reported via Metered Services Consumption report message.

ReadingOrigin¶

Name	Number	Description
READING_ORIGIN_UNSPECIFIED	0	No origin specified.
NETWORK_OPERATOR	1	Distributed network operator (DNO) [DE: Verteilnetzbetreiber (VNB)].
PREVIOUS_PROVIDER	2	The last provider of delivery location.
CUSTOMER	3	The customer herself.
METER_POINT_OPERATOR	4	The meter point operator [DE: Messstellenbetereiber (MSB)].
THIRD_PARTY	5	A third party reported the reading.

ReadingQuality¶

Name	Number	Description
READING_QUALITY_UNSPECIFIED	0	No quality specified.
READ	1	A read value.
ESTIMATED	2	An estimated value.

UsageHours¶

Manage usage hours.

Set¶

Set a usage hours period of a contract.

Input: UsageHoursPeriod¶

Field	Type	Rules	Description
*tenant¶	string		The tenant the usage hours period belongs to.
*contract¶	string		The contract the usage hours period belongs to.
id¶	string		The ID of the usage hours period.
*period¶	enpowerx.types.DateRange		The period in which the usage hours are valid.
*value¶	int32		The usage hours in this period.
origin¶	UsageHoursPeriodOrigin	output only	The origin of the usage hours period.
resource_version¶	int32		The usage hours period version in storage. Omitted for usage hours period creation, required for usage hours period modification.

List¶

List the usage hours periods of a contract.

Input: UsageHoursPeriodListRequest¶

Field	Type	Description
*tenant¶	string	The tenant the usage hours period list belongs to.
*contract¶	string	The contract the usage hours period list belongs to.
page_size¶	int32	The maximum number of items to return. 0 for default.
page_token¶	string	The `next_page_token` value returned from a previous List request, if any.
filter¶	UsageHoursPeriodListRequest.Filter	Filters to limit the response.
order_by¶	string	Comma separated list of fields to order by. Use `-`-prefix for descending order, e.g. "-period.start". Supported fields are: - "period.start" - "period.end"

Output: UsageHoursPeriodList¶

Field	Type	Rules	Description
usage_hours_periods¶	UsageHoursPeriod	repeated	The usage hours periods.
next_page_token¶	string		Token to retrieve the next page of results, or empty if there are no more results in the list.

Calculate¶

Calculate the usage hours of a contract.

UsageHoursPeriodListRequest.Filter¶

Field	Type	Rules	Description
period¶	enpowerx.types.DateRange	optional	The period to filter by.
origin¶	UsageHoursPeriodOrigin	optional	Flag to filter by origin of usage hours.

UsageHoursPeriodOrigin¶

Name	Number	Description
USAGE_HOURS_PERIOD_ORIGIN_UNSPECIFIED	0	No origin specified.
CALCULATION	1	The usage hours are calculated.
AGENT	2	The usage hours were set manually by an agent.

Shared Types¶

Amount¶

Field	Type	Description
unit¶	string	The unit of the amount. E.g.'kWh' or 'PCS' for pieces.
units¶	int64	The whole units of the amount. For example if `unit` is `"PCS"`, then 1 unit is one piece.
nanos¶	int32	Number of nano (10^-9) units of the amount. The value must be between -999,999,999 and +999,999,999 inclusive. If `units` is positive, `nanos` must be positive or zero. If `units` is zero, `nanos` can be positive, zero, or negative. If `units` is negative, `nanos` must be negative or zero. For example $-1.75 is represented as `units`=-1 and `nanos`=-750,000,000.

BankAccount¶

Information about a bank account.

Field	Type	Description
*iban¶	string	The International Bank Account Number.
bic¶	string	The Bank Identifier Code.
account_holder¶	string	The name of the account holder.
bank¶	string	The name of the bank.

CustomerType¶

Represents the kind of the customer.

Name	Number	Description
CUSTOMER_TYPE_UNSPECIFIED	0	The customer type is unspecified.
PRIVATE	1	The customer type is private.
BUSINESS	2	The customer type is business.
BOTH	3	The customer type is private and business.

DateRange¶

Represents a range of dates.

Field	Type	Description
*start¶	google.type.Date	The inclusive start date.
end¶	google.type.Date	The inclusive end date.
end_exclusive¶	google.type.Date	The exclusive end date.
time_zone¶	string	The time zone of the date range (defaults to Europe/Berlin).

DateTimeRange¶

Represents a range of date times.

Field	Type	Rules	Description
*start¶	google.protobuf.Timestamp		The inclusive start date.
end¶	google.protobuf.Timestamp		The inclusive end date.

Decimal¶

Field	Type	Rules	Description
units¶	int64		The whole units of the amount.
nanos¶	int32		Number of nano (10^-9) units of the amount. The value must be between -999,999,999 and +999,999,999 inclusive. If `units` is positive, `nanos` must be positive or zero. If `units` is zero, `nanos` can be positive, zero, or negative. If `units` is negative, `nanos` must be negative or zero. For example $-1.75 is represented as `units`=-1 and `nanos`=-750,000,000.

Billing¶

Billing details.

Field	Type	Description
*contact¶	Contact	The contact to send invoices to.
*payment_method¶	PaymentMethod	The payment method method.
bank_account¶	BankAccount	The bank account used if `payment_method` is `DIRECT_DEBIT`.

CommunicationChannel¶

Communication channel.

Name	Number	Description
COMMUNICATION_CHANNEL_UNSPECIFIED	0	Channel not specified.
LETTER	1	Send messages via letter.
EMAIL	2	Send messages via email.
SMS	3	Send messages via SMS.
MESSENGER	4	Send messages via messenger apps like WhatsApp.
PHONE	5	Communicate via telephone.

Contact¶

Contact details (postal, phone, etc.).

Field	Type	Description
*person¶	Person	Information on how to address the contact.
postal_address¶	PostalAddress	The contact's postal address.
phone_number¶	string	The phone number of the contact. Values are normalized into the form `+123456789`.
email¶	string	The email address of the contact.
careof¶	Person	A person that may receive communication in the name of the actual recipient (e.g. a "C/O" line added to the postal address).

Reading¶

Information about a reading.

Field	Type	Rules	Description
*date¶	google.type.Date		The date when the reading was taken.
channel¶	Reading.Channel		How the reading was reported. This is value is ignored when submitting via `AddMine`.
*values¶	Reading.ValuesEntry	repeated	A map of values to submit with OBIS codes as the key.
ignore_plausibility_check_reason¶	google.protobuf.StringValue		If set the meter reading(s) will be saved, even if they're not plausible. Specifies the reason why the plausibility check is to be ignored.

Reading.ValuesEntry¶

Field	Type	Rules	Description
key¶	string
value¶	double

Reading.Channel¶

Name	Number	Description
CHANNEL_UNSPECIFIED	0	No channel specified.
PORTAL	1	Reported via end-user portal.
EMAIL	2	Reported via email.
LETTER	3	Reported via letter.
PHONE	4	Reported via phone call.
MSCONS	5	Reported via Metered Services Consumption report message.

Relocation¶

Information about the relocation of an contract.

Field	Type	Description
*contract¶	string	The contract's ID this request is targeting.
*moveout_date¶	google.type.Date	The move-out date.
*movein_date¶	google.type.Date	The move-in date.
*delivery¶	EnergyDelivery	Which kind and amount of energy is to be delivered to where.
*use_new_address¶	Relocation.UseNewAddress	Use the new address as postal and billing address.
*meter¶	string	The ID of the meter at the new consumption point.
last_reading¶	Reading	The last reading at the old consumption point.
old_meter¶	string	The ID of the meter at the old consumption point. Optional, must be set if a last reading is provided.

Relocation.UseNewAddress¶

Name	Number	Description
USE_NEW_ADDRESS_UNSPECIFIED	0	Use unspecified.
NO	1	Use not desired.
IMMEDIATELY	2	Use immediately desired.
ON_MOVE_IN	3	Use on moving in desired.

SalesInfo¶

Information on how a sale was made.

Field	Type	Description
sales_partner_code¶	string	Direct sales partner code.
sales_partner_code_second¶	string	Second direct sales partner code.
campaign¶	string	Optional override for the default campaign.

ScheduledRequest¶

Reference to an entity with an optional scheduled starting date.

Field	Type	Rules	Description
*id¶	string		The ID referencing the entity.
scheduled_date¶	google.type.Date		The scheduled starting date (earliest possible if unset).

TransitionType¶

Specifies modalities of a contract transition.

Name	Number	Description
TRANSITION_TYPE_UNSPECIFIED	0	The transition type is unspecified
MANUAL_TERMINATION	1	The customer terminates the prior contract.
VENDOR_TERMINATION	2	The vendor terminates the prior contract.
RELOCATION	3	The customer is going to or has recently moved to the new address.

Duration¶

Represents a coarse time duration (e.g., 2 months).

Field	Type	Rules	Description
*units¶	int32		The number of time units.
*type¶	google.type.CalendarPeriod		The type the units refer to (days, months, etc.).

EnergyDelivery¶

Describes which kind and amount of energy is to be delivered to where.

Field	Type	Description
*energy_type¶	EnergyType	The kind of the energy.
*customer_type¶	CustomerType	The kind of the customer.
*address¶	PostalAddress	The address to deliver energy to.
annual_usage¶	int32	The estimated power usage in kWh per year.
usage_type¶	EnergyDelivery.UsageType	The usage type for the delivered energy.
annual_usage_nt¶	int32	The estimated off-peak power usage in kWh per year (DE: Niedertarifverbrauch).

EnergyDelivery.UsageType¶

Name	Number	Description
USAGE_TYPE_UNSPECIFIED	0	The consumption type is unspecified.
HOUSEHOLD_ELECTRICITY	1	The energy is used for household.
CHARGING_CURRENT	2	The energy is used for charging.
STORAGE_HEATER	3	The energy is used for a storage heater.
HEAT_PUMP	4	The energy is used for a heat pump.
HOUSEHOLD_ELECTRICITY_AND_STORAGE_HEATER	5	The energy is used for household with storage heater.
HOUSEHOLD_ELECTRICITY_AND_HEAT_PUMP	6	The energy is used for household with heat pump.

EnergyType¶

Represents the kind of the energy.

Name	Number	Description
ENERGY_TYPE_UNSPECIFIED	0	The energy type is unspecified.
ELECTRICITY	1	The energy type is electricity.
GAS	2	The energy type is gas.

FileContent¶

Field	Type	Rules	Description
*mime_type¶	string		The media type / content type of the document.
*content¶	bytes		The raw data of the document.

AnnotationFilter¶

AnnotationFilter provides filter semantics for annotations.

Field	Type	Rules	Description
*field¶	string		The annotation field path is a symbolic field path to target an annotation's field, for example: "invoice.id", "is_consumption_based", ...
value¶	google.protobuf.Value		The value to match the annotation field's value.

DateFilter¶

DateFilter provides match semantics for date fields.

Field	Type	Rules	Description
*date¶	google.type.Date		The date to filter for.
match_mode¶	DateFilter.MatchMode		The match mode to use. The default is EQUAL.

DateRangeFilter¶

DateTimeRangeFilter provides match semantics for date fields. The filter treats the start and end date as inclusive.

Field	Type	Rules	Description
*start_date¶	google.type.Date		The start date to filter for.
*end_date¶	google.type.Date		The end date to filter for.

DateTimeFilter¶

DateTimeFilter provides match semantics for date time fields.

Field	Type	Rules	Description
*time¶	google.protobuf.Timestamp		The date time to filter for.
match_mode¶	DateTimeFilter.MatchMode		The match mode to use. The default is EQUAL.

DateTimeRangeFilter¶

DateTimeRangeFilter provides match semantics for date time fields.

Field	Type	Rules	Description
*start_time¶	google.protobuf.Timestamp		The start date time to filter for.
*end_time¶	google.protobuf.Timestamp		The end date time to filter for.

StringListFilter¶

Strings filter x IN and x NOT IN semantics.

Field	Type	Rules	Description
*values¶	string	repeated	The value to filter for.
negate¶	bool		If true the expression is negated.

StringScalarFilter¶

StringFilter provides match semantics for strings fields.

Field	Type	Description
*value¶	string	The value to filter for.
match_mode¶	StringScalarFilter.MatchMode	The match mode to use.
negate¶	bool	If true the expression is negated.

DateFilter.MatchMode¶

Name	Number	Description
MATCH_MODE_UNSPECIFIED	0	The match mode is unspecified.
EQUAL	1	Filter only matches if the date is equal to the provided date.
BEFORE	2	Filter matches all dates that are before the provided date.
AFTER	3	Filter matches all dates that are after the provided date.
BEFORE_OR_EQUAL	4	Filter matches all dates that are before or equal to the provided date.
AFTER_OR_EQUAL	5	Filter matches all dates that are after or equal to the provided date.

DateTimeFilter.MatchMode¶

Name	Number	Description
MATCH_MODE_UNSPECIFIED	0	The match mode is unspecified.
EQUAL	1	Filter only matches if the date is equal to the provided date.
BEFORE	2	Filter matches all dates that are before the provided date.
AFTER	3	Filter matches all dates that are after the provided date.
BEFORE_OR_EQUAL	4	Filter matches all dates that are before or equal to the provided date.
AFTER_OR_EQUAL	5	Filter matches all dates that are after or equal to the provided date.

StringScalarFilter.MatchMode¶

Name	Number	Description
MATCH_MODE_UNSPECIFIED	0	The match mode is unspecified.
EXACT	1	Filter only matches if the field contains exactly the expected value.
PREFIX	2	Filter matches all fields that are prefixed with the given value.
SUFFIX	3	Filter matches all fields that are suffixed with the given value.
SUBSTRING	4	Filter matches all fields that contain the given value.

LetterAddress¶

Combines a name and a postal address.

Field	Type	Description
*person¶	Person	The person being addressed.
careof¶	string	A person that may receive letters in the name of the actual recipient (e.g. a "C/O" line added to the postal address).
*postal_address¶	PostalAddress	The postal address.

MonthOfYear¶

Represents a month of a year.

Field	Type	Rules	Description
month¶	int32		Month of the year.
year¶	int32		Year.

PaymentMethod¶

Possible methods for paying invoices.

Name	Number	Description
PAYMENT_METHOD_UNSPECIFIED	0	The payment method method is unspecified.
DIRECT_DEBIT	1	Money is automatically withdrawn from the specified bank account.
MANUAL_TRANSFER	2	The customer pays bills manually using money transfers.

Period¶

A period of time with inclusive start and inclusive and exclusive end time. If both (inclusive and exclusive) ends are specified, they must be consistent. If no end is specified, the period is considered unbounded on the end. If the time is unspecified it is considered to be 00:00:00.000000000 for the start (and exclusive end) and 23:59:59.999999999 for the inclusive end.

The following example represents a period of time from 2006-01-01 to 2006-01-31: { start_time: { hours: 0 minutes: 0 seconds: 0 nanos: 0 } start_date: { year: 2006 month: 1 day: 1 } end_time: { hours: 23 minutes: 59 seconds: 59 nanos: 999999999 } end_date: { year: 2006 month: 1 day: 31 } end_date_exclusive: { year: 2006 month: 2 day: 1 } end_time_exclusive: { hours: 0 minutes: 0 seconds: 0 nanos: 0 } }

Field	Type	Description
start_time¶	google.type.TimeOfDay	The start time of the period (inclusive).
end_time¶	google.type.TimeOfDay	The end time of the period (inclusive).
start_date¶	google.type.Date	The start date of the period (inclusive).
end_date¶	google.type.Date	The end date of the period (inclusive).
end_time_exclusive¶	google.type.TimeOfDay	The end time of the period (exclusive).
end_date_exclusive¶	google.type.Date	The end date of the period (exclusive).
time_zone¶	string	The time zone of the period (defaults to Europe/Berlin).

Person¶

Information on how to address a person. A person can be either a natural person or a company with an optional contact Natural Person: Must provide firstname, lastname Company: Must provide company

Field	Type	Description
salutation¶	Person.SalutationForm	The salutation of the person.
title¶	string	The title of the person.
firstname¶	string	The first name of the person.
lastname¶	string	The last name of the person.
birthday¶	google.type.Date	The birthday of the person.
company¶	string	The company name.

Person.SalutationForm¶

Name	Number	Description
SALUTATION_FORM_UNSPECIFIED	0	The salutation form is unspecified.
MRS	1	The salutation form is `Mrs.`.
MR	2	The salutation form is `Mr.`.
DIVERSE	3	The salutation form is `Diverse`.
FAMILY	4	The salutation form is `Family`.

PostalAddress¶

Represents a postal address, e.g. for postal delivery or payments addresses.

Field	Type	Rules	Description
*region¶	string		The region the address is located in as a CLDR region code. Example: `DE` for Germany
*postal_code¶	string		A postal code of the city (a city may have more than one). Example: `76131` for Karlsruhe inner city
*city¶	string		The canonical name of the city (there may be more than one per postal code). Example: `Karlsruhe`
street¶	string		The canonical name of the street. Example: `Kaiserstr.`
house_number¶	string		The house number. Examples: `32`, `32a`, `32/1`
postbox_number¶	string		Postbox number in case address is a postbox.
district¶	string		Administrative division (i.e. Stadtteil).
additional_address_lines¶	string	repeated	Additional address lines Example: Appartment 104, Care of etc.

Price¶

Represents a price before and after taxes.

Field	Type	Description
*net¶	google.type.Money	The price without VAT.
*gross¶	google.type.Money	The price including VAT.
unit¶	string	The unit the price is related to (e.g "kWh", "PCS", "month", etc.)

Quantity¶

Field	Type	Description
unit¶	string	The unit of the quantity. E.g.'kWh' or 'PCS' for pieces.
units¶	int64	The whole units of the quantity. For example if `unit` is `"PCS"`, then 1 unit is one piece.
nanos¶	int32	Number of nano (10^-9) units of the quantity. The value must be between -999,999,999 and +999,999,999 inclusive. If `units` is positive, `nanos` must be positive or zero. If `units` is zero, `nanos` can be positive, zero, or negative. If `units` is negative, `nanos` must be negative or zero. For example $-1.75 is represented as `units`=-1 and `nanos`=-750,000,000.

RecurringCost¶

Represents a price/cost that repeats at a fixed interval.

Field	Type	Rules	Description
*price¶	Price		The price per interval.
*interval¶	google.type.CalendarPeriod		The interval at which the cost occurs (per day, month, etc.).

TenantScopedListRequest¶

Field	Type	Description
*tenant¶	string	The tenant the list belongs to.
page_size¶	int32	The maximum number of items to return. 0 for default.
page_token¶	string	The `next_page_token` value returned from a previous List request, if any.

TenantScopedResource¶

A tenant scoped resource.

Field	Type	Rules	Description
*tenant¶	string		The tenant the resource belongs to.
*id¶	string		The ID of the resource.

TimeRange¶

A range of time with inclusive start, inclusive and exclusive end time. If both (inclusive and exclusive) ends are specified, they must be consistent. If no end is specified, the period is considered unbounded on the end.

Field	Type	Description
start¶	google.protobuf.Timestamp	The inclusive start.
end¶	google.protobuf.Timestamp	The inclusive end.
end_exclusive¶	google.protobuf.Timestamp	The exclusive end.

File-level Extensions¶

Extension	Type	Base	Number	Description
throws	string	.google.protobuf.MethodOptions	76131	throws is used to document error messages that the method might return in status.details.

CalendarPeriod¶

A CalendarPeriod represents the abstract concept of a time period that has a canonical start. Grammatically, "the start of the current CalendarPeriod." All calendar times begin at midnight UTC.

Name	Number	Description
CALENDAR_PERIOD_UNSPECIFIED	0	Undefined period, raises an error.
DAY	1	A day.
WEEK	2	A week. Weeks begin on Monday, following ISO 8601.
FORTNIGHT	3	A fortnight. The first calendar fortnight of the year begins at the start of week 1 according to ISO 8601.
MONTH	4	A month.
QUARTER	5	A quarter. Quarters start on dates 1-Jan, 1-Apr, 1-Jul, and 1-Oct of each year.
HALF	6	A half-year. Half-years start on dates 1-Jan and 1-Jul.
YEAR	7	A year.

Date¶

Represents a whole or partial calendar date, such as a birthday. The time of day and time zone are either specified elsewhere or are insignificant. The date is relative to the Gregorian Calendar. This can represent one of the following:

A full date, with non-zero year, month, and day values
A month and day value, with a zero year, such as an anniversary
A year on its own, with zero month and day values
A year and month value, with a zero day, such as a credit card expiration date

Related types are [google.type.TimeOfDay][google.type.TimeOfDay] and google.protobuf.Timestamp.

Field	Type	Description
year¶	int32	Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.
month¶	int32	Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.
day¶	int32	Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant.

Money¶

Represents an amount of money with its currency type.

Field	Type	Description
currency_code¶	string	The three-letter currency code defined in ISO 4217.
units¶	int64	The whole units of the amount. For example if `currencyCode` is `"USD"`, then 1 unit is one US dollar.
nanos¶	int32	Number of nano (10^-9) units of the amount. The value must be between -999,999,999 and +999,999,999 inclusive. If `units` is positive, `nanos` must be positive or zero. If `units` is zero, `nanos` can be positive, zero, or negative. If `units` is negative, `nanos` must be negative or zero. For example $-1.75 is represented as `units`=-1 and `nanos`=-750,000,000.

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)

Legend¶

*) required