Release 1.8.0

.github/workflows/1-pr.yaml

@@ -122,9 +122,11 @@ jobs:
           directory: ${{ env.DOTNET_SRC_DIR }}
 
       - name: Generate Open API
-        run: dotnet tool run swagger tofile --output ./wwwroot/api/v1/swagger.yaml --yaml ${{ env.DLL_FILE_PATH }} v1
         env:
+          DataSources__EmissionsDataSource: Json
+          DataSources__Configurations__Json__Type: JSON
           DOTNET_ROLL_FORWARD: LatestMajor
+        run: dotnet tool run swagger tofile --output ./wwwroot/api/v1/swagger.yaml --yaml ${{ env.DLL_FILE_PATH }} v1
         working-directory: ./src/CarbonAware.WebApi/src 
 
       - name: Upload swagger artifact
@@ -146,7 +148,7 @@ jobs:
 
       - name: Docker Run Container
         run: |
-          docker run -d --name runnable-container -p 8080:8080 ca-api
+          docker run -d --name runnable-container -e DataSources__EmissionsDataSource=Json -e DataSources__Configurations__Json__Type=JSON -p 8080:8080 ca-api
           docker container ls
 
       - name: Docker WGET Health Endpoint
@@ -182,6 +184,8 @@ jobs:
       - name: Generate Open API
         run: dotnet tool run swagger tofile --output ./wwwroot/api/v1/swagger.yaml --yaml ${{ env.DLL_FILE_PATH }} v1
         env:
+          DataSources__EmissionsDataSource: Json
+          DataSources__Configurations__Json__Type: JSON
           DOTNET_ROLL_FORWARD: LatestMajor
       - name: Upload dev artifact
         uses: actions/upload-artifact@v4

CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to the Carbon Aware SDK will be documented in this file.
 
