Sign in

v1

latestOpenAPI 3.0.12026-07-178827.6 KB
CarbonAware

Retrieves the most recent forecasted data and calculates the optimal marginal carbon intensity window.

This endpoint fetches only the most recently generated forecast for all provided locations. It uses the "dataStartAt" and "dataEndAt" parameters to scope the forecasted data points (if available for those times). If no start or end time boundaries are provided, the entire forecast dataset is used. The scoped data points are used to calculate average marginal carbon intensities of the specified "windowSize" and the optimal marginal carbon intensity window is identified.

The forecast data represents what the data source predicts future marginal carbon intesity values to be, not actual measured emissions data (as future values cannot be known).

This endpoint is useful for determining if there is a more carbon-optimal time to use electicity predicted in the future.

get/emissions/forecasts/current

Query parameters

locationstring[] required

String array of named locations

dataStartAtstring date-time
Example:2022-03-01T15:30:00Z

Start time boundary of forecasted data points.Ignores current forecast data points before this time. Defaults to the earliest time in the forecast data.

dataEndAtstring date-time
Example:2022-03-01T18:30:00Z

End time boundary of forecasted data points. Ignores current forecast data points after this time. Defaults to the latest time in the forecast data.

windowSizeinteger
Example:30

The estimated duration (in minutes) of the workload. Defaults to the duration of a single forecast data point.

Response

Returns the requested forecast objects

generatedAtstring date-time

Timestamp when the forecast was generated.

requestedAtstring date-time

For current requests, this value is the timestamp the request for forecast data was made. For historical forecast requests, this value is the timestamp used to access the most recently generated forecast as of that time.

locationstring nullable

The location of the forecast

dataStartAtstring date-time

Start time boundary of forecasted data points. Ignores forecast data points before this time. Defaults to the earliest time in the forecast data.

dataEndAtstring date-time

End time boundary of forecasted data points. Ignores forecast data points after this time. Defaults to the latest time in the forecast data.

windowSizeinteger

The estimated duration (in minutes) of the workload. Defaults to the duration of a single forecast data point.

Example response

[
  {
    "dataEndAt": "2022-06-01T18:00:00Z",
    "windowSize": 30,
    "forecastData": [
      {
        "location": "eastus",
        "timestamp": "2022-06-01T14:40:00Z",
        "duration": 30,
        "value": 380.99
      },
      {
        "location": "eastus",
        "timestamp": "2022-06-01T14:45:00Z",
        "duration": 30,
        "value": 359.23
      },
      {
        "location": "eastus",
        "timestamp": "2022-06-01T14:50:00Z",
        "duration": 30,
        "value": 375.12
      }
    ],
    "requestedAt": "2022-06-01T00:03:30Z",
    "generatedAt": "2022-06-01T00:00:00Z",
    "optimalDataPoints": {
      "location": "eastus",
      "timestamp": "2022-06-01T14:45:00Z",
      "duration": 30,
      "value": 359.23
    },
    "location": "eastus",
    "dataStartAt": "2022-06-01T12:00:00Z"
  }
]