ofpiyush/carbonintensity-api repository overview

⁠CarbonIntensity API

API server for pseudo-realtime production carbon intensity data in gCO2eq/kWh for any zone supported by https://github.com/tmrowco/electricitymap-contrib⁠.

⁠Installation and running

⁠With Docker

docker run -p 80:80 ofpiyush/carbonintensity-api:stable

⁠Local

The code has been teted working on Python 3.7.0. It should work in compatible versions. You can use pyenv⁠ to manage python versions

1. Fork and clone this repository and submodules

   Replace <username> with your github username.

   git clone --recurse-submodules [email protected]:<username>/carbonintensity-api
   

   Copy

2. Install dependencies

   Within your virtualenv

   pip install -r requirements.txt
   pip install -r electricitymapcontrib/parsers/requirements.txt
   

   Copy

3. Start the server

   python app.py
   

   Copy

⁠Usage

Change http://localhost to the host and port combo of your environment.

curl 'http://localhost/carbon-intensity/latest?zone=IN-KA'
{
  "zone": "IN-KA",
  "carbonIntensity": 474,
  "datetime": "2020-11-21T04:30:00Z",
  "updatedAt": "2020-11-21T04:30:00Z"
}

⁠Contributing

1. Create an issue with the problem you're trying to solve or improvement you'd like to see.
2. Fork and clone the repo.
3. Use the local install guide above.
4. Install dev requirements with:

   pip install -r dev.requirements.txt
   

   Copy
5. Make your changes
6. Run before committing

   black --exclude electricitymapcontrib .
   

   Copy
7. Open a PR!

⁠Motivation

This API server is meant to be a self-hosted, free drop-in replacement of https://api.electricitymap.org/v3/carbon-intensity/latest⁠ endpoint. (Documentation⁠)

While working on https://github.com/thegreenwebfoundation/grid-intensity-go⁠, I needed a test server to check my client implementation of https://api.electricitymap.org⁠.

⁠Goals

• Be a free, API compatible replacement of https://api.electricitymap.org/v3/carbon-intensity/latest⁠.
• Be capable of testing or light loads (like the ones from a perioidically running kube-scheduler-plugin)

⁠Non-Goals

• Add sophisticated modeling methods to get more accuracy.
• Be a complete replacement for all endopoints of api.electricitymap.org/v3.

⁠When should you pay for api.electricitymap.org instead?

⁠You want more than just the latest carbon intensity data

This project has exactly one endpoint. If you want historical data or forecasts, buy their API key!

⁠If you need more accurate data

This project relies on production data from open source parsers available at https://github.com/tmrowco/electricitymap-contrib⁠.

While production is a decent lens to guess CO2 emissions, api.electricitymap.org uses better lenses⁠.

⁠If you want to make a lot of requests

Right now, this project doesn't cache or save data from the data sources in any way. Each request you make refetches and parses data from the original source.

If you're going to make a lot of requests, be a nice citizen and either cache the data or buy an API key.

⁠If you have money to support a company combating climate change with open source

This project is a thin wrapper over the open source parsers that Tomorrow⁠ maintains.

Go buy from them⁠ so that they can invest in more and better parsers.