←Back to API DocsZeroCarbon Logo
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-sdk

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')
)

Record Emissions

# Record Scope 1 emissions (diesel generator)
result = client.emissions.create(
    scope=1,
    source='diesel_generator',
    activity_value=500,
    activity_unit='liters',
    period='January 2026',
    activity_date='2026-01-15',
    data_quality='measured',
    notes='Backup generator usage'
)

print(f"Recorded: {result['emission']['value_tco2e']} tCO2e")
print(f"ID: {result['emission']['id']}")

API Reference

Complete list of available methods

Emissions

client.emissions.create(**kwargs)

Record new emissions data with detailed tracking

Parameters:

  • scope (int) - Emission scope (1, 2, or 3)
  • source (str) - Emission source (diesel_generator, electricity_grid, etc.)
  • activity_value (float) - Activity quantity
  • activity_unit (str) - Unit of measurement (liters, kWh, km)
  • activity_date (str) - Date (YYYY-MM-DD)
  • period (str) - Reporting period
  • data_quality (str, optional) - measured, estimated, calculated
  • notes (str, optional) - Additional notes

client.emissions.list(**filters)

Retrieve emissions records with filters

Filters:

  • scope - Filter by scope (1, 2, or 3)
  • from_date - Start date filter
  • to_date - End date filter
  • page - Page number
  • limit - Results per page

Calculate

client.calculate.electricity(**kwargs)

Calculate emissions from electricity consumption

Parameters:

  • amount_kwh (float) - Electricity consumed in kWh
  • country (str) - Country code (IN, US, UK, etc.)
  • state (str, optional) - State/region
  • renewable_percentage (float, optional) - Renewable energy %

client.calculate.flight(**kwargs)

Calculate flight emissions by route

Parameters:

  • origin (str) - Origin airport code (IATA)
  • destination (str) - Destination airport code
  • cabin_class (str) - economy, business, first
  • passengers (int, optional) - Number of passengers

client.calculate.fuel(**kwargs)

Calculate emissions from fuel combustion

Parameters:

  • amount (float) - Fuel quantity
  • fuel_type (str) - diesel, petrol, natural_gas, etc.
  • unit (str) - liters, gallons, cubic_meters

client.calculate.spend(**kwargs)

Calculate Scope 3 emissions using spend-based method

Parameters:

  • amount (float) - Spend amount
  • currency (str) - INR, USD, EUR, GBP
  • category (str) - Spend category (transportation, materials, services)
  • description (str, optional) - Description for ML matching

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 DocumentationContact Support