{"id":48356783,"url":"https://github.com/green-coding-solutions/elephant","last_synced_at":"2026-04-05T11:33:38.379Z","repository":{"id":331022587,"uuid":"1067657758","full_name":"green-coding-solutions/elephant","owner":"green-coding-solutions","description":"Grid carbon intensity provider which supports simulation as well as multiple real time data API backends like EM, Wattime etc. ","archived":false,"fork":false,"pushed_at":"2026-03-10T13:48:15.000Z","size":645,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-10T20:14:50.161Z","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":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/green-coding-solutions.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-01T07:29:47.000Z","updated_at":"2026-03-10T13:48:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/green-coding-solutions/elephant","commit_stats":null,"previous_names":["green-coding-solutions/elephant"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/green-coding-solutions/elephant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-coding-solutions%2Felephant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-coding-solutions%2Felephant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-coding-solutions%2Felephant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-coding-solutions%2Felephant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/green-coding-solutions","download_url":"https://codeload.github.com/green-coding-solutions/elephant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-coding-solutions%2Felephant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31434624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T08:13:15.228Z","status":"ssl_error","status_checked_at":"2026-04-05T08:13:11.839Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":"2026-04-05T11:33:36.755Z","updated_at":"2026-04-05T11:33:38.360Z","avatar_url":"https://github.com/green-coding-solutions.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Elephant 🐘\n\n**Elephant** is a specialized Carbon Grid Intensity (CGI) service. It provides current and historical carbon intensity data from multiple providers.\n\nIts main purpose is the integration into the Green Metrics Tool (GMT) to provide dynamic carbon intensity values.\n\n![Elephant UI](Screenshot.png)\n\n## Installation\n\n```bash\ngit clone https://github.com/green-coding-solutions/elephant\ncd elephant\n\n# Create virtual environment\npython3 -m venv venv\nsource venv/bin/activate\n\n# Install dependencies\npip install -r requirements.txt\n```\n\n## Configuration\n\nBefore running Elephant, you need to configure your data providers:\n\n```bash\n# Copy the example configuration\ncp config.example.yml config.yml\n```\n\nEdit `config.yml` and add API tokens per source in `cron.sources` (via `api_token`).\nIf a source should skip historical fetches, set `only_get_current: true` on that source.\nYou can also set `resolution` per source to override provider defaults (for example ElectricityMaps `5_minutes`).\nSet `update_iterval` (seconds) on a source to run it less frequently than the global cron loop (`run_cron_checker_seconds`).\n\nFor ElectricityMaps: Replace \"your-electricitymaps-api-token-here\" with your actual token. You don't need to modify anything to start collection. We use free endpoints per default.\n\n\n## Running\n\nYou should just be able to do\n```bash\ndocker compose up --build\n```\n\nand that should set everythin up so that you can access Elephant under `http://localhost:8085/`\n\n**Required for ElectricityMaps:**\n\n- Sign up at [ElectricityMaps](https://portal.electricitymaps.com/) to get an API token\n- Add a `cron.sources` entry with `provider: \"electricitymaps\"` and set its `api_token`\n\n## Development\nYou should be able to\n\n```\npip install -r requirements-dev.txt\npylint --recursive=y elephant/\npytest tests\n```\n\nAlso for development it might be easier to not having to build a docker container all the time. So you can only run the DB with\n\n```bash\ndocker compose up -d db\n```\n\nand then run the commands on your development machine\n\n```bash\npython3 -m elephant.database\npython3 -m elephant.cron\npython3 -m elephant --host 0.0.0.0 --port 8085\n```\n\n## API\n\nOnce Elephant is running (for example with `docker compose up --build`), the generated docs are available at:\n\n- Swagger UI: `http://localhost:8085/docs`\n- ReDoc: `http://localhost:8085/redoc`\n\n### Core endpoints\n\n- `GET /carbon-intensity/current` — Latest carbon intensities for a region. Query params: `region` (ISO 3166-1 alpha-2), optional `update` (force refresh) and `simulation_id` (serve simulated data).\n- `GET /carbon-intensity/current/primary` — Latest carbon intensity from the configured primary provider for `region`; also accepts `update` and `simulation_id`.\n- `GET /carbon-intensity/history` — Historical values between `startTime` and `endTime` (ISO 8601) for `region`.\n- `GET /regions` — List of regions with stored data.\n- `GET /health` — Service health, providers, DB record count, and regions.\n\n### Simulation endpoints\n\nElephant includes a lightweight simulator so you can drive client integrations or demos without live provider data.\n\n- `POST /simulation` with a JSON body `{\"carbon_values\": [120, [140, 2], [100, null]]}` registers a run and returns a `simulation_id`. Each entry is either a float or a `[value, calls]` pair; `calls` is how often that value is returned before automatically advancing (use `null` to disable auto-advance).\n- `GET /simulation/get_carbon?simulation_id=...` returns the current simulated carbon intensity and will auto-advance when call thresholds are met.\n- `POST /simulation/next?simulation_id=...` forces the next value.\n- `GET /simulation/stats?simulation_id=...` shows the current index and call history for debugging.\n\nYou can plug a simulation into the core responses by passing `simulation_id`:\n\n```bash\ncurl \"http://localhost:8085/carbon-intensity/current?region=DE\u0026simulation_id=\u003csimulation_id\u003e\"\ncurl \"http://localhost:8085/carbon-intensity/current/primary?region=DE\u0026simulation_id=\u003csimulation_id\u003e\"\n```\n\n### Electricity Maps compatible endpoints\n\nFor Electricity Maps compatible payloads, use the v3 endpoints:\n\n```bash\ncurl \"http://localhost:8085/v3/carbon-intensity/current?zone=DE\"\ncurl \"http://localhost:8085/v3/carbon-intensity/history?zone=DE\"\n```\n\nThey mirror the Electricity Maps API schema. To serve simulated data to an Electricity Maps client, send the simulation id as `auth-token`:\n\n```bash\ncurl -H \"auth-token: \u003csimulation_id\u003e\" \"http://localhost:8085/v3/carbon-intensity/current?zone=DE\"\ncurl -H \"auth-token: \u003csimulation_id\u003e\" \"http://localhost:8085/v3/carbon-intensity/history?zone=DE\"\n```\n\n\n## Credit / Funding\n\nThis work is funded by the Deutsche Bundesstiftung Umwelt (DBU) under the number [DBU Project 39703/01](https://www.dbu.de/projektdatenbank/39703-01/)\n\nProject details are to be found on the [project page](https://greencoding.f2.htw-berlin.de/projekte/caso-entwicklung-von-technologien-zur-co2-und-energieeinsparung-bei-der-softwareentwicklung/)\n\n![DBU Logo](https://www.dbu.de/app/uploads/jpg-DBU-Logosponsored-by-RGB.jpg)\n\nWe are super grateful for this funding and are blessed to have been granted the opportunity to create this data repository for the greater\nsoftware community!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgreen-coding-solutions%2Felephant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgreen-coding-solutions%2Felephant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgreen-coding-solutions%2Felephant/lists"}