+
+## [1.8] - 2025-04
+
+This release consolidates the ElectricityMaps sources, introduces new CO₂-intensity signal support in WattTime, and rounds out the release with documentation improvements and critical bug fixes [https://github.com/Green-Software-Foundation/carbon-aware-sdk/labels/v1.8](https://github.com/Green-Software-Foundation/carbon-aware-sdk/labels/v1.8).
+
+### Added
+
+
+- [PR #619] feat(ElectricityMaps source): unify ElectricityMaps and ElectricityMapsFree ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/pull/619)
+- [PR #614] Make documentation for forecasts signal agnostic ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/pull/614)
+- [PR #611] Support co2_aoer in WattTime ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/pull/611)
+- [PR #450] Remove JSON examples from artifacts ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/pull/450)
+
+And supporting issues:
+
+- [#612] Documentation: Update wording about marginal signal ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/issues/612)
+- [#440] [Feature Contribution]: Remove JSON examples from WebAPI container ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/issues/440)
+- [#396] [Feature Contribution]: Better to throw exception when future datetime is specified to endpoints for current/historical data ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/issues/396)
+
+### Fixed 
+
+- [#613] [Bug]: Electricity Maps API configuration is out of date ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/issues/613)
+- [PR #623] [URGENT] Set JsonStringConverter to JSON deserializer option in WattTimeClient ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/pull/623)
+
+For more details, checkout [https://github.com/Green-Software-Foundation/carbon-aware-sdk/issues/628](https://github.com/Green-Software-Foundation/carbon-aware-sdk/issues/628)
+
 ## [1.7] - 2025-01
 
 This release mainly introduces new clients libraries for NPM and Java [https://github.com/Green-Software-Foundation/carbon-aware-sdk/labels/v1.7](https://github.com/Green-Software-Foundation/carbon-aware-sdk/labels/v1.7) 

casdk-docs/docs/architecture/c-sharp-client-library.md

@@ -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`

casdk-docs/docs/architecture/data-sources.md

@@ -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.
 

casdk-docs/docs/architecture/decisions/0017-watt-time-signal-type.md

@@ -0,0 +1,50 @@
+# 0017. Signal Type in WattTime v3 Data Source
+
+## Status
+
+Proposed
+
+## Context
+
+WattTime v3 API has been supported since [Carbon Aware SDK v1.5.0](https://carbon-aware-sdk.greensoftware.foundation/blog/release-v1.5). As we mentioned in [ADR-0015](https://carbon-aware-sdk.greensoftware.foundation/docs/architecture/decisions/watt-time-v3), `signal_type` has been added in each endpoints which the SDK will access since v3 API. We should be able to set following parameters to it, but it can't in Carbo Aware SDK.
+
+https://watttime.org/data-science/data-signals/
+
+| Signal Type | Description |
+|---|---|
+| `co2_moer` |  Marginal Operating Emissions Rate of carbon dioxide. |
+| `co2_aoer` |  Average Operating Emissions Rate of carbon dioxide. |
+
+According to [Green Software Practitioners](https://learn.greensoftware.foundation/carbon-awareness#marginal-carbon-intensity), "marginal" means the carbon intensity of the power plant that would have to be employed to meet any new demand. On the other hand, "average" means the average of all of power plants. It should be chosen by Carbon Aware SDK user because which value is needed depends on the user.
+
+`co2_moer` is hard-coded until Carbon Aware SDK v1.7.0 (at least).
+
+## Decision
+
+The proposal is for adding a new parameter for Signal Type in WattTime Data Source.
+
+## Update Changes
+
+We will introduce new parameter for data source configuration of WattTime as following.
+
+### appsettings.json
+
+```json
+"WattTime": {
+  "Type": "WattTime",
+  "Username": "username",
+  "Password": "password",
+  "BaseURL": "https://api.watttime.org/v3/",
+  "SignalType": "co2_aoer"
+}
+```
+
+### environment variable
+
+```bash
+DataSources__Configurations__WattTime__SignalType=co2_aoer
+```
+
+## Green Impact
+
+Neutral

casdk-docs/docs/overview/enablement.md

@@ -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
@@ -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)
 
@@ -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.
 
@@ -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
@@ -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)
 
@@ -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.
@@ -155,6 +147,8 @@ parameters and short explanations.
 To get a list of all locations supported, you can use the Locations API,
 referenced in `src/CarbonAware.CLI/src/Commands/Location`
 and the command `.\caw locations`.
+Note that you have to configure `LocationDataSourcesConfiguration`
+into `appsettings.json` before running the command.
 
 Expected output:
 
@@ -269,19 +263,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`
@@ -452,6 +440,9 @@ endpoints, full endpoint description can be found [here](https://github.com/Gree
 To get a list of all locations supported, you can use the Locations API endpoint
 `/locations` referenced in
 `src/CarbonAware.WebApi/src/Controllers/LocationsController.cs`.
+Note that you have to configure `LocationDataSourcesConfiguration`
+into `appsettings.json` before launching WebAPI, otherwise WebAPI returns
+HTTP 204 (No Content).
 
 Expected Output:
 
@@ -474,12 +465,16 @@ Expected Output:
 ##### Calling the `/emissions/bylocation` endpoint
 
 In console, we can run the below command, to request data for a single location
-(currently Azure region names supported) in a particular timeframe:
+in a particular timeframe:
 
 ```bash
 curl "http://localhost:5073/emissions/bylocation?location=westus&time=2022-08-23T14%3A00&toTime=2022-08-23T14%3A30" | jq
 ```
 
+Note that region names in this example (e.g. `westus`) are defined in
+[azure-regions.json](https://github.com/Green-Software-Foundation/carbon-aware-sdk/blob/dev/src/data/location-sources/azure-regions.json).
+AWS region is also available in [aws-regions.json](https://github.com/Green-Software-Foundation/carbon-aware-sdk/blob/dev/src/data/data-files/aws-regions.json).
+
 You can omit the `| jq` to get the JSON data raw and unparsed. This is a request
 for data in the `westus` region from the date `2022-08-23 at 14:00` to
 `2022-08-23 at 14:30`. (Note: semicolons `:` are encoded as `%3A` in URLs).

casdk-docs/docs/quickstart.md

@@ -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`
 
@@ -81,7 +75,8 @@ parameters and short explanations.
 
 To get a list of all locations supported, you can use the Locations API,
 referenced in `src/CarbonAware.CLI/src/Commands/Location`
-and the command `.\caw locations`.
+and the command `.\caw locations`. Note that you have to configure `LocationDataSourcesConfiguration`
+into `appsettings.json` before running the command.
 
 Expected output:
 
@@ -213,19 +208,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`
@@ -246,6 +235,9 @@ endpoints, full endpoint description can be found here:
 To get a list of all locations supported, you can use the Locations API endpoint
 `/locations` referenced in
 `src/CarbonAware.WebApi/src/Controllers/LocationsController.cs`.
+Note that you have to configure `LocationDataSourcesConfiguration`
+into `appsettings.json` before launching WebAPI, otherwise WebAPI returns
+HTTP 204 (No Content).
 
 Expected Output:
 
@@ -269,12 +261,16 @@ Expected Output:
 #### Calling the `/emissions/bylocation` endpoint
 
 In console, we can run the below command, to request data for a single location
-(currently Azure region names supported) in a particular timeframe:
+in a particular timeframe:
 
 ```bash
 curl "http://localhost:5073/emissions/bylocation?location=westus&time=2022-08-23T14%3A00&toTime=2022-08-23T14%3A30" | jq
 ```
 
+Note that region names in this example (e.g. `westus`) are defined in
+[azure-regions.json](https://github.com/Green-Software-Foundation/carbon-aware-sdk/blob/dev/src/data/location-sources/azure-regions.json).
+AWS region is also available in [aws-regions.json](https://github.com/Green-Software-Foundation/carbon-aware-sdk/blob/dev/src/data/data-files/aws-regions.json).
+
 You can omit the `| jq` to get the JSON data raw and unparsed. This is a request
 for data in the `westus` region from the date `2022-08-23 at 14:00` to
 `2022-08-23 at 14:30`. (Note: semicolons `:` are encoded as `%3A` in URLs).