jnioche/carbonintensity-api

A simple Rust library to retrieve data from https://api.carbonintensity.org.uk/

carbonintensity-api

A simple Rust library to help retrieve data from the Carbon Intensity API, not all functionalities of the CarbonIntensity API might be exposed.

Please read the API's terms of use.

CLI

An executable is provided to try the library. With Rust and Cargo installed

cargo install --path .

then

carbonintensity-api -h

should display the list of available commands and options.

Provides a client for the UK National Grid Carbon Intensity API

Usage: carbonintensity-api [OPTIONS] <VALUE>

Arguments:
  <VALUE>  numerical value for a region (1-17) or first part of a UK postcode

Options:
  -s, --start-date <START_DATE>  
  -e, --end-date <END_DATE>
  -h, --help                     Print help
  -V, --version                  Print version

To display the current carbon intensity for a given postcode

carbonintensity-api bs7

To do the same for a region

carbonintensity-api 11

The region id is a number between 1 and 17

1. North Scotland
2. South Scotland
3. North West England
4. North East England
5. South Yorkshire
6. North Wales, Merseyside and Cheshire
7. South Wales
8. West Midlands
9. East Midlands
10. East England
11. South West England
12. South England
13. London
14. South East England
15. England
16. Scotland
17. Wales

Specifying dates will return a list of intensities for a region or postcode. If no end date is provided, the current day and time will be used.

The dates are expected to be at the %Y-%m-%dT%H:%MZ format or simply %Y-%m-%d, for instance

carbonintensity-api -s 2023-11-11 -e 2023-11-11T12:00Z postcode bs7

Intensities are returned by 30 mins windows.

Library

You can use the library in your Rust project by adding it to cargo with

cargo add carbonintensity-api

then declaring it in your code

use carbonintensity::{
    get_intensities_postcode, get_intensities_region, get_intensity_postcode, get_intensity_region,
    ApiError,
};

...

  let result = get_intensity_postcode(postcode).await;

License

This project is provided under Apache License.

carbonintensity-api's Issues

Handle date ranges of more than 13 days

The CI API limits the range between the start and end dates to 14 days. An error is returned if a user provides a greater range.
We could at least provide a utility function to return the list of maximum ranges for a given input so that the end users can call the methods themselves for each range.

Later on we could do these calls in parallel and return a unified output.

Shift date and / or time before calling the API

The API returns the 30min slot with the range inclusive of the start date

carbonintensity-api -s 2023-11-19 postcode bs7
2023-11-18 23:30:00, 223
2023-11-19 00:00:00, 241
...

We should rewrite the start date so that it is aligned with the closest 30 min boundary + 1min

Improve outputs for date ranges

We currently return the whole RegionData

pub struct RegionData {
    regionid: i32,
    dnoregion: Option<String>,
    shortname: String,
    postcode: Option<String>,
    data: Vec<Data>,
}

including the GenerationMix which is pretty verbose. The dates are also returned as strings, which takes further processing.

If #3 gets implemented we would also need to merge the outputs from individual calls into a single output.

Simplify CLI arguments

Since a postcode starts with a letter and a region is a numerical value, it would possible to remove the subcommand (postcode region) altogether and determine what the user wants from the input itself.
Additionally, passing nothing at all could return data for the country as a whole.

Retrieve data at the national level

and not just at the regional level

Prevent CLI to panic when the pipe is broken

rust-lang/rust#46016 (comment)

carbonintensity-api -s 2023-11-11 postcode bs7 | head

Fix handling of postcodes

The outward code can be between 2 and 4 characters

https://en.wikipedia.org/wiki/Postcodes_in_the_United_Kingdom

carbonintensity-api postcode wc2n currently fails

day skipped when querying a date range straddling 2 years

Currently goes straight from

2022-12-31 23:00:00

to

2023-01-02 22:30:00

Send requests to CarbonAPI in multiple threads

when the range exceeds 13 days, this is currently done sequentially