Custom Connector
Carbon Intensity
UK
The Carbon Intensity Connector integrates with the Carbon Intensity API for Great Britain, developed by the National Energy System Operator (NESO). It provides national and regional carbon-intensity data, generation mix, factors, and statistics — acting as a proxy for intensity, factors, statistics, generation mix, and regional data, in JSON, optimized for GCP.
Overview
Integration Overview
This document provides a detailed guide for each integration point using the Carbon Intensity Connector for GCP. Endpoints cover national intensity (current, today, by date/period, forward/past ranges), statistics, generation mix, and regional intensity (by region, England/Scotland/Wales, postcode, and region ID).
- getCurrentIntensity. Carbon intensity for the current half hour.
- getTodayIntensity. Carbon intensity for today.
- getDateIntensity. Carbon intensity for a specific date.
- getDatePeriodIntensity. Carbon intensity for a specific date and half-hour period.
- getSpecificPeriodIntensity. Carbon intensity for a specific half-hour period.
- get24hForwardIntensity / get48hForwardIntensity. Intensity 24 or 48 hours forward from a datetime.
- get24hPastIntensity. Intensity 24 hours past from a datetime.
- getRangeIntensity. Intensity between two datetimes (up to 14 days).
- getRangeStats / getBlockStats. Intensity statistics and block averages between two datetimes.
- getIntensityFactors. Carbon intensity factors for each fuel type.
- getCurrentGeneration / get24hPastGeneration / getRangeGeneration. Generation mix for current, past 24h, or a datetime range.
- getCurrentRegional / England / Scotland / Wales / Postcode. Current regional intensity for GB regions, nations, or a postcode.
- Forward / past / range regional. 48h-forward, 24h-past, and range intensity by region, postcode, or region ID.
Documentation
Detailed Integration Documentation
Current Intensity
| Action | getCurrentIntensity |
|---|---|
| Purpose | Retrieves carbon intensity for the current half-hour period in Great Britain — real-time energy monitoring. |
| Configuration | Configure the base URL via CONNECTOR_ENV_CARBONINTENSITY_BASE_URL (default https://api.carbonintensity.org.uk). |
| Parameters | Optional: format (json, default json). |
| Output | Successful: JSON with a data array of { from, to, intensity: { forecast, actual, index } }. Failure: error details (e.g. 400 Bad Request). |
Today Intensity
| Action | getTodayIntensity |
|---|---|
| Purpose | Retrieves carbon intensity for today — daily energy planning. |
| Configuration | Configure the base URL via CONNECTOR_ENV_CARBONINTENSITY_BASE_URL (default https://api.carbonintensity.org.uk). |
| Parameters | Optional: format (json, default json). |
| Output | Successful: JSON with a data array of { from, to, intensity: { forecast, actual, index } }. Failure: error details (e.g. 400 Bad Request). |
Specific Date Intensity
| Action | getDateIntensity |
|---|---|
| Purpose | Retrieves carbon intensity for a specific date — historical analysis. |
| Configuration | Configure the base URL via CONNECTOR_ENV_CARBONINTENSITY_BASE_URL (default https://api.carbonintensity.org.uk). |
| Parameters | Required: date (YYYY-MM-DD, e.g. 2025-08-18). Optional: format (json). |
| Output | Successful: JSON with a data array of { from, to, intensity: { forecast, actual, index } }. Failure: error details (e.g. 400 Bad Request). |
Date & Period Intensity
| Action | getDatePeriodIntensity |
|---|---|
| Purpose | Retrieves carbon intensity for a specific date and half-hour settlement period — granular historical analysis. |
| Configuration | Configure the base URL via CONNECTOR_ENV_CARBONINTENSITY_BASE_URL (default https://api.carbonintensity.org.uk). |
| Parameters | Required: date (YYYY-MM-DD); period (1–48, e.g. 42). Optional: format (json). |
| Output | Successful: JSON with a data array of { from, to, intensity: { forecast, actual, index } }. Failure: error details (e.g. 400 Bad Request). |
Specific Period Intensity
| Action | getSpecificPeriodIntensity |
|---|---|
| Purpose | Retrieves carbon intensity for a specific half-hour period. |
| Configuration | Configure the base URL via CONNECTOR_ENV_CARBONINTENSITY_BASE_URL (default https://api.carbonintensity.org.uk). |
| Parameters | Required: from (ISO8601, e.g. 2025-08-18T12:00Z). Optional: format (json). |
| Output | Successful: JSON with a data array of { from, to, intensity: { forecast, actual, index } }. Failure: error details (e.g. 400 Bad Request). |
24h / 48h Forward Intensity
| Action | get24hForwardIntensity / get48hForwardIntensity |
|---|---|
| Purpose | Retrieves carbon intensity 24 or 48 hours forward from a datetime — short/medium-term forecasting. |
| Configuration | Configure the base URL via CONNECTOR_ENV_CARBONINTENSITY_BASE_URL (default https://api.carbonintensity.org.uk). |
| Parameters | Required: from (ISO8601). Optional: format (json). |
| Output | Successful: JSON with a data array of { from, to, intensity: { forecast, actual, index } }. Failure: error details (e.g. 400 Bad Request). |
24h Past Intensity
| Action | get24hPastIntensity |
|---|---|
| Purpose | Retrieves carbon intensity 24 hours past from a datetime — historical analysis. |
| Configuration | Configure the base URL via CONNECTOR_ENV_CARBONINTENSITY_BASE_URL (default https://api.carbonintensity.org.uk). |
| Parameters | Required: from (ISO8601). Optional: format (json). |
| Output | Successful: JSON with a data array of { from, to, intensity: { forecast, actual, index } }. Failure: error details (e.g. 400 Bad Request). |
Range Intensity
| Action | getRangeIntensity |
|---|---|
| Purpose | Retrieves carbon intensity between two datetimes (up to 14 days) — custom range analysis. |
| Configuration | Configure the base URL via CONNECTOR_ENV_CARBONINTENSITY_BASE_URL (default https://api.carbonintensity.org.uk). |
| Parameters | Required: from, to (ISO8601). Optional: format (json). Failure: 400 if the range exceeds 14 days. |
| Output | Successful: JSON with a data array of { from, to, intensity: { forecast, actual, index } }. Failure: error details (e.g. 400 Bad Request). |
Range & Block Statistics
| Action | getRangeStats / getBlockStats |
|---|---|
| Purpose | Retrieves carbon-intensity statistics (max, average, min) between two datetimes (up to 30 days), and block-average statistics over a block size — trend analysis. |
| Configuration | Configure the base URL via CONNECTOR_ENV_CARBONINTENSITY_BASE_URL (default https://api.carbonintensity.org.uk). |
| Parameters | Required: from, to (ISO8601). getBlockStats also takes block (hours). Optional: format (json). |
| Output | Successful: JSON with statistics objects (max, average, min, and index). Failure: error details. |
Intensity Factors
| Action | getIntensityFactors |
|---|---|
| Purpose | Retrieves carbon-intensity factors (gCO2/kWh) for each fuel type. |
| Configuration | Configure the base URL via CONNECTOR_ENV_CARBONINTENSITY_BASE_URL (default https://api.carbonintensity.org.uk). |
| Parameters | Optional: format (json). |
| Output | Successful: JSON with a data array of fuel-type factors (e.g. gas, coal, nuclear, wind, solar). Failure: error details. |
Generation Mix
| Action | getCurrentGeneration / get24hPastGeneration / getRangeGeneration |
|---|---|
| Purpose | Retrieves the generation mix (percentage per fuel type) for the current half hour, the past 24 hours, or a datetime range. |
| Configuration | Configure the base URL via CONNECTOR_ENV_CARBONINTENSITY_BASE_URL (default https://api.carbonintensity.org.uk). |
| Parameters | Range variant required: from, to (ISO8601). Others: none. Optional: format (json). |
| Output | Successful: JSON with a generationmix array (fuel, perc). Failure: error details. |
Current Regional Intensity
| Action | getCurrentRegional / getCurrentEngland / getCurrentScotland / getCurrentWales / getCurrentPostcode |
|---|---|
| Purpose | Retrieves current half-hour carbon intensity for all GB regions, for England/Scotland/Wales, or for a specific postcode. |
| Configuration | Configure the base URL via CONNECTOR_ENV_CARBONINTENSITY_BASE_URL (default https://api.carbonintensity.org.uk). |
| Parameters | Postcode variant required: postcode (outward code, e.g. RG10). Others: none. Optional: format (json). |
| Output | Successful: JSON with regions (regionid, dnoregion, shortname, intensity, generationmix). Failure: error details. |
Forward / Past / Range Regional Intensity
| Action | get48hForward*, get24hPast*, getRange* (Regional / Postcode / RegionID) |
|---|---|
| Purpose | Retrieves 48-hour-forward, 24-hour-past, and datetime-range carbon intensity for GB regions, a postcode, or a specific region ID. |
| Configuration | Configure the base URL via CONNECTOR_ENV_CARBONINTENSITY_BASE_URL (default https://api.carbonintensity.org.uk). |
| Parameters | Required (varies): from (and to for range) in ISO8601; postcode for postcode variants; regionid for region-ID variants. Optional: format (json). |
| Output | Successful: JSON with regional intensity and generation mix per period. Failure: error details. |
Example Workflow: Energy-Aware Scheduling
| Check current intensity | Call getCurrentIntensity (or getCurrentPostcode for a location) to read real-time carbon intensity. |
|---|---|
| Forecast | Use get24hForwardIntensity to find the greenest upcoming windows. |
| Regional detail | Use getCurrentRegional or getRangeRegionID for region-specific planning. |
| Analyze | Use getRangeStats and getIntensityFactors to report trends in a GCP dashboard. |
Support
For technical support, contact custom-connectors-support@isolutions.sa.