The National Grid have created a Carbon Intensity API for Great Britain. This allows you to access to predictions for carbon intensity across England, Scotland, and Wales.

The Carbon Minimiser sits on top of this, and allows you to estimate the optimal time to perform actions to reduce their impact on the planet, by choosing times when your area has a lower carbon intensity.

This API allows you to answer questions like:

What is the best 4 hour window to charge my electric car in the next 12 hours?

or

Which of our server locations should I deploy this process to for minimal carbon output?

You have to host your own version of this API. Feel free to make one publicly available - but remember requests to this API result in multiple requests to the National Grid Carbon Intensity API, so please use the caching option provided.

• Set up a virtual environment: python3 -m venv .venv

• Activate environment: source .venv/bin/activate

• Install dependencies: pip install -r requirements.txt

The default settings are found in config.ini. Here you can disable the cache (not recommended), change the cache refresh rate, and change the port number.

It is recommended you edit the LOCATIONS section to only list the locations you expect to be using. This will reduce the time it takes to cache and process your requests.

To run the API:

python3 -m carbon_minimiser

The API will then be available at http:https://localhost:8080

To run the suite of tests:

python3 -m pytest

Some calls accept results or range as optional URL parameters.

This parameter allows you to return the top n results like so: ?results=5

This parameter allows you to define a timerange you want the results to reside between: ?range=from,to.

These can be defined in intervals of 0.5 hours from the time of the last cache: ?range=3.5,10.

The range can be up to 47.5, as this is the furthest away prediction the Carbon Intensity API provides.

All numbers provided will be clipped to <=47.5, and rounded to the nearest 0.5.

This is a UTC (+00:00) timestamp in ISO8601 format

This is the forecast amount of CO2 in grams per kWh. For endpoints using a time window this is the averaged cost.

A measure of the Carbon Intensity represented on a scale between 'very low', 'low', 'moderate', 'high', 'very high'.

One of the locations defined in config.ini, from the list of possible locations

• URL: /optimise

• Method: GET

• URL Params

  Optional: results=[int] Optional: range=[int],[int]

• Success Response:

  • Code: 200
    Content: { "time": "YYYY-mm-ddThh:mmZ", "forecast": int, "index": str, "location": str }

• Sample Call: curl "http:https://localhost:8080/optimise?results=2&range=5,10"

• URL: /optimise/location

• Method: GET

• Success Response:

  • Code: 200
    Content: { "location": str, "cost": int, "index": str }

• Sample Call: curl http:https://localhost:8080/optimise/location

• URL: /optimise/location/<location>

• Method: GET

• URL Params

  • Required: <location> Key in Regions

  • Optional: results=[int]

  • Optional: range=[int],[int]

• Success Response:

  • Code: 200
    Content: { "time": "YYYY-mm-ddThh:mmZ", "forecast": int, "index": str }

• Error Response:

  • Code: 404
    Content: "Location not found"

• Sample Call: curl "http:https://localhost:8080/optimise/location/n_scotland?results=3&range=0,5"

• URL: /optimise/location/<location>/window/<window>

• Method: GET

• URL Params

  • Required:
    • <location> Key in Regions
    • <window> float number of hours (minimum resolution 0.5 hours)
  • Optional: results=[int]
  • Optional: range=[int],[int]

• Success Response:

  • Code: 200
    Content: { "time": "YYYY-mm-ddThh:mmZ", "cost": int }

• Error Response:

  • Code: 404
    Content: "Location not found"

• Sample Call: curl "http:https://localhost:8080/optimise/location/n_scotland/window/5?results=3&range=0,5"

• URL: /optimise/location/window/<window>

• Method: GET

• URL Params

  • Required:
    • <window> float number of hours (minimum resolution 0.5 hours)
  • Optional: results=[int]
  • Optional: range=[int],[int]

• Success Response:

  • Code: 200
    Content: { "location": str, "time": "YYYY-mm-ddThh:mmZ", "cost": int }

• Error Response:

  • Code: 404
    Content: "Location not found"

• Sample Call: curl "http:https://localhost:8080/optimise/location/window/5?results=2&range=0,5"