Skip to content

feat(ElectricityMaps source): unify ElectricityMaps and ElectricityMapsFree #619

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Apr 14, 2025
Merged

feat(ElectricityMaps source): unify ElectricityMaps and ElectricityMapsFree #619

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b086396
refactor(ElectricityMaps): unify ElectricityMaps and ElectricityMapsFree
unitrium Mar 10, 2025
e3ba7d1
remove free trial mention
unitrium Mar 10, 2025
ced86c7
DCO Remediation Commit for Robin TROESCH <[email protected]…
unitrium Mar 10, 2025
ea41012
fix(carbon-aware-web-api): fix integration test with json src
unitrium Mar 18, 2025
1c3a86a
DCO Remediation Commit for Robin TROESCH <[email protected]…
unitrium Mar 18, 2025
726e86a
add API TokenHeader and APIToken config
lav-julien Apr 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions casdk-docs/docs/architecture/c-sharp-client-library.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,7 @@ The following namespaces are included:

There are two main classes that represents the data fetched from the data
sources (i.e `Static Json`, [WattTime](https://www.watttime.org),
[ElectricityMaps](https://www.electricitymaps.com), and
[ElectricityMapsFree](https://www.co2signal.com/)):
[ElectricityMaps](https://www.electricitymaps.com)):

- `EmissionsData`
- `EmissionsForecast`
Expand Down
3 changes: 1 addition & 2 deletions casdk-docs/docs/architecture/data-sources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,7 @@ sidebar_position: 3

Data sources allow developers easily integrate different data providers into the
carbon aware SDK ([WattTime](https://www.wattime.org),
[ElectricityMaps](https://www.electricitymaps.com/),
[ElectricityMapsFree](https://www.co2signal.com/) etc) to be made available to
[ElectricityMaps](https://www.electricitymaps.com/), etc) to be made available to
all higher-level user-interfaces (WebAPI, CLI, etc), while avoiding the details
of how to interact with any specific provider.

Expand Down
34 changes: 10 additions & 24 deletions casdk-docs/docs/overview/enablement.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ sidebar_position: 3
* SDK
* Use cases

2. [How to Use Carbon Aware SDK](#2-how-to-use-carbon-aware-sdk)
2. [How to Use Carbon Aware SDK](#2-how-to-use-carbon-aware-sdk)

2.1 [Pre-requisites](#21-pre-requisites)
* Data sources
Expand All @@ -23,13 +23,13 @@ sidebar_position: 3
* Setup
* Usage

2.3 [WebAPI](#23-webapi)
2.3 [WebAPI](#23-webapi)
* Setup
* Deploying with container
* Deploying with Kubernetes
* Usage
* Calling WebAPI using CLI
* Calling WebAPI using client libraries
* Calling WebAPI using client libraries

2.4 [Configurations](#24-configurations)

Expand All @@ -43,16 +43,16 @@ you different data than the WebAPI for the same query). We provide a number of
different endpoints to provide the most flexibility to integrate to your
environment:

* CLI
* CLI
You can run the application using the [CLI](/src/CarbonAware.CLI) and refer
to more documentation [here](../tutorial-basics/carbon-aware-cli.md).
to more documentation [here](../tutorial-basics/carbon-aware-cli.md).

* WebAPI
* WebAPI
You can build a container containing the [WebAPI](/src/CarbonAware.WebApi)
and connect via REST requests and refer to more documentation
[here](../tutorial-basics/carbon-aware-webapi.md).

* SDK
* SDK
You can reference the [Carbon Aware C# Library](/src/GSF.CarbonAware) in your
projects and make use of its functionalities and features.

Expand All @@ -75,7 +75,6 @@ We support various data sources of carbon aware data:

* [WattTime](https://www.watttime.org/)
* [ElectricityMaps](https://www.electricitymaps.com/)
* [ElectricityMapsFree](https://www.co2signal.com/)
* JSON file

There are a few constraints to select data sources to some functions of
Expand All @@ -91,7 +90,7 @@ providers into the carbon aware SDK.
* Alternatively:
* Docker
* VSCode and its [Remote Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
* WebAPI
* WebAPI
* Docker
* VSCode and its [Remote Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)

Expand Down Expand Up @@ -127,20 +126,13 @@ VSCode Remote Containers (Dev Container). To run locally:
or

```bash
export DataSources__EmissionsDataSource="ElectricityMaps"
export DataSources__ForecastDataSource="ElectricityMaps"
export DataSources__Configurations__ElectricityMaps__Type="ElectricityMaps"
export DataSources__Configurations__ElectricityMaps__APITokenHeader="auth-token"
export DataSources__Configurations__ElectricityMaps__APIToken="<YOUR_ELECTRICITYMAPS_TOKEN>"
```

or

```bash
export DataSources__EmissionsDataSource="ElectricityMapsFree"
export DataSources__Configurations__ElectricityMapsFree__Type="ElectricityMapsFree"
export DataSources__Configurations__ElectricityMapsFree__token="<CO2SIGNAL_TOKEN>"
```

4. Run the CLI using `dotnet run`

The CLI will ask you to at minimum provide a `--location (-l)` parameter.
Expand Down Expand Up @@ -269,19 +261,13 @@ First we need to set up the GitHub repository
or

```bash
export DataSources__EmissionsDataSource="ElectricityMaps"
export DataSources__ForecastDataSource="ElectricityMaps"
export DataSources__Configurations__ElectricityMaps__Type="ElectricityMaps"
export DataSources__Configurations__ElectricityMaps__APITokenHeader="auth-token"
export DataSources__Configurations__ElectricityMaps__APIToken="<YOUR_ELECTRICITYMAPS_TOKEN>"
```

or

```bash
export DataSources__EmissionsDataSource="ElectricityMapsFree"
export DataSources__Configurations__ElectricityMapsFree__Type="ElectricityMapsFree"
export DataSources__Configurations__ElectricityMapsFree__token="<CO2SIGNAL_TOKEN>"
```

6. In the VSCode Terminal:
7. Change directory to: `cd src/CarbonAware.WebApi/src`
Expand Down
16 changes: 2 additions & 14 deletions casdk-docs/docs/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,19 +55,13 @@ VSCode Remote Containers (Dev Container). To run locally:
or

```bash
export DataSources__EmissionsDataSource="ElectricityMaps"
export DataSources__ForecastDataSource="ElectricityMaps"
export DataSources__Configurations__ElectricityMaps__Type="ElectricityMaps"
export DataSources__Configurations__ElectricityMaps__APITokenHeader="auth-token"
export DataSources__Configurations__ElectricityMaps__APIToken="<YOUR_ELECTRICITYMAPS_TOKEN>"
```

or

```bash
export DataSources__EmissionsDataSource="ElectricityMapsFree"
export DataSources__Configurations__ElectricityMapsFree__Type="ElectricityMapsFree"
export DataSources__Configurations__ElectricityMapsFree__token="<CO2SIGNAL_TOKEN>"
```

1. Run the CLI using `dotnet run`

Expand Down Expand Up @@ -213,19 +207,13 @@ First we need to set up the GitHub repository
or

```bash
export DataSources__EmissionsDataSource="ElectricityMaps"
export DataSources__ForecastDataSource="ElectricityMaps"
export DataSources__Configurations__ElectricityMaps__Type="ElectricityMaps"
export DataSources__Configurations__ElectricityMaps__APITokenHeader="auth-token"
export DataSources__Configurations__ElectricityMaps__APIToken="<YOUR_ELECTRICITYMAPS_TOKEN>"
```

or

```bash
export DataSources__EmissionsDataSource="ElectricityMapsFree"
export DataSources__Configurations__ElectricityMapsFree__Type="ElectricityMapsFree"
export DataSources__Configurations__ElectricityMapsFree__token="<CO2SIGNAL_TOKEN>"
```

6. In the VSCode Terminal:
7. Change directory to: `cd src/CarbonAware.WebApi/src`
Expand Down
28 changes: 2 additions & 26 deletions casdk-docs/docs/tutorial-basics/carbon-aware-webapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,6 @@ client generation
- [ElectricityMaps](#electricitymaps)
- [Locations](#electricitymaps-locations)
- [Exception Handling](#electricitymaps-exception-handling)
- [ElectricityMapsFree](#electricitymapsfree)
- [Locations](#locations)
- [Exception Handling](#exception-handling)

## Endpoints

Expand Down Expand Up @@ -491,9 +488,9 @@ specification
dotnet build --configuration Release --no-restore
dotnet tool run swagger tofile --output ./wwwroot/api/v1/swagger.yaml --yaml bin/Release/net8.0/CarbonAware.WebApi.dll v1
```
1. The `CarbonAware.WebApi/src/wwwroot/api/v1/swagger.yaml` file contains the supported
1. The `CarbonAware.WebApi/src/wwwroot/api/v1/swagger.yaml` file contains the supported
OpenApi specification.
1. Use for instance [swagger editor](https://editor.swagger.io) to see and try
1. Use for instance [swagger editor](https://editor.swagger.io) to see and try
the endpoint routes.

## Data Sources
Expand Down Expand Up @@ -550,24 +547,3 @@ Data Source will forward the response code and message back to the caller. Refer
to the
[ElectricityMapsHttpClientException](../src/CarbonAware.DataSources/CarbonAware.DataSources.ElectricityMaps/src/Client/ElectricityMapsClientHttpException.cs)
class for documentation on expected error codes.

### ElectricityMapsFree

#### Locations

Each ElectricityMapsFree emissions data point is associated with a particular
named country code. While the ElectricityMapsFree endpoint supports calling with
lat/long geoposition as well, the result will always be a corresponding country
code.
They provide a
[route on their parent API (ElectricityMaps)](https://static.electricitymaps.com/api/docs/index.html#zones)
which can be queried to list all the country codes you have access to given your
token.

#### Exception Handling

If ElectricityMapsFree responds with a 4XX or 5XX status code the
ElectricityMapsFree Data Source will forward the response code and message back
to the caller. Refer to the
[ElectricityMapsFreeHttpClientException](../src/CarbonAware.DataSources/CarbonAware.DataSources.ElectricityMapsFree/src/Client/ElectricityMapsFreeClientHttpException.cs)
class for documentation on expected error codes.
10 changes: 0 additions & 10 deletions casdk-docs/docs/tutorial-basics/containerization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,16 +49,6 @@ carbon_aware v1 6293e2528bf2 About an hour ago 230MB
> carbon_aware:v1
```

or the [ElectricityMapsFree](https://www.co2signal.com/) provider

```sh
docker run --rm -p 8000:8080 \
> -e DataSources__EmissionsDataSource="ElectricityMapsFree" \
> -e DataSources__Configurations__ElectricityMapsFree__Type="ElectricityMapsFree" \
> -e DataSources__Configurations__ElectricityMapsFree__token="<YOUR_CO2SIGNAL_TOKEN>" \
> carbon_aware:v1
```

1. Verify that the WebApi is responding to requests using an HTTP client tool
(e.g. `postman`, `curl`)

Expand Down
24 changes: 0 additions & 24 deletions casdk-docs/docs/tutorial-extras/carbon-aware-library.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,6 @@ same configuration
- [ElectricityMaps](#electricitymaps)
- [Locations](#locations)
- [Exception Handling](#exception-handling)
- [ElectricityMapsFree](#electricitymapsfree)
- [Locations](#locations)
- [Exception Handling](#exception-handling)

## EmissionsHandler Functions

Expand Down Expand Up @@ -469,24 +466,3 @@ Data Source will forward the response code and message back to the caller. Refer
to the
[ElectricityMapsHttpClientException](../src/CarbonAware.DataSources/CarbonAware.DataSources.ElectricityMaps/src/Client/ElectricityMapsClientHttpException.cs)
class for documentation on expected error codes.

### ElectricityMapsFree

#### Locations

Each ElectricityMapsFree emissions data point is associated with a particular
named country code. While the ElectricityMapsFree endpoint supports calling with
lat/long geoposition as well, the result will always be a corresponding country
code.
They provide a
[route on their parent API (ElectricityMaps)](https://static.electricitymaps.com/api/docs/index.html#zones)
which can be queried to list all the country codes you have access to given your
token.

#### Exception Handling

If ElectricityMapsFree responds with a 4XX or 5XX status code the
ElectricityMapsFree Data Source will forward the response code and message back
to the caller. Refer to the
[ElectricityMapsFreeHttpClientException](../src/CarbonAware.DataSources/CarbonAware.DataSources.ElectricityMapsFree/src/Client/ElectricityMapsFreeClientHttpException.cs)
class for documentation on expected error codes.
66 changes: 1 addition & 65 deletions casdk-docs/docs/tutorial-extras/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,6 @@
- [BaseUrl](#baseurl)
- [Emission Factor Type](#emission-factor-type)
- [Disable Estimations](#disable-estimations)
- [ElectricityMapsFree Configuration](#electricitymapsfree-configuration)
- [API Token](#api-token)
- [BaseUrl](#baseurl)
- [Cache](#cache)
- [CarbonAwareVars](#carbonawarevars)
- [Tracing and Monitoring Configuration](#tracing-and-monitoring-configuration)
Expand All @@ -30,7 +27,6 @@
- [Configuration for Emissions data Using WattTime](#configuration-for-emissions-data-using-watttime)
- [Configuration for Forecast data Using ElectricityMaps](#configuration-for-forecast-data-using-electricitymaps)
- [Configuration for Emissions data using ElectricityMaps and Forecast data using WattTime](#configuration-for-emissions-data-using-electricitymaps-and-forecast-data-using-watttime)
- [Configuration for Emissions data using ElectricityMapsFree and Forecast data using WattTime](#configuration-for-emissions-data-using-electricitymapsfree-and-forecast-data-using-watttime)
- [Configuration For Emissions data Using JSON](#configuration-for-emissions-data-using-json)
- [Configuration Using WattTime and Defined Location Source Files](#configuration-using-watttime-and-defined-location-source-files)

Expand Down Expand Up @@ -296,44 +292,6 @@ See the
[ElectricityMaps API Documentation](https://static.electricitymaps.com/api/docs/index.html#estimations)
for more details.

### ElectricityMapsFree Configuration

If using the ElectricityMapsFree data source, ElectricityMapsFree configuration
is required.

**With an account token:**

> **NOTE** The ElectricityMapsFree API does not currently support access to
> historical forecasts. This means that functionality such as the CLI
> `emissions-forecasts` > `--requested-at` flag and the API `/forecasts/batch` >
> `requestedAt` input will respond with a `NotImplemented` error.
>
> The ElectricityMapsFree API also does not currently support access to
> historical emissions data. It only supports getting the single latest
> emissions data point for the given location.
>
> If either of these restrictions are an issue, a data source that has support
> for historical forecasts, such as [WattTime](#watttime-configuration) or
> historical emissions, such as
> [ElectricityMaps](#electricitymaps-configuration) may be preferable.

```json
{
"token": "<api-token>",
"baseUrl": "https://api.co2signal.com/v1/"
}
```

#### API Token

The ElectricityMapsFree token you receive with your account.

#### BaseUrl

The url to use when connecting to ElectricityMapsFree. Defaults to
"https://api.co2signal.com/v1/" but can be overridden in the config if needed
(such as to enable integration testing scenarios).

## Cache

Frequent access to data sources could cause problems such as performance trouble
Expand Down Expand Up @@ -434,7 +392,7 @@ The scraping endpoint is `<ROOT_PATH>/metrics` like this:
http://localhost/metrics
```

By default, the exposed data are latest ones within last 24 hours. If you would like to change the period
By default, the exposed data are latest ones within last 24 hours. If you would like to change the period
in some reasones, you can configure the value like this:

```json
Expand Down Expand Up @@ -613,28 +571,6 @@ DataSources__Configurations__WattTime__Password="wattTimePassword"
}
```

## Configuration for Emissions data using ElectricityMapsFree and Forecast data using WattTime

```json
"DataSources": {
"EmissionsDataSource": "ElectricityMapsFree",
"ForecastDataSource": "WattTime",
"Configurations": {
"WattTime": {
"Type": "WattTime",
"Username": "username",
"Password": "password",
"BaseURL": "https://api2.watttime.org/v2/",
},
"ElectricityMapsFree": {
"Type": "ElectricityMapsFree",
"token": "token",
"BaseURL": "https://api.co2signal.com/v1/"
}
}
}
```

### Configuration For Emissions data Using JSON

```json
Expand Down
10 changes: 0 additions & 10 deletions casdk-docs/docs/tutorial-extras/containerization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,16 +49,6 @@ carbon_aware v1 6293e2528bf2 About an hour ago 230MB
> carbon_aware:v1
```

or the [ElectricityMapsFree](https://www.co2signal.com/) provider

```sh
docker run --rm -p 8000:80 \
> -e DataSources__EmissionsDataSource="ElectricityMapsFree" \
> -e DataSources__Configurations__ElectricityMapsFree__Type="ElectricityMapsFree" \
> -e DataSources__Configurations__ElectricityMapsFree__token="<YOUR_CO2SIGNAL_TOKEN>" \
> carbon_aware:v1
```

1. Verify that the WebApi is responding to requests using an HTTP client tool
(e.g. `postman`, `curl`)

Expand Down
Loading
Loading