> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engrate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cost of Energy API Overview

> Calculate the cost of energy

The Cost of Energy API allows you to calculate or optimise 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
* Pipelines can be evaluated deterministically (calculation mode) or compiled into an optimisation model (optimisation mode), against the same definitions
* 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:

* Call our Calculate endpoint 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<br/><small>hourly · kWh</small>")
        mul("multiply<br/><small>× 36.0 SEK_per_kWh</small>")
        con("constant<br/><small>45.0 SEK · monthly</small>")
        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("Calculate or optimise<br/>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.

For optimisation, step 3 becomes embedding the pipelines in your model rather than evaluating them — see [In Optimisation](/api-reference/cost-of-energy/optimisation).