Python SDK

<div class="admonition admonition-warning"><span class="admonition-icon">⚠️</span><div class="admonition-content"><p>Coming Soon The Python SDK is under development. In the meantime, you can call the API directly using <code>requests</code> or <code>httpx</code> — see the <a href="/docs/api">API Reference</a> for endpoints and parameters.</p> </div></div>

Official Python client for the emissions.dev API.

Installation

pip install emissions-dev

Requirements: Python 3.8+

Quick Start

from emissions_dev import EmissionsClient

client = EmissionsClient(api_key="em_live_xxxx")

result = client.freight.calculate(
    origin_country="GB",
    destination_country="FR",
    weight=1000
)

print(f"Emissions: {result.data.attributes.emissions.co2e} kg CO2e")

Configuration

client = EmissionsClient(
    api_key="em_live_xxxx",
    base_url="https://api.emissions.dev/v1",
    timeout=30,
    retries=3
)

Freight API

result = client.freight.calculate(
    origin_country="GB",
    destination_country="DE",
    origin_location="London",
    destination_location="Berlin",
    weight=5000,
    transport_mode="road",
    equivalents=True
)

print(f"CO2e: {result.data.attributes.emissions.co2e} kg")
print(f"Distance: {result.data.attributes.route.total_distance_km} km")

Travel API

result = client.travel.calculate(
    origin_country="GB",
    destination_country="FR",
    origin_location="London",
    destination_location="Paris",
    transport_mode="flight",
    cabin_class="business",
    passengers=2,
    return_trip=True
)

print(f"Total: {result.data.attributes.emissions.co2e} kg")
print(f"Per passenger: {result.data.attributes.emissions.per_passenger_kg} kg")

Hotel API

# Calculate emissions
result = client.hotel.calculate(
    country="GB",
    nights=3,
    rooms=1
)

# Get all factors
factors = client.hotel.factors()
for country in factors.data:
    print(f"{country.country_name}: {country.factor} kg/night")

# Compare countries
comparison = client.hotel.compare(
    countries=["GB", "FR", "DE", "ES"],
    nights=5
)

Error Handling

from emissions_dev import EmissionsClient
from emissions_dev.exceptions import (
    UnauthorizedError,
    ValidationError,
    RateLimitError
)

try:
    result = client.freight.calculate(
        origin_country="GB",
        destination_country="XX",
        weight=1000
    )
except UnauthorizedError:
    print("Invalid API key")
except ValidationError as e:
    print(f"Validation error: {e.field} - {e.message}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")

Django Example

from django.http import JsonResponse
from emissions_dev import EmissionsClient
import json

client = EmissionsClient()

def calculate_shipping(request):
    data = json.loads(request.body)
    
    result = client.freight.calculate(
        origin_country=data["from_country"],
        destination_country=data["to_country"],
        weight=data["weight_kg"]
    )
    
    return JsonResponse({
        "co2e_kg": result.data.attributes.emissions.co2e
    })