{"id":18376939,"url":"https://github.com/bbc/carbon-minimiser","last_synced_at":"2025-04-06T20:31:56.021Z","repository":{"id":55198087,"uuid":"432135787","full_name":"bbc/carbon-minimiser","owner":"bbc","description":"An API which performs optimisation operations on data from carbonintensity.org.uk","archived":false,"fork":false,"pushed_at":"2024-07-29T15:30:17.000Z","size":33,"stargazers_count":18,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-07-30T19:51:20.847Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bbc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-26T10:16:43.000Z","updated_at":"2024-07-29T15:30:31.000Z","dependencies_parsed_at":"2024-04-18T17:08:48.650Z","dependency_job_id":null,"html_url":"https://github.com/bbc/carbon-minimiser","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fcarbon-minimiser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fcarbon-minimiser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fcarbon-minimiser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fcarbon-minimiser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbc","download_url":"https://codeload.github.com/bbc/carbon-minimiser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223263753,"owners_count":17115970,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T00:25:30.952Z","updated_at":"2024-11-06T00:25:33.062Z","avatar_url":"https://github.com/bbc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Carbon Minimisation API\n\n# Background\nThe National Grid have created [a Carbon Intensity API for Great Britain](https://api.carbonintensity.org.uk/). This allows you to access to predictions for carbon intensity across England, Scotland, and Wales.\n\nThe 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.\n\n# What this API does\n\nThis API allows you to answer questions like:\n\n```What is the best 4 hour window to charge my electric car in the next 12 hours?```\n\nor\n\n```Which of our server locations should I deploy this process to for minimal carbon output?```\n\n# Important Note\n\nYou 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.\n\n\n## Running the API\n\n### Set up\n\n* Set up a virtual environment:\n`python3 -m venv .venv`\n\n* Activate environment:\n`source .venv/bin/activate`\n\n* Install dependencies:\n`pip install -r requirements.txt`\n\n### Configuration\nThe 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.\n\nIt 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.\n\n### Running\n\nTo run the API:\n\n`python3 -m carbon_minimiser`\n\nThe API will then be available at `http://localhost:8080`\n\n### Testing\n\nTo run the suite of tests:\n\n`python3 -m pytest`\n\n## Endpoints\n\n### Optional Parameters\nSome calls accept `results` or `range` as optional URL parameters.\n\n#### results\nThis parameter allows you to return the top `n` results like so:\n`?results=5\n`\n#### range\nThis parameter allows you to define a timerange you want the results to reside between: `?range=from,to`.\n\nThese can be defined in intervals of 0.5 hours from the time of the last cache: `?range=3.5,10`.\n\nThe range can be up to 47.5, as this is the furthest away prediction the Carbon Intensity API provides. \n\nAll numbers provided will be clipped to \u003c=47.5, and rounded to the nearest 0.5.\n\n\n### Returned values\n\n#### time\nThis is a UTC (+00:00) timestamp in ISO8601 format\n\n#### forecast\nThis is the forecast amount of CO2 in grams per kWh. For endpoints using a time window this is the averaged cost.\n\n#### index\nA measure of the Carbon Intensity represented on a scale between 'very low', 'low', 'moderate', 'high', 'very high'.\n\n#### location\nOne of the locations defined in config.ini, from the [list of possible locations](https://carbon-intensity.github.io/api-definitions/#region-list)\n\n\n### Get optimal time and location\n#### Returns the place and time over the next 48 hours with the lowest carbon intensity\n\n* **URL:** `/optimise`\n\n* **Method:** `GET`\n\n*  **URL Params**\n\n   **Optional:** `results=[int]`\n   **Optional:** `range=[int],[int]`\n\n* **Success Response:**\n\n  * **Code:** 200 \u003cbr /\u003e\n    **Content:** `{\n      \"time\": \"YYYY-mm-ddThh:mmZ\",\n      \"forecast\": int,\n      \"index\": str,\n      \"location\": str\n    }`\n\n* **Sample Call:** `curl \"http://localhost:8080/optimise?results=2\u0026range=5,10\"`\n\n### Get optimal location right now\n#### Returns the place with the lowest carbon intensity currently\n\n* **URL:** `/optimise/location`\n\n* **Method:** `GET`\n\n* **Success Response:**\n\n  * **Code:** 200 \u003cbr /\u003e\n    **Content:** `{\n      \"location\": str,\n      \"cost\": int,\n      \"index\": str\n    }`\n\n* **Sample Call:** `curl http://localhost:8080/optimise/location`\n\n### Get optimal time for a given location\n#### Returns the time over the next 48 hours with the lowest carbon intensity, in the specified location\n\n* **URL:** `/optimise/location/\u003clocation\u003e`\n\n* **Method:** `GET`\n\n*  **URL Params**\n   \n    * **Required:** `\u003clocation\u003e` [Key in Regions](https://github.com/bbc/rd-carbon-intensity-exporter/blob/11e17d679f8ff0611d1fd585d493811e603ce3fc/carbon_intensity_exporter/carbon_api_wrapper/carbon.py#L4)\n   \n    * **Optional:** `results=[int]`\n    * **Optional:** `range=[int],[int]`\n\n* **Success Response:**\n\n  * **Code:** 200 \u003cbr /\u003e\n    **Content:** `{\n      \"time\": \"YYYY-mm-ddThh:mmZ\",\n      \"forecast\": int,\n      \"index\": str\n    }`\n    \n* **Error Response:**\n\n  * **Code:** 404 \u003cbr /\u003e\n    **Content:** `\"Location not found\"`\n\n* **Sample Call:** `curl \"http://localhost:8080/optimise/location/n_scotland?results=3\u0026range=0,5\"`\n\n### Get optimal time window for a location\n#### Given a time window of H hours, returns the optimal start time to minimise average carbon usage over H hours, along with the average carbon forecast in gC02/kWh\n\n* **URL:** `/optimise/location/\u003clocation\u003e/window/\u003cwindow\u003e`\n\n* **Method:** `GET`\n\n*  **URL Params**\n   \n    * **Required:** \n      * `\u003clocation\u003e` [Key in Regions](https://github.com/bbc/rd-carbon-intensity-exporter/blob/11e17d679f8ff0611d1fd585d493811e603ce3fc/carbon_intensity_exporter/carbon_api_wrapper/carbon.py#L4)\n      * `\u003cwindow\u003e` float number of hours (minimum resolution 0.5 hours)  \n    * **Optional:** `results=[int]`\n    * **Optional:** `range=[int],[int]`\n\n* **Success Response:**\n\n  * **Code:** 200 \u003cbr /\u003e\n    **Content:** `{\n      \"time\": \"YYYY-mm-ddThh:mmZ\",\n      \"cost\": int\n    }`\n    \n* **Error Response:**\n\n  * **Code:** 404 \u003cbr /\u003e\n    **Content:** `\"Location not found\"`\n\n* **Sample Call:** `curl \"http://localhost:8080/optimise/location/n_scotland/window/5?results=3\u0026range=0,5\"`\n\n### Get optimal time window and location\n#### Given a time window of H hours, returns the optimal start time and location to minimise average carbon over H hours, along with the average carbon forecast in gC02/kWh\n\n* **URL:** `/optimise/location/window/\u003cwindow\u003e`\n\n* **Method:** `GET`\n\n*  **URL Params**\n   \n    * **Required:** \n      * `\u003cwindow\u003e` float number of hours (minimum resolution 0.5 hours)  \n    * **Optional:** `results=[int]`\n    * **Optional:** `range=[int],[int]`\n\n* **Success Response:**\n\n  * **Code:** 200 \u003cbr /\u003e\n    **Content:** `{\n      \"location\": str,\n      \"time\": \"YYYY-mm-ddThh:mmZ\",\n      \"cost\": int\n    }`\n    \n* **Error Response:**\n\n  * **Code:** 404 \u003cbr /\u003e\n    **Content:** `\"Location not found\"`\n\n* **Sample Call:** `curl \"http://localhost:8080/optimise/location/window/5?results=2\u0026range=0,5\"`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbc%2Fcarbon-minimiser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbc%2Fcarbon-minimiser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbc%2Fcarbon-minimiser/lists"}