From bd9682bd3ea66b988857ea9dde8f614a7ca388fc Mon Sep 17 00:00:00 2001 From: Hamza Mobeen Date: Sun, 19 Apr 2026 18:11:32 +0100 Subject: [PATCH] docs: explain electricitymaps_api_token and query behaviour (#403) Add a dedicated "Electricity Maps API Token" section to configuration.md clarifying what the parameter does (real-time vs annual-average carbon intensity), how often the API is queried, where to get a free token, and that co2_signal_api_token is the deprecated predecessor. --- docs/how-to/configuration.md | 38 ++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/docs/how-to/configuration.md b/docs/how-to/configuration.md index e8b42b929..39d600ec2 100644 --- a/docs/how-to/configuration.md +++ b/docs/how-to/configuration.md @@ -84,6 +84,44 @@ Yields attributes: which relies on the [INI syntax](https://docs.python.org/3/library/configparser.html#supported-ini-file-structure). +## Electricity Maps API Token + +By default, CodeCarbon estimates carbon intensity using annual country-level +averages from Our World in Data. Providing an `electricitymaps_api_token` +upgrades this to **real-time carbon intensity** data from the +[Electricity Maps API](https://api.electricitymaps.com), giving more accurate +emissions figures — especially useful if your grid's energy mix varies +throughout the day. + +**Without a token:** CodeCarbon uses a static annual average for your country. + +**With a token:** CodeCarbon queries the Electricity Maps API for the current +carbon intensity of your grid. The query runs at the end of each tracking run, +and also periodically during long runs (every +`api_call_interval × measure_power_secs` seconds; default: every ~2 minutes). + +The Electricity Maps API offers a free tier. You can sign up and get a token at +[electricitymaps.com](https://app.electricitymaps.com/sign-up). + +Set it in your config file: + +``` ini +[codecarbon] +electricitymaps_api_token = your-token-here +``` + +Or in code: + +``` python +EmissionsTracker(electricitymaps_api_token="your-token-here") +``` + +!!! note "Deprecated parameter" + + The old parameter name `co2_signal_api_token` still works for backward + compatibility but is deprecated and will be removed in a future version. + Use `electricitymaps_api_token` instead. + ## Access internet through proxy server If you need a proxy to access internet, which is needed to call a Web