# Calculate Cost Source: https://docs.engrate.io/api-reference/calculate-cost https://api.engrate.io/v1/power-tariffs/openapi.json post /power-tariffs/{tariff_uid}/calculate Calculate power tariff cost based on power offtake and subscribed capacity data. Note: Power tariffs apply to periods of time (such as weeks, months or years). If the provided offtake or subscribed capacity data does not cover full tariff periods, the calculation will apply the tariff rules as if the supplied data represented the full period. In this case, the cost will reflect the peak offtake, resp. subscribed capacity observed within the passed time range. E.g. if you only pass 24 hours of offtake data for a tariff with a peak power fee component that is calculated on a monthly basis, the calculation will just use the highest x peaks observed within that 24 hour period to calculate the peak power that goes into the peak power fee cost calculation. # Extra Identifier Source: https://docs.engrate.io/api-reference/core/models/extra-identifier # Metering Grid Area Source: https://docs.engrate.io/api-reference/core/models/metering-grid-area # Party Source: https://docs.engrate.io/api-reference/core/models/party # Core API Overview Source: https://docs.engrate.io/api-reference/core/overview Engrate Core API covers the fundamentals The Core API defines fundamental building blocks we use to talk about the Electricity System. The European electricity grid is undergoing large changes, and the language used to talk about it is in flux. Each country has it's own legal and regulatory frameworks, language and roles structure defining who does what. At the same time, the system is increasingly regulated on the European level, which means a shared language is emerging. As much as possible the Engrate API leans on the official [Harmonized Electricity Role Model](https://www.entsoe.eu/data/cim/role-models/). This helps our APIs be general, making it possible for clients to think about all of Europe in one holistic domain model. At the same time, local differences are still present. Engrate tries to be pragmatic but forward looking: * We aspire to a single pan-European model * We keep the scope small, naming only those concepts we need for the API * Where necessary we augment the harmonized model, [Extra Identifier](/api-reference/core/models/extra-identifier) being one such example ## Core concepts * [Party](/api-reference/core/models/party) represent market parties, legal entities that serve one or more roles in the system * [Metering Grid Area](/api-reference/core/models/metering-grid-area) are a collection of metering points operated by some [Party](/api-reference/core/models/party) serving as a `system-operator` # Calculation Pipeline Source: https://docs.engrate.io/api-reference/cost-of-energy/calculation-pipeline An algebra for calculating the cost of energy How energy costs are calculated vary not only across [System Operators](/api-reference/core/models/party), but also over time, energy consumption levels, power usage and so on. A given metering point may have one set of calculations one day, and a different set the next as rules are changed. There is also a very wide *range* of calculations, with market parties broadly left up to their own devices to invent rate "algorithms'. Calculation pipelines are a minimal *algebra* that abstracts this away - as new tariffs are invented or you enter new markets, your code keeps working. This lets you build systems that require much less maintenance than manually implementing and updating hundreds of tariffs. The calculation pipelines are a sequential list of a small set of [Functions](/api-reference/cost-of-energy/functions/overview), each taking zero or more input [Datasets](/api-reference/cost-of-energy/models/dataset), and producing a single output [Dataset](/api-reference/cost-of-energy/models/dataset). Evaluating each function in order will give you the final cost dataset. For the technically curious, the calculation pipeline is a form of [Static Single Assignment](https://en.wikipedia.org/wiki/Static_single-assignment_form) representation — each step assigns a new named dataset, which then serves as input for later steps. Pipelines usually start with one or more well-known [Registered Datasets](/api-reference/cost-of-energy/models/dataset). Those are datasets that you'll need to provide to the calculation, like how much energy was or will be consumed per quarter-hour. # Example pipelines Lets walk through a series of increasingly powerful examples to help get a feel for how the pipelines express different cost structures. Note each example is available as a diagram and as the equivalent JSON representation. The diagrams are available in LLM-readable mermaid diagrams in [llms-full.txt](https://docs.engrate.io/llms-full.txt). ## Example: Fixed monthly fee This is likely the very simplest example we can give: Each month, the metering point is billed some fixed fee. The fee is the same independent of what the metering point does, so there are no [Registered Datasets](/api-reference/cost-of-energy/models/dataset) needed. The pipeline consists of a single [Constant Function](/api-reference/cost-of-energy/functions/constant) which outputs a fixed cost per month. ```mermaid theme={null} %%{init: {'theme': 'base'}}%% graph TD fn_0_constant("constant
45.0 SEK · monthly") result_cost("Fixed monthly fee") fn_0_constant -->|cost| result_cost click fn_0_constant "/api-reference/cost-of-energy/functions/constant" class fn_0_constant eg-fn class result_cost eg-output ``` ```json theme={null} { "name": "Fixed monthly fee", "applicable_from": "1658-02-26T00:00:00Z", "applicable_to": null, "timezone": "Europe/Stockholm", "datasets": [], "functions": [ { "function": "constant", "value": { "value": 45.0, "unit": "SEK" }, "resolution": "monthly", "output": { "id": "cost", "resolution": "monthly", "unit": "SEK" } } ], "cost": { "id": "cost", "resolution": "monthly", "unit": "SEK" } } ``` ## Example: Energy tax Lets take it a step further and do a calculation that *does* depend on what the Metering Point does. The energy tax in Sweden is calculated based on hourly kWh consumed. There is no [Registered Datasets](/api-reference/cost-of-energy/models/dataset) for hourly energy consumed, as energy consumption at the meter is tracked quarter-hourly. Therefore we combine two functions: 1. [Aggregate](/api-reference/cost-of-energy/functions/aggregate) the quarter-hour consumption data to hourly by summing it 2. [Multiply](/api-reference/cost-of-energy/functions/multiply) the hourly consumption data by the energy tax cost to get the final cost ```mermaid theme={null} %%{init: {'theme': 'base'}}%% graph TD ds_quarter-hourly-energy-offtake("quarter-hourly-energy-offtake
quarter_hourly · kWh") fn_0_aggregate("aggregate
sum · hourly") fn_1_multiply("multiply
× 36.0 SEK_per_kWh") result_cost("Energy tax") ds_quarter-hourly-energy-offtake --> fn_0_aggregate fn_0_aggregate -->|hourly-energy-offtake| fn_1_multiply fn_1_multiply -->|cost| result_cost click fn_0_aggregate "/api-reference/cost-of-energy/functions/aggregate" click fn_1_multiply "/api-reference/cost-of-energy/functions/multiply" class ds_quarter-hourly-energy-offtake eg-dataset class fn_0_aggregate eg-fn class fn_1_multiply eg-fn class result_cost eg-output ``` ```json theme={null} { "name": "Energy tax", "applicable_from": "1658-02-26T00:00:00Z", "applicable_to": null, "timezone": "Europe/Stockholm", "datasets": [ { "id": "quarter-hourly-energy-offtake", "resolution": "quarter_hourly", "unit": "kWh" } ], "functions": [ { "function": "aggregate", "input": { "id": "quarter-hourly-energy-offtake", "resolution": "quarter_hourly", "unit": "kWh" }, "resolution": "hourly", "aggregation_function": "sum", "output": { "id": "hourly-energy-offtake", "resolution": "hourly", "unit": "kWh" } }, { "function": "multiply", "left": { "id": "hourly-energy-offtake", "resolution": "hourly", "unit": "kWh" }, "right": { "value": 36.0, "unit": "SEK_per_kWh" }, "output": { "id": "cost", "resolution": "hourly", "unit": "SEK" } } ], "cost": { "id": "cost", "resolution": "hourly", "unit": "SEK" } } ``` ## Example: Peak tariff Some rate plans charge you for "peak" usage - but what exactly is a "peak"? Unfortunately that depends on which [System Operators](/api-reference/core/models/party) you ask. This example shows a simplified peak calculation: * In each month, find the three highest hourly peaks * Take the average of those three * Multiply that average with some fee To do this we: 1. [Aggregate](/api-reference/cost-of-energy/functions/aggregate) the quarter-hour consumption data to hourly kWh by summing it 2. [Divide](/api-reference/cost-of-energy/functions/divide) the hourly energy consumption data by 1 hour to convert to kW (yes yes, but otherwise we would have needed to add a separate 'conversion' operator you know) 3. [Select](/api-reference/cost-of-energy/functions/select) the 3 highest values per month (see [Absent Values](/api-reference/cost-of-energy/models/dataset)) 4. [Aggregate](/api-reference/cost-of-energy/functions/aggregate) to monthly peaks by taking the mean of those 3 peaks 5. [Multiply](/api-reference/cost-of-energy/functions/multiply) the monthly peak value by the fee to get the final cost ```mermaid theme={null} %%{init: {'theme': 'base'}}%% graph TD ds_quarter-hourly-energy-offtake("quarter-hourly-energy-offtake
quarter_hourly · kWh") fn_0_aggregate("aggregate
sum · hourly") fn_1_divide("divide
hourly-energy-offtake ÷ 1.0 hours") fn_2_select("select
top 3 · monthly") fn_3_aggregate("aggregate
mean · monthly") fn_4_multiply("multiply
× 5.0 SEK_per_kW") result_cost("Highest peaks fee") ds_quarter-hourly-energy-offtake --> fn_0_aggregate fn_0_aggregate -->|hourly-energy-offtake| fn_1_divide fn_1_divide -->|hourly-power-offtake| fn_2_select fn_2_select -->|hourly-top3-power| fn_3_aggregate fn_3_aggregate -->|monthly-peak| fn_4_multiply fn_4_multiply -->|cost| result_cost click fn_0_aggregate "/api-reference/cost-of-energy/functions/aggregate" click fn_1_divide "/api-reference/cost-of-energy/functions/divide" click fn_2_select "/api-reference/cost-of-energy/functions/select" click fn_3_aggregate "/api-reference/cost-of-energy/functions/aggregate" click fn_4_multiply "/api-reference/cost-of-energy/functions/multiply" class ds_quarter-hourly-energy-offtake eg-dataset class fn_0_aggregate eg-fn class fn_1_divide eg-fn class fn_2_select eg-fn class fn_3_aggregate eg-fn class fn_4_multiply eg-fn class result_cost eg-output ``` ```json theme={null} { "name": "Highest peaks fee", "applicable_from": "1658-02-26T00:00:00Z", "applicable_to": null, "timezone": "Europe/Stockholm", "datasets": [ { "id": "quarter-hourly-energy-offtake", "resolution": "quarter_hourly", "unit": "kWh" } ], "functions": [ { "function": "aggregate", "input": { "id": "quarter-hourly-energy-offtake", "resolution": "quarter_hourly", "unit": "kWh" }, "resolution": "hourly", "aggregation_function": "sum", "output": { "id": "hourly-energy-offtake", "resolution": "hourly", "unit": "kWh" } }, { "function": "divide", "numerator": { "id": "hourly-energy-offtake", "resolution": "hourly", "unit": "kWh" }, "denominator": { "value": 1.0, "unit": "hours" }, "output": { "id": "hourly-power-offtake", "resolution": "hourly", "unit": "kW" } }, { "function": "select", "input": { "id": "hourly-power-offtake", "resolution": "hourly", "unit": "kW" }, "condition": { "type": "highest", "n": 3, "resolution": "monthly" }, "output": { "id": "hourly-top3-power", "resolution": "hourly", "unit": "kW" } }, { "function": "aggregate", "input": { "id": "hourly-top3-power", "resolution": "hourly", "unit": "kW" }, "resolution": "monthly", "aggregation_function": "mean", "output": { "id": "monthly-peak", "resolution": "monthly", "unit": "kW" } }, { "function": "multiply", "left": { "id": "monthly-peak", "resolution": "monthly", "unit": "kW" }, "right": { "value": 5.0, "unit": "SEK_per_kW" }, "output": { "id": "cost", "resolution": "monthly", "unit": "SEK" } } ], "cost": { "id": "cost", "resolution": "monthly", "unit": "SEK" } } ``` # Condition: And Source: https://docs.engrate.io/api-reference/cost-of-energy/conditions/and # Condition: DayOfWeek Source: https://docs.engrate.io/api-reference/cost-of-energy/conditions/day-of-week # Condition: ExcludeHolidays Source: https://docs.engrate.io/api-reference/cost-of-energy/conditions/exclude-holidays Condition that excludes certain holidays. ## Holiday strings | Value | Description | | --------------------- | ------------------------------------------- | | `se/nyarsdagen` | January 1st. | | `se/trettondedag_jul` | January 6th (Epiphany). | | `se/langfredagen` | The Friday before Easter Sunday (moveable). | | `se/annandag_pask` | The Monday after Easter Sunday (moveable). | | `se/julafton` | December 24th. | | `se/juldagen` | December 25th. | | `se/annandag_jul` | December 26th. | | `se/nyarsafton` | December 31st. | # Condition: Highest Source: https://docs.engrate.io/api-reference/cost-of-energy/conditions/highest # Condition: Lowest Source: https://docs.engrate.io/api-reference/cost-of-energy/conditions/lowest # Condition: Month Source: https://docs.engrate.io/api-reference/cost-of-energy/conditions/month # Condition: Not Source: https://docs.engrate.io/api-reference/cost-of-energy/conditions/not # Condition: Or Source: https://docs.engrate.io/api-reference/cost-of-energy/conditions/or # Conditions Source: https://docs.engrate.io/api-reference/cost-of-energy/conditions/overview Available Conditions Conditions are used by operations like [Select](/api-reference/cost-of-energy/ops/select) and [Mask](/api-reference/cost-of-energy/ops/mask) to define when the operation applies. Conditions are represented as a [tagged union](https://en.wikipedia.org/wiki/Tagged_union), using the field `type` which every condition contains. Anywhere a condition is accepted you may find any of the conditions listed here, and you tell them apart using the value of the `type` field. ### Time conditions | Condition | Tag | Description | | ---------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------- | | [Month](/api-reference/cost-of-energy/conditions/month) | `month` | Only applies in the specified months. | | [DayOfWeek](/api-reference/cost-of-energy/conditions/day-of-week) | `day_of_week` | Only applies on the specified days of the week. | | [TimeOfDay](/api-reference/cost-of-energy/conditions/time-of-day) | `time_of_day` | Only applies within the specified time-of-day range. | | [ExcludeHolidays](/api-reference/cost-of-energy/conditions/exclude-holidays) | `exclude_holidays` | Applies on all days except the specified holidays. | | [And](/api-reference/cost-of-energy/conditions/and) | `and` | Applies when all sub-conditions are met. | | [Or](/api-reference/cost-of-energy/conditions/or) | `or` | Applies when any sub-condition is met. | | [Not](/api-reference/cost-of-energy/conditions/not) | `not` | Applies when the sub-condition doesn't apply. | ### Value conditions | Condition | Tag | Description | | ----------------------------------------------------------- | --------- | ------------------------------------------------ | | [Highest](/api-reference/cost-of-energy/conditions/highest) | `highest` | Keep the N highest values per resolution window. | | [Lowest](/api-reference/cost-of-energy/conditions/lowest) | `lowest` | Keep the N lowest values per resolution window. | # Condition: TimeOfDay Source: https://docs.engrate.io/api-reference/cost-of-energy/conditions/time-of-day # Function: Add Source: https://docs.engrate.io/api-reference/cost-of-energy/functions/add # Function: Aggregate Source: https://docs.engrate.io/api-reference/cost-of-energy/functions/aggregate # Function: Clip Source: https://docs.engrate.io/api-reference/cost-of-energy/functions/clip # Function: Constant Source: https://docs.engrate.io/api-reference/cost-of-energy/functions/constant # Function: Divide Source: https://docs.engrate.io/api-reference/cost-of-energy/functions/divide # Function: Lookup Source: https://docs.engrate.io/api-reference/cost-of-energy/functions/lookup # Function: Mask Source: https://docs.engrate.io/api-reference/cost-of-energy/functions/mask # Function: Multiply Source: https://docs.engrate.io/api-reference/cost-of-energy/functions/multiply # Function Source: https://docs.engrate.io/api-reference/cost-of-energy/functions/overview Available Functions Functions are the building blocks that define [Calculation Pipelines](/api-reference/cost-of-energy/calculation-pipeline), a domain-specific algebra for computer-readable cost calculations. Functions are represented as a [tagged union](https://en.wikipedia.org/wiki/Tagged_union), using the field `function` which every function contains. Anywhere a function is accepted you may find any of the functions listed here, and you tell them apart using the value of the `function` field. | Function | Tag | Description | | -------------------------------------------------------------- | ----------- | ---------------------------------------------------------------- | | [Constant](/api-reference/cost-of-energy/functions/constant) | `constant` | Emit a constant value at a given resolution. | | [Add](/api-reference/cost-of-energy/functions/add) | `add` | Sum two or more operands. | | [Subtract](/api-reference/cost-of-energy/functions/subtract) | `subtract` | Compute left - right. | | [Divide](/api-reference/cost-of-energy/functions/divide) | `divide` | Compute numerator / denominator with unit algebra. | | [Multiply](/api-reference/cost-of-energy/functions/multiply) | `multiply` | Multiply two operands with unit algebra. | | [Aggregate](/api-reference/cost-of-energy/functions/aggregate) | `aggregate` | Aggregate a dataset over a coarser resolution window. | | [Resample](/api-reference/cost-of-energy/functions/resample) | `resample` | Resample a coarse-resolution series to finer resolution. | | [Select](/api-reference/cost-of-energy/functions/select) | `select` | Keep only values matching a condition (temporal or value-based). | | [Mask](/api-reference/cost-of-energy/functions/mask) | `mask` | Conditional substitution based on a condition. | | [Clip](/api-reference/cost-of-energy/functions/clip) | `clip` | Clamp values to a min/max range. | | [Lookup](/api-reference/cost-of-energy/functions/lookup) | `lookup` | Tier-based table lookup. | # Function: Resample Source: https://docs.engrate.io/api-reference/cost-of-energy/functions/resample # Function: Select Source: https://docs.engrate.io/api-reference/cost-of-energy/functions/select # Function: Subtract Source: https://docs.engrate.io/api-reference/cost-of-energy/functions/subtract # Dataset Source: https://docs.engrate.io/api-reference/cost-of-energy/models/dataset # Level Source: https://docs.engrate.io/api-reference/cost-of-energy/models/level # Resolution Source: https://docs.engrate.io/api-reference/cost-of-energy/models/resolution # Tariff Source: https://docs.engrate.io/api-reference/cost-of-energy/models/tariff # Tariff Component Source: https://docs.engrate.io/api-reference/cost-of-energy/models/tariff-component # Unit Source: https://docs.engrate.io/api-reference/cost-of-energy/models/unit # Cost of Energy API Overview Source: https://docs.engrate.io/api-reference/cost-of-energy/overview Calculate the cost of energy The Cost of Energy API allows you to calculate the cost of energy consumption in any Swedish [Metering Grid Area](/api-reference/core/models/metering-grid-area). The API is structured around [Tariffs](/api-reference/cost-of-energy/models/tariff) that contain [Tariff Components](/api-reference/cost-of-energy/models/tariff-component), each describing some aspect like tax, transfer fees etc. The [Tariff Components](/api-reference/cost-of-energy/models/tariff-component) use a machine-readable [Calculation Pipeline](/api-reference/cost-of-energy/calculation-pipeline) to describe exactly how to calculate energy cost. ## Approach The API gives you *abstract* machine-readable [Calculation Pipelines](/api-reference/cost-of-energy/calculation-pipeline) that describe how to calculate the cost of energy. To actually do the calculation, your code - or our API depending on your needs - executes the calculation pipelines. This abstraction comes with several benefits: * Implementation is fast as there are only a handful of operations to implement, compared to implementing hundreds of DSOs rate plans individually * It works both to implement as regular code and for constructing optimisation problems * It allows any language to be used * Applications can be built without a need to call our APIs in runtime hot loops, improving speed and robustness To execute the abstract calculation pipelines you pick an approach that suits your needs: * Coming Soon Call our Calculate API and we'll calculate the cost for you * Implement code in your application to execute them ```mermaid theme={null} %%{init: {'theme': 'base'}}%% flowchart LR subgraph pipeline[" Calculation Pipeline "] direction TB ds("energy consumption
hourly · kWh") mul("multiply
× 36.0 SEK_per_kWh") con("constant
45.0 SEK · monthly") add("add") cost("Cost") ds --> mul mul -->|energy tax| add con -->|fixed fee| add add -->|cost| cost end subgraph yourcode[" Your Code "] direction TB exec("Interpret & execute
in any language") end pipeline --> yourcode class ds eg-dataset class mul,con,add eg-fn class cost eg-output ``` ## Usage Common usage of the API revolves around: 1. Find the [Tariffs](/api-reference/cost-of-energy/models/tariff) that apply for the metering point(s) you are interested in 2. Choose all or some [Tariff Components](/api-reference/cost-of-energy/models/tariff-component) of the tariff that you care about 3. Evaluate the [Calculation Pipelines](/api-reference/cost-of-energy/calculation-pipeline) of those [Tariff Components](/api-reference/cost-of-energy/models/tariff-component) using your metering point's datasets. You can find Tariffs in multiple ways: * Look up `system-operator` [Party](/api-reference/core/models/party) by name, country or other filters, then ask for [Tariffs](/api-reference/cost-of-energy/models/tariff) that are offered by that `system-operator` * Look up [Metering Grid Area](/api-reference/core/models/metering-grid-area) by metering point lat/lon, address, name or other filters and then ask for [Tariffs](/api-reference/cost-of-energy/models/tariff) that are available in that MGA. # Swedish grid fees explained Source: https://docs.engrate.io/api-reference/endpoints/power-tariffs/model What are grid fees/power tariffs and how do they fit into the energy world. ## Overview Swedish electricity grid tariffs are regulated network charges paid to Distribution System Operators (DSOs) for the use of the electricity grid infrastructure. These tariffs are separate from the actual electricity commodity price (paid to the retailer/supplier) and are determined by the DSO operating each metering grid area (MGA). The tariffs cover the cost of metering, distributing electricity, maintaining the grid, and investing in grid expansion and modernization. ## Evolution Toward Power-Based Pricing Swedish DSOs are transitioning from traditional energy-based pricing (kWh) to **power-based pricing** (effektabonnemang) to better reflect actual grid costs and incentivize efficient grid usage. This shift encourages customers to spread their electricity consumption more evenly over time rather than creating demand peaks that strain grid capacity. ### The Regulatory Mandate for Power Tariffs In 2022, Sweden's energy regulator **Energimarknadsinspektionen (EI)** issued directive **EIFS 2022:1**, mandating all DSOs to implement power-based tariffs by January 1, 2027. The directive pursues two goals: 1. **Cost-reflectivity (Kostnadsriktighet):** Customers pay for the actual infrastructure they use, not theoretical capacity. 2. **Efficient grid utilization (Effektivt nätutnyttjande):** Power-based pricing incentivizes load spreading to flatten peaks and defer expensive grid expansion. This regulatory shift is critical to developers: your plugin needs to understand tariffs from both legacy fuse-based subscriptions (still common for residential \<63A) and the emerging power-based models (rapidly expanding to all customer segments). ## Tariff Structure ### Subscription Types Swedish grid tariffs are typically structured into several subscription categories: #### 1. Apartment Subscriptions (Lägenhet) * For apartments with shared grid connections * Simple pricing: Fixed monthly fee + energy-based transfer charge (öre/kWh) * Typically for connections with 16A, but also up to 35A single-phase * No power-based component #### 2. Fuse-Based Subscriptions (Säkringsabonnemang) **For residential and small commercial customers (16-63A, sometimes up to 200A)** Traditional model still used by some customers: * **Fixed monthly fee** - Based on main fuse size (kr/månad) * **Transfer fee** - Volume-based charge (öre/kWh) * May offer choice between: * **Single tariff** (Enkeltariff) - Same rate year-round * **Time-differentiated tariff** (Tidstariff) - Higher rates during winter peak hours #### 3. Power-Based Subscriptions (Effektabonnemang) **Historically for customers with 80A or higher connections** Modern pricing model increasingly becoming standard: * **Fixed monthly fee** - Base subscription charge (kr/månad) * **Transfer fee** - Volume-based charge (öre/kWh) * **Power fee** - Capacity-based charge (kr/kW per month or year) The power fee is typically calculated as the **average of the three highest hourly peaks** measured over **three different days** during the billing period (usually monthly). **Night discount:** Many DSOs apply a 50% reduction to measured capacity during night hours (22:00-06:00), meaning a 10 kW peak at night counts as only 5 kW for billing purposes. API reponse for subscription types here:\ [https://docs.engrate.io/api-reference/get-by-mga-code#response-data-subscription-category](https://docs.engrate.io/api-reference/get-by-mga-code#response-data-subscription-category) ### Time-of-Use Differentiation Many tariffs differentiate pricing by time: #### Peak Period (Högpris) * **Months:** November through March (winter) * **Days:** Monday through Friday (weekdays) * **Hours:** 06:00 - 22:00 (can be individual per DSO) * Higher rates during these periods reflect increased grid stress #### Off-Peak Period (Lågpris) * **Months:** April through October (summer) * **Days:** Weekends and public holidays * **Hours:** 22:00 - 06:00 (nights) * Lower rates during periods of reduced grid demand ### Seasonal Variations #### Winter Pricing (November - March) * Peak/off-peak time differentiation active * Higher grid tariffs overall * Reflects maximum grid utilization during cold, dark months * Critical for grid cost recovery #### Summer Pricing (April - October) * Often flat-rate pricing (no time differentiation) * Lower overall grid charges * Reflects lower grid stress and maintenance periods ### The Swedish DSO & Grid Architecture Sweden has approximately 170 distribution system operators, ranging from major national players (Ellevio, Vattenfall Eldistribution, E.ON) to small municipal utilities. Each DSO operates independently within their regional service area and sets their own tariffs within regulatory guidelines. The physical electricity infrastructure is hierarchical: Transmission System (run by SvK - Svenska Kraftnät)\ ↓\ Regional Grid Areas run by regional DSOs\ ↓\ Local Grid Areas - smallest operational unit, serviced by local DSOs **Metering Grid Areas (MGA)** are the granular building blocks of Sweden's electricity system. Each MGA typically corresponds to a single DSO's service area, though larger DSOs may operate multiple MGAs. MGAs are identified by unique 3-letter codes (e.g., "STH" for Ellevio Stockholm area, "GBG" for Gothenburg area). When querying power tariffs via the Engrate API, you'll specify an MGA code to receive applicable tariff rules. ## Which Variables Determine the grid fees The actual payment that a customer has to do regarding the usage of the grid depends on a couple of variables: **Fuse Size (Säkring):** A customer chooses their fuse size according to the expected maximum power they need at the connection point. Its size is defined in Amperes (A). The higher the value, the more the DSO charges (in the legacy tariff model). The fuse size can be changed in alignment with the DSO. **Important:** Every instantaneous peak power that is above the fuse size's capacity will trip the circuit breaker, breaking the connection and causing a blackout. For a three-phase 400V connection with a 63A fuse, the maximum power is approximately 0.693 × A (e.g., 63A = \~43.7 kW). **Consumption (Energi):** The total amount of electricity used over a period of time. Measured in kilowatt-hours (kWh). Consumption is what you accumulate—it's the integral of power over time. Example: a villa that uses electricity constantly throughout a month will accumulate, say, 1,500 kWh. Under power-based tariffs, consumption determines the variable transfer charge (öre/kWh). Formula: `kWh = kW × hours` **Power (Effekt):** The instantaneous rate at which electricity is being drawn at any given moment. Measured in kilowatts (kW). Power fluctuates throughout the day based on which appliances are running. Example: at 18:00 when cooking dinner and charging an electric car simultaneously, a household might draw 12 kW; at 3 AM when everything is off, it might draw only 0.5 kW. Under power-based tariffs, the peak power (specifically the average hourly power during peak hours) determines the power charge (effektavgift). Formula: `kW = kWh ÷ hours` **The Key Distinction:** * **Consumption (kWh):** "How much total energy did I use?" → Determines transfer charges * **Power (kW):** "How much am I using right now?" → Determines demand charges and breaker limits **Subscribed Power (Abonnerad Effekt):** A customer declares their expected maximum power need from the grid for the coming period (typically one year). The DSO approves this subscribed power level based on the customer's historical usage or stated requirements. This replaces the physical limitation of fuse size with a contractual agreement. The subscribed power is typically calculated as the average of the customer's highest monthly power peaks from the previous year. Under power-based tariffs, a fixed annual or monthly fee is charged based on the subscribed power level (e.g., kr/kW/year). **Important:** If a customer's measured power exceeds their subscribed power (called "overtrading" or övertrassering), they are charged a penalty fee -typically double the normal power charge - on the excess power. Example: a customer subscribes to 200 kW but one month has a peak of 220 kW; they pay the overtrading penalty on 20 kW. This model provides flexibility: customers can adjust their subscribed power level annually based on changing business needs, but must manage peaks within their declared limit or face financial penalties. **Subscribed Power vs. Fuse Size:** * **Fuse Size (legacy):** Physical safety limit; exceeding it causes immediate disconnection (circuit breaker trips) * **Subscribed Power (modern):** Contractual limit; exceeding it causes financial penalty but allows continued operation **Voltage Level (Spänningsnivå):** The electrical potential at which a customer's connection point is connected to the grid. Different voltage levels serve different customer sizes and geographic coverage areas. **Low voltage (lågspänning):** 230V single-phase or 400V three-phase. Used for residential customers, apartments, small businesses, and rural areas. Typical DSO connections. **High voltage (högspänning):** 6 kV, 10 kV, 20 kV, or higher. Used for industrial facilities, large commercial buildings, and data centers. Connected to regional grid operators or local DSOs. The voltage level significantly affects tariff structure and cost. Low-voltage customers typically pay simpler tariffs with fewer components (fixed fee + transfer charge + power charge). High-voltage customers face more complex tariffs with multiple components, including annual power subscriptions, distance-dependent fees, reactive power charges, and network loss compensation. Higher voltage levels generally have lower per-unit costs (kr/kW) but require sophisticated metering and contractual agreements. Example: a high-voltage industrial customer at 20 kV pays regional grid tariffs with rates like 200 SEK/kW/year, while a residential customer at 400V pays local DSO tariffs with rates like 45 kr/kW/month. **Important:** The Engrate API returns tariffs for low-voltage (DSO) and high-voltage (local or regional grid) connections based on the customer's connection point. **Active Energy (Arbetande Energi):** The electrical energy that performs useful work—heating, lighting, motor operation, etc. Measured in kilowatt-hours (kWh). This is the energy customers typically think of when they talk about "electricity consumption." All DSO tariffs charge for active energy consumed via the transfer charge (överföringsavgift) in öre/kWh. Example: a household that heats water, cooks dinner, and charges an electric car consumes active energy (kWh) which is measured by the meter and billed at the transfer rate. **Reactive Energy (Reaktiv Energi):** Electrical energy that oscillates back and forth in the circuit without performing useful work. Caused by inductive loads (motors, transformers, fluorescent lights) and capacitive loads. Measured in kilovolt-ampere-reactive-hours (kVArh) or simply reactive power in kilovolt-ampere-reactive (kVAr). Reactive energy causes grid stress by increasing peak demand without producing output, forcing DSOs and regional grid operators to invest in larger infrastructure. **DSO/Regional Grid Operator Treatment:** Residential customers typically don't pay for reactive energy—it's absorbed as part of grid operations. Industrial and high-voltage commercial customers are charged for excessive reactive power that exceeds a permitted threshold (typically 30–50% of active power). Charges range from 15–80 SEK/kVAr depending on voltage level and DSO. Example: a manufacturing plant with large motors may have a reactive power charge of 50 SEK/kVAr/month in addition to their active energy charges. **Power Factor (Effektfaktor):** The ratio of active power to total power, expressed as cos(φ) or as a percentage. A power factor of 1.0 (or 100%) means all power is active (no reactive waste). Industrial facilities with poor power factors (e.g., 0.85 or 85%) waste significant reactive energy and face higher tariffs. Improving power factor through capacitor banks or synchronous motors reduces reactive charges and improves grid efficiency. # Get All Source: https://docs.engrate.io/api-reference/get-all https://api.engrate.io/v1/power-tariffs/openapi.json get /power-tariffs/{country_code} Get all power tariffs for a given country. # Get by Address Source: https://docs.engrate.io/api-reference/get-by-address https://api.engrate.io/v1/power-tariffs/openapi.json get /power-tariffs/{country_code}/address/{address}/city/{city} Get power tariffs by address. # Get by Coordinates Source: https://docs.engrate.io/api-reference/get-by-coordinates https://api.engrate.io/v1/power-tariffs/openapi.json get /power-tariffs/{country_code}/lat/{lat}/lon/{lon} Get power tariffs by latitude and longitude. # Get by EDIEL Code Source: https://docs.engrate.io/api-reference/get-by-ediel-code https://api.engrate.io/v1/power-tariffs/openapi.json get /power-tariffs/{country_code}/ediel/{ediel} Get power tariffs by grid operator EDIEL code. # Get by ID Source: https://docs.engrate.io/api-reference/get-by-id https://api.engrate.io/v1/power-tariffs/openapi.json get /power-tariffs/{country_code}/tariff-uid/{tariff_uid} Get Power Tariff by ID. # Get by MGA Code Source: https://docs.engrate.io/api-reference/get-by-mga-code https://api.engrate.io/v1/power-tariffs/openapi.json get /power-tariffs/{country_code}/mga/{mga_code} Get power tariffs by metering grid area code. # Get by Postal Code Source: https://docs.engrate.io/api-reference/get-by-postal-code https://api.engrate.io/v1/power-tariffs/openapi.json get /power-tariffs/{country_code}/postal-code/{postal_code} Get power tariffs by postal code. # Get Grid Operators Source: https://docs.engrate.io/api-reference/get-grid-operators https://api.engrate.io/v1/power-tariffs/openapi.json get /power-tariffs/{country_code}/grid-operators Get a list of all grid operators (DSOs) with their names and EDIEL codes. # Get Holidays Source: https://docs.engrate.io/api-reference/get-holidays https://api.engrate.io/v1/power-tariffs/openapi.json get /power-tariffs/{country_code}/holidays Get a list of public and bank holidays for a given country and year(s) # Get Tariff Source: https://docs.engrate.io/api-reference/get-tariff /openapi.json get /cost-of-energy/v1/tariffs/{tariff_id} Get a single [Tariff](/api-reference/cost-of-energy/models/tariff) by ID. # List Areas Source: https://docs.engrate.io/api-reference/list-areas https://api.engrate.io/v1/electricity-area-map/openapi.json get /electricity-area-map/areas Find electricity areas based on specified query. No querystring returns all areas. If you query by lat you also need to provide lng and vice versa. # List Datasets Source: https://docs.engrate.io/api-reference/list-datasets /openapi.json get /cost-of-energy/v1/datasets List all [Registered Datasets](/api-reference/cost-of-energy/models/dataset) # List Metering Grid Areas Source: https://docs.engrate.io/api-reference/list-metering-grid-areas /openapi.json get /core/v1/metering-grid-areas List & filter Metering Grid Areas. If you specify multiple values for some filter parameter they are OR-ed. If you specify multiple separate filters they are "AND"-ed. For instance if you specify country=SE&country=DK, you'll get MGAs in Denmark and Sweden. If you specify country=DK&city=Stockholm you'll get no results as no MGAs cover both Stockholm and Denmark. See [Metering Grid Area](/api-reference/core/models/metering-grid-area) for details on MeteringGridArea. # List Parties Source: https://docs.engrate.io/api-reference/list-parties /openapi.json get /core/v1/parties List & filter market parties. If you specify multiple values for some filter parameter they are OR-ed. If you specify multiple separate filters they are "AND"-ed. See [Party](/api-reference/core/models/party) for details on Parties. # List Tariffs Source: https://docs.engrate.io/api-reference/list-tariffs /openapi.json get /cost-of-energy/v1/tariffs List [Tariffs](/api-reference/cost-of-energy/models/tariff). Multiple values within a single parameter are combined with OR. Different parameters are combined with AND. Omitting all parameters returns all published tariffs. # Calculate Imbalance Source: https://docs.engrate.io/api-reference/mabis/calculate-imbalance https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/mabis/clearing-periods/{uid}/imbalance Calculate energy imbalance for a clearing period. Compares the scheduled values (from submitted schedules) against the actual metering values (from MSCONS messages) for each day of the clearing period. The imbalance cost uses the reBAP price (Regelenergiebilanzausgleichspreis) received via PRICAT from the TSO. Returns total scheduled/actual MWh, total imbalance MWh and cost EUR, and a per-day breakdown. # Create Clearing Period Source: https://docs.engrate.io/api-reference/mabis/create-clearing-period https://api.engrate.io/schedule-management/v1/openapi.json post /schedule-management/v1/mabis/clearing-periods Create a new MaBiS clearing period. A clearing period represents one Bilanzierungsmonat for a Bilanzkreis. The deadlines should match the MaBiS calendar: preliminary at M+18 WT, objection window closing at M+30 WT, and final settlement at M+42 WT. Use `GET /mabis/clearing-calendar` to calculate the exact dates for a given month. # Create Objection Source: https://docs.engrate.io/api-reference/mabis/create-objection https://api.engrate.io/schedule-management/v1/openapi.json post /schedule-management/v1/mabis/clearing-periods/{uid}/objections Submit a MaBiS objection (Einspruch) for a clearing period. An objection disputes the TSO's settlement values within the clearing window (M+10 to M+30 WT per BK6-24-174). The TSO will respond via UTILMD with acceptance or rejection, updating the objection status. The `disputed_values` field is a free-form dict describing the contested data (e.g., `{"date": "2026-01-15", "interval": 42, "value_mwh": 1.5}`). # Get Clearing Calendar Source: https://docs.engrate.io/api-reference/mabis/get-clearing-calendar https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/mabis/clearing-calendar Get MaBiS clearing deadlines for a settlement month. Returns all relevant MaBiS clearing deadlines based on Werktag (working day, Mon–Fri excluding DE public holidays) calculations per BK6-24-174 Section 3.10. **Key deadlines** - Erstaufschlag BG-SZR: M+10 WT — TSO publishes initial balance group summary - Erstaufschlag BK-SZR: M+12 WT — TSO publishes initial balance circle summary - Clearing start BG-SZR: M+11 WT - Clearing start BK-SZR: M+13 WT - Preliminary billing: M+18 WT - Clearing end: M+30 WT — objection window closes - Final billing: M+42 WT **Current phase values**: 'erstaufschlag', 'clearing', 'final', 'closed' Example: pass `bilanzierungsmonat=2026-01-01` to get deadlines for January 2026. # Get Clearing Period Source: https://docs.engrate.io/api-reference/mabis/get-clearing-period https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/mabis/clearing-periods/{uid} Get detailed clearing period with aggregated summary. Returns the clearing period header plus counts of settlements, objections, and messages, the total imbalance, and the next upcoming MaBiS deadline (preliminary at M+18 WT or final at M+42 WT). # Get Control Energy Prices Source: https://docs.engrate.io/api-reference/mabis/get-control-energy-prices https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/mabis/control-energy-prices Get control energy prices (reBAP) for settlement calculations. Returns balancing energy prices (Regelzonenübergreifender Bilanzausgleichsenergiepreis) received from TSOs via PRICAT messages. Args: tso_area: Optional filter by TSO control area (e.g., 10YDE-VE-------2) month: Optional filter by month (YYYY-MM format) Returns: List of control energy price records with interval data # Get Monthly Summary Source: https://docs.engrate.io/api-reference/mabis/get-monthly-summary https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/mabis/energy-volumes/{mabis_zp_id}/monthly-summary Get monthly energy summary and cost calculation. Returns the monthly energy totals and optional cost calculation for a specific MaBiS-Zählpunkt. Uses the latest version (by message_date). Args: mabis_zp_id: MaBiS-Zählpunkt identifier bilanzierungsmonat: Settlement month (first day of month) tso_area: TSO control area EIC (required for cost calculation) Returns: Monthly summary with energy and optional cost data # List Aggregation Objects Source: https://docs.engrate.io/api-reference/mabis/list-aggregation-objects https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/mabis/aggregation-objects List registered aggregation objects. Returns aggregation objects registered via UTILMD messages for energy settlement purposes. BRP is automatically filtered via org_uid. Args: tso: Optional TSO Y area code filter (e.g., 10YDE-EON------1) sender: Optional sender MP-ID filter (DSO) - returns MGAs managed by this DSO aggregation_object: Optional specific object ID filter aggregation_type: Optional type filter (BAS, SLP, RLM) aggregation_subtype: Optional OBIS code filter month: Optional month for validity check (YYYY-MM) Returns: List of matching aggregation objects # List Clearing Periods Source: https://docs.engrate.io/api-reference/mabis/list-clearing-periods https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/mabis/clearing-periods List MaBiS clearing periods for the organization. A clearing period covers one calendar month (Bilanzierungsmonat) for a given balance group (Bilanzkreis). The MaBiS process starts at M+5 WT (Erstaufschlag) and closes at M+42 WT (final settlement). Filters: - status: Filter by status — 'open', 'preliminary', 'objection', 'final', 'closed' - bilanzkreis_eic: Filter by balance group EIC X code (16-char, starts with '11X') # List Energy Volumes Source: https://docs.engrate.io/api-reference/mabis/list-energy-volumes https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/mabis/energy-volumes List energy volumes from MSCONS messages. Returns energy volume records stored from parsed MSCONS messages, ordered by message_date descending (latest first). Args: mabis_zp_id: Optional filter by MaBiS-Zählpunkt ID aggregation_object_uid: Optional filter by linked aggregation object bilanzierungsmonat: Optional filter by settlement month Returns: List of energy volume records # List Messages Source: https://docs.engrate.io/api-reference/mabis/list-messages https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/mabis/clearing-periods/{uid}/messages List EDIFACT messages for a clearing period. Filters: - message_type: IFTSTA, UTILMD, MSCONS, PARTIN - direction: inbound, outbound - status: pending, sent, delivered, acknowledged, etc. # List Objections Source: https://docs.engrate.io/api-reference/mabis/list-objections https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/mabis/clearing-periods/{uid}/objections List objections filed for a clearing period. Filters: - status: Filter by status — 'pending', 'submitted', 'accepted', 'rejected', 'withdrawn' # List Settlements Source: https://docs.engrate.io/api-reference/mabis/list-settlements https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/mabis/clearing-periods/{uid}/settlements List daily settlement records for a clearing period. Each record represents one calendar day of MSCONS metering data received from the TSO/DSO. The `values` field contains the raw interval data as parsed from the MSCONS EDIFACT message. # Send Response To Aggregation Time Series Source: https://docs.engrate.io/api-reference/mabis/send-response-to-aggregation-time-series https://api.engrate.io/schedule-management/v1/openapi.json post /schedule-management/v1/mabis/send-response-to-aggregation-time-series Send accept/reject response to an aggregation time series (BAS/ASZR). Submits an IFTSTA message to the TSO/BIKO accepting or rejecting the aggregation time series data for a given month and version. Args: month: Settlement month (YYYY-MM format, e.g. '2026-01') version_id: Version identifier from the incoming UTILMD message answer: True to accept the values, False to reject request: Aggregation object details Returns: Response status (currently a stub — see TODO in implementation) # Validate Clearing Data Source: https://docs.engrate.io/api-reference/mabis/validate-clearing-data https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/mabis/clearing-periods/{uid}/validate Validate clearing data completeness for a clearing period. Checks that: - All expected settlement days have MSCONS data - The required EDIFACT messages are present - The clearing period status allows submission Returns a `valid` flag, counts of settlements/messages vs expected, and a list of human-readable `issues` describing any gaps found. # Check Exchange Priority Source: https://docs.engrate.io/api-reference/schedules/check-exchange-priority https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/reference/exchange-priority-check/{eic_code} Check if a specific balance group has exchange priority. Useful for the UI to flag counterparties with Börsenvorrang when displaying ANO reconciliation data. Args: eic_code: EIC code of the balance group to check. # Create Schedule Source: https://docs.engrate.io/api-reference/schedules/create-schedule https://api.engrate.io/schedule-management/v1/openapi.json post /schedule-management/v1/schedules Create a new schedule or a new version of an existing schedule. Re-submitting for the same TSO + delivery date creates a new version. The TSO message ID is reused with an incremented version number as required by market rules (MaBiS for DE, MMC Hub for NL). **Submission flow** 1. Validate gate closure (skipped when `test=true`) 2. Validate EIC codes, business types, and interval counts 3. Build ESS XML (DE) or CIM XML (NL) 4. Submit to TSO via AS4 messaging 5. Create audit event 6. Return the created schedule version **Gate closure (DE, per AG-FPM)** - Day-ahead: open until D-1 14:30 CET for all series types - DA matching (D-1 14:30–16:00 CET): internal series accepted; external/foreign corrections only - Intraday: D-1 16:00 CET until GCT (15-minute lead time for external/foreign) **Gate closure (NL)** - Day-ahead window: D-2 10:00 CET to D-1 15:00 CET # Get Delivery Status Source: https://docs.engrate.io/api-reference/schedules/get-delivery-status https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/schedules/{uid}/delivery-status Get delivery status (NRR) for a schedule. Returns the AS4 delivery status for the TSO + delivery date combination. The NRR (Non-Repudiation of Receipt) confirms the TSO received the message. **Status values** - `pending`: submission sent, NRR not yet received - `nrr_received`: TSO acknowledged receipt (AS4 NRR) - `submitted`: accepted by the TSO message broker - `rejected`: TSO rejected the submission (check `tso_message_id` for details) # Get Schedule Source: https://docs.engrate.io/api-reference/schedules/get-schedule https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/schedules/{uid} Get a specific schedule by UID. Returns the schedule header (market, TSO, delivery date). Use `GET /schedules/{uid}/versions` to retrieve submitted versions. # Get Schedule Anomalies Source: https://docs.engrate.io/api-reference/schedules/get-schedule-anomalies https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/schedules/{uid}/anomalies List all anomaly time series records for a schedule. Returns the full interval data from TSO AnomalyReport (ANO) messages, showing the counterparty's values as seen by the TSO. Works for both DE and NL schedules. # Get Schedule Reconciliation Source: https://docs.engrate.io/api-reference/schedules/get-schedule-reconciliation https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/schedules/{uid}/reconciliation Side-by-side reconciliation of our values vs counterparty values. Matches ANO time series to our schedule series and computes per-interval deltas for reconciliation. Works for both DE and NL schedules. DE: Flags counterparties with exchange priority (Börsenvorrang). NL: Only mismatched positions are present in the anomaly report. # Get Schedule Version Source: https://docs.engrate.io/api-reference/schedules/get-schedule-version https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/schedules/{uid}/versions/{version_number} Get a specific version of a schedule by version number. Version numbers start at 1 and increment with each re-submission for the same TSO + delivery date. The TSO message ID carries a `_v{N}` suffix matching the version number. # List Audit Logs Source: https://docs.engrate.io/api-reference/schedules/list-audit-logs https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/audit-logs Query audit logs with optional filters. Filters: - schedule_uid: Filter by related schedule - order: NEWEST_FIRST (default) or OLDEST_FIRST - limit: Maximum number of results (default 50, max 1000) # List Exchange Priority Balance Groups Source: https://docs.engrate.io/api-reference/schedules/list-exchange-priority-balance-groups https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/reference/exchange-priority-balance-groups List all balance groups with exchange priority (Börsenvorrang). These balance groups have priority per clause 12.b of the Bilanzkreisvertrag. When scheduling conflicts occur (ANO), the exchange party's values may be imposed by the TSO. # List Incoming Messages Source: https://docs.engrate.io/api-reference/schedules/list-incoming-messages https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/schedules/{uid}/incoming-messages List all incoming TSO messages for a schedule. Returns metadata for each response received from the TSO. Works for both DE and NL schedules. **DE document types** (MaBiS/ESS via Mako365): - `A01`: Confirmation (CNF) — TSO accepted the schedule - `A02`: Anomaly (ANO) — TSO detected a mismatch with counterparty values - `A09`: Acknowledgement (ACK) — technical receipt confirmation **NL document types** (CIM XML via TenneT MMC Hub): - `A05`: Confirmation - `A06`: Anomaly # List Schedule Series Source: https://docs.engrate.io/api-reference/schedules/list-schedule-series https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/schedule-series/{version_uid} List all series in a schedule version. Each series corresponds to one time series submitted to the TSO (one row in the ESS XML for DE, or one TimeSeries block in the CIM XML for NL), with the full interval data and EIC identifiers. # List Schedule Versions Source: https://docs.engrate.io/api-reference/schedules/list-schedule-versions https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/schedules/{uid}/versions List all versions of a schedule. Annotates each version with is_active=False if it belongs to a rejected/different message ID than the authoritative TSO message ID. # List Schedules Source: https://docs.engrate.io/api-reference/schedules/list-schedules https://api.engrate.io/schedule-management/v1/openapi.json get /schedule-management/v1/schedules List all schedules for the authenticated organization. Filters: - market: Filter by market (DE or NL) - tso: Filter by TSO (e.g., "50HERTZ_DE_TSO") - date_from: Start date filter (YYYY-MM-DD) - date_to: End date filter (YYYY-MM-DD) # Send Status Request Source: https://docs.engrate.io/api-reference/schedules/send-status-request https://api.engrate.io/schedule-management/v1/openapi.json post /schedule-management/v1/send_status_request Send a status request to TSO. Queries the current status of schedule applications for a specific delivery date. The TSO responds with an ACK or CNF containing the current status. Rate limited to 1 request per 15 minutes per balance group per delivery day. Args: request: Status request parameters (sender_id, receiver_id, date) org_uid: Organization UID from request headers service: Status request service Returns: StatusRequestResponse with message_id and status Raises: 429: Rate limit exceeded (max 1 per 15 min) 400: Invalid request parameters 502: TSO communication error # Changelog Source: https://docs.engrate.io/changelog/product-updates Product & technology updates and announcements Schedule Management now implements AG-FPM v4.6 process-phase-aware gate closure with separate handling for day-ahead, DA matching, and intraday phases. New audit trail events cover declared-limit breach warnings (A59), fault-tolerant acceptance (A57/A21), no-ACK timeout detection, and intraday submission advisories (close-to-QH and multiple-versions-per-QH). Schedule submissions past gate closure now proceed with a warning logged to the audit trail instead of returning an error. Submissions with non-consecutive or duplicate 15-minute interval timestamps now return a 400 validation error. We've launched **console.engrate.io** - a completely redesigned application replacing the previous app.engrate.io. The new console features a modern design system and serves as the central hub for all Engrate products. **What's new:** * **Refreshed dashboard** with improved navigation and overview of your resources * **Power Tariff management** now fully integrated in the console * **Schedule Management** with audit logs, debugging tools, and detailed views Log in at [console.engrate.io](https://console.engrate.io) to explore. **app.engrate.io** now automatically redirects to **console.engrate.io**. Schedule graphs
Schedule Management in the new console
Schedule Management in the new console New endpoint to retrieve public and bank holidays for supported countries. Useful for tariff calculations where holiday pricing differs from regular weekday rates. Check out the [holidays endpoint](https://docs.engrate.io/api-reference/get-holidays). Power Tariff now supports price levels with a configurable price tier system. You can choose between: * **No tiers** - Single flat-rate pricing * **Stacked** - Each tier applies only to power within its range * **Stepwise** - Entire power is charged at the rate of the tier it falls into This enables flexible pricing models for all components. Check out the [price level definition](https://docs.engrate.io/api-reference/get-by-id#response-power-tariff-components-items-one-of-0-data-price-levels). The Power Tariff product has been extended with *The Engrate Power Tariff Calculator Engine* and is now readily available for your calculation needs. Check it out the [calculation endpoint](https://docs.engrate.io/api-reference/calculate-cost). Power Tariff is now out of Early Access! Go build! Early Access customer can safely switch from: > `api.ea.engrate.io` to `api.engrate.io` A new model for Power Tariff is now out. We've redesigned it to make it simpler from our customer feedback. Check out the updated documentation here: [https://docs.engrate.io/api-reference/get-by-mga-code](https://docs.engrate.io/api-reference/get-by-mga-code) Today we're adding Electricity Area Map. This product provides comprehensive access to electricity area boundaries from all Swedish Distribution System Operators (DSOs), Market Balance Areas (MBAs), and Market Grid Areas (MGAs). Check it out here: [https://docs.engrate.io/api-reference/list-areas](https://docs.engrate.io/api-reference/list-areas) Vibe Coded Map The Power Tariff product is now live in early access! You can sign up for it here: [https://engrate.io/effektavgifter](https://engrate.io/effektavgifter) Pt Hero Pn # Authentication Source: https://docs.engrate.io/guides/authentication ## Overview This guide explains how to authenticate with our API using API keys. This authentication method is designed for server-to-server communication where your application needs to access API resources on its own behalf. ## Prerequisites Before you begin, ensure you have an **Api Key**, which you can create at [https://console.engrate.io](https://console.engrate.io) ## Examples ### Making API requests ```bash Request theme={null} curl --request GET \ --url https://api.engrate.io/v1/power-tariffs/SE/lat/57.727011/lon/14.155703 \ --header 'authorization: $API_KEY' --header "content-type: application/json" ``` ```json Response theme={null} [ { "uid": "01993426-ab3f-7150-99e3-00b98916d496", "name": "Standard fee", "model": "avg_monthly_peaks", "samplesPerMonth": 2, ... } ] ``` # Connect via MCP Source: https://docs.engrate.io/guides/mcp Give your AI agent direct access to up-to-date energy data and integrations ## Supported clients We use [OAuth 2.0 Dynamic Client Registration](https://curity.io/resources/learn/openid-connect-understanding-dcr/) for secure authentication, making the Power Tariffs MCP compatible with any client supporting this industry-standard flow. ## Getting Started For a step-by-step walkthrough of how to connect to a Remote MCP Server please see the [official documentation](https://modelcontextprotocol.io/docs/develop/connect-remote-servers#connecting-to-a-remote-mcp-server). For completing the process you'll need 2 things: * An [Engrate account](/guides/authentication) * The **Remote MCP Server URLs** which are: ```sh theme={null} https://docs.engrate.io/mcp https://api.engrate.io/v1/mcp/power-tariffs https://api.engrate.io/v1/mcp/electricity-area-map ``` ### Example: Connecting Claude to Engrate Integrations As an administrator of your company's organization, you can add custom connectors to enable your teams to access all Engrate integrations available to your organization. For complete details on custom connectors, refer to the official Anthropic documentation [here](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp). Navigate to **Admin settings** and click **Add custom connector**. Mcp Claude Step 0 Pn Click **Connect** on the newly added Engrate connector. Mcp Claude Step 1 Pn Log in with your Engrate account credentials. This initiates OAuth 2.0 Dynamic Client Registration, which automatically provisions secure credentials for your organization's Claude instance and establishes an authorized connection to Engrate's APIs. Mcp Claude Step 2 Pn Your prompts now have direct access to Electricity Area Map data. Claude can query grid areas, DSO information, and geographical boundaries to create insights, generate documents, and build prototypes using your organization's Engrate integrations. Add the Power Tariffs MCP connector to also enable real-time tariff data access. Mcp Claude Step 4 Pn ## Connect to Engrate documentation Connecting your IDE or editor to Engrate's documentation MCP server provides AI-assisted access to our API documentation, code examples, and integration guides directly in your development environment. You can always use the ***Contextual menu*** at the top of this page (arrow right next to "Copy page") to quickly add documentation to various options Mcp Context Pn To connect the Engrate MCP server to VS Code, click the **Install in VS Code** button in the Contextual menu. Or manually connect the MCP server, create a `.vscode/mcp.json` file and add: ```json theme={null} { "mcp": { "servers": { "Engrate Developer": { "url": "https://docs.engrate.io/mcp" } } } } ``` See the [**VS Code documentation**](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details. To connect the Mintlify MCP server to Cursor, click the **Install in Cursor** button in the contextual menu. Or manually connect the MCP server, follow these steps: 1. Use **Command** + **Shift** + **P** (**Ctrl** + **Shift** + **P** on Windows) to open the command palette. 2. Search for “Open MCP settings”. 3. Select **Add custom MCP**. This will open the `mcp.json` file. In `mcp.json`, add: ```json theme={null} { "mcpServers": { "Engrate Developer": { "url": "https://docs.engrate.io/mcp" } } } ``` In Cursor’s chat, ask “What tools do you have available?” Cursor should show the Engrate Developer MCP server as an available tool. See [**Installing MCP servers**](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) in the Cursor documentation for more details. To use the Engrate documentation MCP server with Claude Code, run the following command: ```shellscript theme={null} claude mcp add --transport http Engrate https://docs.engrate.io/mcp ``` Test the connection by running: ```shellscript theme={null} claude mcp list ``` See the [**Claude Code documentation**](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details. 1. Navigate to the [**Connectors**](https://claude.ai/settings/connectors) page in the Claude settings. 2. Select **Add custom connector**. 3. Add the Engrate documentation MCP server: * Name: `Engrate Developer` * URL: `https://docs.engrate.io/mcp` 4. Select **Add**. 1. When using Claude, select the attachments button (the plus icon). 2. Select the Engrate Developer server. 3. Ask Claude a question about Engrate developer documentation. # Video Walkthrough Source: https://docs.engrate.io/guides/video-walkthrough Co-founder and CTO Richard walks through the Engrate platform