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:
GET /carbon-intensity/forecastGET /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.