{"id":31844779,"url":"https://github.com/jonperron/carbem","last_synced_at":"2026-01-20T17:27:34.992Z","repository":{"id":315749862,"uuid":"1060698916","full_name":"jonperron/carbem","owner":"jonperron","description":"Carbem provides a unified interface for querying carbon emission data from various cloud service providers. This library helps developers build more environmentally conscious applications by making it easy to access and analyze the carbon footprint of cloud infrastructure.","archived":false,"fork":false,"pushed_at":"2025-09-28T17:19:39.000Z","size":17,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-28T18:23:38.422Z","etag":null,"topics":["carbon-emissions","cloud"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonperron.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-09-20T12:11:59.000Z","updated_at":"2025-09-28T17:19:41.000Z","dependencies_parsed_at":null,"dependency_job_id":"120974e5-4493-4709-8c84-5d37d8ba1672","html_url":"https://github.com/jonperron/carbem","commit_stats":null,"previous_names":["jonperron/carbem"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jonperron/carbem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonperron%2Fcarbem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonperron%2Fcarbem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonperron%2Fcarbem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonperron%2Fcarbem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonperron","download_url":"https://codeload.github.com/jonperron/carbem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonperron%2Fcarbem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279010676,"owners_count":26084785,"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","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["carbon-emissions","cloud"],"created_at":"2025-10-12T07:48:10.035Z","updated_at":"2026-01-20T17:27:34.979Z","avatar_url":"https://github.com/jonperron.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Carbem\n\nA Rust library for retrieving carbon emission values from cloud providers.\n\n## Overview\n\nCarbem provides a unified interface for querying carbon emission data from various cloud service providers. This library helps developers build more environmentally conscious applications by making it easy to access and analyze the carbon footprint of cloud infrastructure.\n\n## Features\n\n- 🌍 **Multi-provider support**: Unified API for different cloud providers\n- ⚡ **Async/await**: Built with modern async Rust for high performance\n- 🔒 **Type-safe**: Leverages Rust's type system for reliable carbon data handling\n- 🚀 **Easy to use**: Simple and intuitive API design\n- 🐍 **Python Bindings**: Native Python integration via PyO3\n- 🔧 **Flexible Filtering**: Filter by regions, services, and resources\n\n## Installation\n\n### Rust Library\n\nAdd this to your `Cargo.toml`:\n\n```toml\n[dependencies]\ncarbem = \"0.2.0\"\n```\n\n### Python Package\n\nInstall from PyPI:\n\n```bash\npip install carbem-python\n```\n\nFor development setup with maturin:\n\n```bash\npip install maturin\nmaturin develop\n```\n\n## Quick Start\n\n### Using Rust\n\nFor standalone Rust applications, use the builder pattern with environment variables:\n\n```rust\nuse carbem::{CarbemClient, EmissionQuery, TimePeriod};\nuse chrono::{Utc, Duration};\n\n#[tokio::main]\nasync fn main() -\u003e carbem::Result\u003c()\u003e {\n    // Configure client from environment variables\n    let client = CarbemClient::new()\n        .with_azure_from_env()?;\n    \n    // Create a query\n    let query = EmissionQuery {\n        provider: \"azure\".to_string(),\n        regions: vec![\"subscription-id\".to_string()],\n        time_period: TimePeriod {\n            start: Utc::now() - Duration::days(30),\n            end: Utc::now(),\n        },\n        services: Some(vec![\"compute\".to_string(), \"storage\".to_string()]),\n        resources: None,\n    };\n    \n    let emissions = client.query_emissions(\u0026query).await?;\n    \n    for emission in emissions {\n        println!(\"Service: {}, Emissions: {} kg CO2eq\", \n                 emission.service.unwrap_or_default(),\n                 emission.emissions_kg_co2eq);\n    }\n    \n    Ok(())\n}\n```\n\n### Using Python\n\nFor Python applications, use the `get_emissions_py` function:\n\n```python\nimport carbem\nimport json\nfrom datetime import datetime, timedelta\n\n# Azure configuration\nconfig = json.dumps({\n    \"access_token\": \"your-azure-bearer-token\"\n})\n\n# Query for last 30 days\nend_date = datetime.utcnow()\nstart_date = end_date - timedelta(days=30)\n\nquery = json.dumps({\n    \"start_date\": start_date.strftime(\"%Y-%m-%dT%H:%M:%SZ\"),\n    \"end_date\": end_date.strftime(\"%Y-%m-%dT%H:%M:%SZ\"),\n    \"regions\": [\"your-subscription-id\"],\n})\n\n# Get emissions data\nresult = carbem.get_emissions_py(\"azure\", config, query)\nemissions = json.loads(result)\n\nprint(f\"Found {len(emissions)} emission records\")\n```\n\nCreate a `.env` file in your project root:\n\n```env\n# Azure Carbon Emissions Configuration\nCARBEM_AZURE_ACCESS_TOKEN=your_azure_bearer_token_here\n# OR alternatively use:\n# AZURE_TOKEN=your_azure_bearer_token_here\n```\n\n## Configuration Parameters\n\n### Environment Variables (for Standalone Rust)\n\n- `CARBEM_AZURE_ACCESS_TOKEN`: Azure access token\n- `AZURE_TOKEN`: Alternative Azure access token variable\n\n### Python Configuration\n\nFor Python applications, configuration is passed as JSON strings to the `get_emissions_py` function. See the [Python API Documentation](docs/python_api.md) for detailed configuration examples and usage patterns.\n\n### Azure Configuration (AzureConfig)\n\nThe Azure provider requires minimal configuration:\n\n```rust\nuse carbem::AzureConfig;\n\nlet config = AzureConfig {\n    access_token: \"your-bearer-token\".to_string(),\n};\n```\n\n### Object-Oriented API (Advanced Usage)\n\n```rust\nuse carbem::{CarbemClient, AzureConfig, EmissionQuery, TimePeriod};\nuse chrono::{Utc, Duration};\n\n#[tokio::main]\nasync fn main() -\u003e carbem::Result\u003c()\u003e {\n    // Create a client and configure Azure provider\n    let config = AzureConfig {\n        access_token: \"your-bearer-token\".to_string(),\n    };\n    \n    let client = CarbemClient::new()\n        .with_azure(config)?;\n    \n    // Query carbon emissions for the last 30 days\n    let query = EmissionQuery {\n        provider: \"azure\".to_string(),\n        regions: vec![\"subscription-id\".to_string()], // Use your subscription IDs\n        time_period: TimePeriod {\n            start: Utc::now() - Duration::days(30),\n            end: Utc::now(),\n        },\n        services: None,\n        resources: None,\n    };\n    \n    let emissions = client.query_emissions(\u0026query).await?;\n    \n    for emission in emissions {\n        println!(\"Date: {}, Region: {}, Emissions: {} kg CO2eq\", \n                 emission.time_period.start.format(\"%Y-%m-%d\"),\n                 emission.region, \n                 emission.emissions_kg_co2eq);\n    }\n    \n    Ok(())\n}\n```\n\n## Supported Providers\n\n### Microsoft Azure ✅\n\n- **Report Types**: All report type from [the API](https://learn.microsoft.com/en-us/azure/carbon-optimization/api-export-data?source=recommendations\u0026tabs=OverallSummaryReport#report-types) are supported.\n- **Queries**: All [query parameters](https://learn.microsoft.com/en-us/azure/carbon-optimization/api-export-data?source=recommendations\u0026tabs=OverallSummaryReport#export-emissions-api-parameters) are supported.\n\n###  Google Cloud Platform\n\nGoogle Cloud Platform is not supported at the moment (October 11th 2025). Data are available only after exporting them to BigQuery as discussed in [this page](https://cloud.google.com/carbon-footprint/docs/api). Thus, one will need to make a query to the BigQuery API, which makes a standard implementation not possible at the moment.\n\n### Amazon Web Services (AWS)\n\nAWS is not supported at the moment (October 11th 2025). Data are available in S3 buckets as discussed in [this page](https://aws.amazon.com/fr/blogs/aws-cloud-financial-management/export-and-visualize-carbon-emissions-data-from-your-aws-accounts/). An endpoint existed but was discontinued on July 23rd 2025 ([ref](https://github.com/aws-samples/experimental-programmatic-access-ccft)).\n\n## Roadmap\n\n- [x] Core library infrastructure\n- [x] Azure Carbon Emission Reports API\n- [x] IBM Cloud Carbon Calculator\n- [ ] Amazon Web Services (AWS)\n- [ ] Google Cloud Platform (GCP)\n- [ ] Additional providers planned\n\n## Testing\n\nThe library includes a comprehensive test suite:\n\n```bash\n# Run all tests\ncargo test\n\n# Run specific Azure provider tests\ncargo test providers::azure\n\n# Run with output\ncargo test -- --nocapture\n```\n\nTest coverage includes:\n\n- Provider creation and configuration\n- Query conversion and validation\n- Date parsing and time period handling\n- Data conversion from Azure API responses  \n- Error handling for invalid configurations\n\n## Documentation\n\n### Rust Documentation\n\n- API Documentation: Available on [docs.rs](https://docs.rs/carbem/)\n\n### Python Documentation\n\n- [Python API Reference](docs/python_api.md) - Detailed function documentation and usage patterns  \n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nThis project is licensed under Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or \u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e)\n\n## Acknowledgments\n\nThis project aims to support sustainability efforts in cloud computing by making carbon emission data more accessible to developers and organizations.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonperron%2Fcarbem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonperron%2Fcarbem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonperron%2Fcarbem/lists"}