# Electricity maps

![App schema](https://raw.githubusercontent.com/eliona-smart-building-assistant/electricity-maps-app/refs/heads/develop/schema.png)

### Installation

Install the Electricity Maps app via the Eliona App Store.

### Configuration

#### Registration with Electricity Maps

1. Create an account at [Electricity Maps](https://www.electricitymaps.com/)
2. Subscribe to the appropriate API plan (free version available for basic use in one region)
3. Generate an API key in your account settings and save it for the Eliona configuration

#### Configuration of the Electricity Maps app

Configurations can be created in Eliona under `Settings > Apps > Electricity Maps` which opens the app interface. [Generic Frontend](https://doc.eliona.io/collection/v/eliona-english/manuals/settings/apps) Use the configuration endpoint with the PUT method.

The configuration requires the following data:

| Attribute       | Description                                                             | Required          |
| --------------- | ----------------------------------------------------------------------- | ----------------- |
| apiKey          | Electricity Maps API key from the previous step                         | Yes               |
| enable          | Flag to enable/disable this configuration                               | Yes               |
| refreshInterval | Interval in seconds for data synchronization (at least 300 recommended) | Yes               |
| requestTimeout  | API query timeout in seconds                                            | No (default: 120) |
| projectIDs      | List of Eliona project IDs for data collection                          | Yes               |

Example configuration JSON:

```json
{
  "apiKey": "your-api-key",
  "enable": true,
  "refreshInterval": 900,
  "requestTimeout": 120,
  "projectIDs": [
    "10"
  ]
}
```

### Asset creation

After configuration, the app creates an asset type `Electricity Zone`. You can create multiple assets of this type, each representing a geographic zone to be monitored.

### Configuration of Electricity Zone locations

1. Create a new asset of type `Electricity Zone`
2. Click the asset's edit button
3. In the "More information" section, set the zone identifier (e.g. "CH" or "Switzerland" for Switzerland, "DE" or "Germany" for Germany)
4. Save the asset configuration
5. Refresh the page to check whether the app has correctly identified the zone

The asset will then be populated with grid data:

| Attribute                | Description                                            | Unit       |
| ------------------------ | ------------------------------------------------------ | ---------- |
| carbon\_intensity        | CO₂ intensity of electricity consumption               | gCO₂eq/kWh |
| renewable\_percentage    | Share of renewable energy in electricity consumption   | %          |
| fossil\_free\_percentage | Share of fossil-free energy in electricity consumption | %          |

### App status monitoring

The app creates a root asset called "Electricity Maps Root", which provides information about the app's status:

* Asset status: Active/Inactive indicates whether the app is running
* Status attribute: Shows the current operating status. If the app status is not "OK", this indicates that the app may not be functioning properly. If the error condition persists, let us know by submitting a bug report.

### Use cases

The Electricity Maps app enables:

* Real-time monitoring of the grid's CO₂ intensity
* Tracking the share of renewable energy
* Optimization of energy procurement
* ESG reporting and sustainability tracking
* Load management strategies based on grid composition
* CO₂-aware load shifting