Official SDK

Python SDK

Official Python SDK for ZeroCarbon API. Perfect for data science, analytics, and backend applications.

pip install zerocarbon

View on GitHub

Installation

Install via pip or poetry

pip

pip install zerocarbon

poetry

poetry add zerocarbon

Quick Start

Initialize the SDK and start tracking emissions

Initialize the Client

from zerocarbon import ZeroCarbon
import os

# Initialize with your API key
client = ZeroCarbon(
    api_key=os.getenv('ZEROCARBON_API_KEY')
)

Submit Emissions Data

# Submit electricity usage
emission = client.emissions.submit(
    scope=1,
    source='electricity',
    value=1500,
    unit='kWh',
    activity_date='2026-01-07',
    location='Mumbai, India'
)

print(f"Emission recorded: {emission.value_tco2e} tCO2e")

API Reference

Complete list of available methods

Emissions

client.emissions.submit(**kwargs)

Submit new emissions data

Parameters:

scope (int) - Emission scope (1, 2, or 3)
source (str) - Emission source
value (float) - Activity value
unit (str) - Unit of measurement
activity_date (str) - Date (YYYY-MM-DD)
location (str, optional) - Location

client.emissions.list(**filters)

Retrieve emissions data

Filters:

start_date - Start date filter
end_date - End date filter
scope - Filter by scope

client.emissions.get(emission_id)

Get a specific emission by ID

Analytics

client.analytics.get()

Get comprehensive emissions analytics

client.analytics.by_scope()

Get emissions breakdown by scope

client.analytics.trend(period)

Get emissions trend over time

More Examples

Common use cases and patterns

Bulk Submit

emissions_data = [
    {
        'scope': 1,
        'source': 'electricity',
        'value': 1500,
        'unit': 'kWh'
    },
    {
        'scope': 2,
        'source': 'travel',
        'value': 250,
        'unit': 'km'
    }
]

for data in emissions_data:
    client.emissions.submit(**data)

Error Handling

from zerocarbon.exceptions import (
    RateLimitError
)

try:
    emission = client.emissions.submit(
        **data
    )
    print(f'Success: {emission}')
except RateLimitError:
    print('Rate limit exceeded')
except Exception as e:
    print(f'Error: {e}')

Get Analytics with Pandas

import pandas as pd

# Get analytics
analytics = client.analytics.get()

# Convert to DataFrame
df = pd.DataFrame(
    analytics['by_scope']
)
print(df)

Filter by Date Range

from datetime import datetime

emissions = client.emissions.list(
    start_date='2026-01-01',
    end_date='2026-01-31',
    scope=1
)

print(f'Found {len(emissions)} 
      emissions')

Data Science Integration

Perfect for Pandas, Jupyter notebooks, and data analysis

import pandas as pd
from zerocarbon import ZeroCarbon

client = ZeroCarbon(api_key='your_key')

# Get emissions as DataFrame
emissions = client.emissions.list(
    start_date='2026-01-01',
    end_date='2026-01-31'
)

df = pd.DataFrame(emissions)

# Analyze by source
print(df.groupby('source')['value_tco2e'].sum())

# Plot trends
df.plot(x='activity_date', y='value_tco2e', kind='line')

Need Help?

Check out our full API documentation or reach out to our support team

API Documentation Contact Support