Selecting a Data Source

The Carbon Aware SDK includes access to various data sources of carbon aware data, including WattTime, ElectricityMaps, ElectricityMapsFree, and a custom JSON source. These matrices are an attempt to track what features of the Carbon Aware SDK are enabled for which data sources.

Contents

• Type of Data Sources and Configuration
• Data Source Methods Available
• Location Coverage
• Restriction: ElectricityMaps Free Trial User

Type of Data Sources and Configuration

In the CarbonAware SDK configuration, you can set what data source to use as the EmissionsDataSource and the ForecastDataSource. There are also certain configuration fields that must be set in order to access the raw data.

Type	WattTime	ElectricityMaps	ElectricityMapsFree	JSON
Is Emissions DataSource	✅	✅	✅	✅
Is Forecast DataSource	✅	✅	❌	❌
Makes HTTP(s) call	✅	✅	✅	❌
Can Use Custom Data	❌	❌	❌	✅
Supports Trial + Full Account	✅	✅ (*see restriction below)	N/A	N/A

Data Source Methods Available

Not all data sources support all the routes provided in the interfaces (IEmissionsDataSource/IForecastDataSource).

Methods	WattTime	ElectricityMaps	ElectricityMapsFree	JSON	CLI Usage	Web Api Usage	SDK Usage
GetCarbonIntensityAsync	✅	✅	✅	✅	emissions	emissions/bylocation or emissions/bylocations or emissions/bylocations/best or emissions/average‑carbon‑intensity or emissions/average‑carbon‑intensity/batch	GetEmissionsDataAsync(...) or GetBestEmissionsDataAsync(...) or GetAverageCarbonIntensityDataAsync(...)
GetCurrentForecastAsync	✅	✅	❌	❌	emissions‑forecasts	forecasts/current	GetCurrentForecastAsync(...)
GetForecastByDateAsync	✅	❌	❌	❌	emissions‑forecasts ‑‑requested‑at	forecasts/batch with requestedAt field	GetForecastByDateAsync(...)

Location Coverage

Different data sources provide both different features (as outlined above) but also coverage of different geographic areas. It's important to note that each data source may have different region names, which are handled through the location config.

• For WattTime, see their interactive coverage map to find the relevant zone.
• For ElectricityMaps, see their live map app to find the relevant zone and see current data coming in.
• For ElectricityMapsFree, see the Electricity Maps zone list to find the relevant zones.

Restrictions: free trial of ElectricityMaps

ElectricityMaps allows new users to create a free trial for 1 month access to the API. Free trial users have restricted access to the API and a slightly different configuration for the SDK (see configuration.md. You can request a free trial on the ElectricityMaps API Portal.

Restricted Zone Access

Free trial users only have access ~100 zones in the ElectricityMaps API. ElectricityMaps maintains a frequently updated list of available free trial zones that include the key, name, and country of each zone. If you need access to other zones not included on the list, you will need a full access product key.

Restricted Endpoint Access

Free trial users only have access to seven endpoints in the ElectricityMaps API. Of those seven, only two are currently supported as part of Carbon Aware SDK:

1. GET /carbon-intensity/forecast
2. GET /carbon-intensity/history

Note: The Carbon Aware SDK is not restricting implementations to only support free trial users of ElectricityMaps. There may be implementations in the future that use endpoints that a free trial user may not be able to access and therefore cannot use that functionality of the SDK.

Restricted Call Access

Free trial users are capped at 1,000 calls for the month of the free trial. Any calls beyond the 1,000th call will be rejected.