Step 3 - Calculate Scope 2 Emissions - Dcycle API Documentation

Understanding Scope 2 Emissions

Scope 2 emissions are indirect greenhouse gas emissions from the generation of purchased energy consumed by your organization. According to the GHG Protocol Scope 2 Guidance, these include:

Electricity: Power purchased from the grid or third-party providers
Steam: Purchased steam for industrial processes
Heating: District heating or purchased heat
Cooling: District cooling services

┌─────────────────────────────────────────────────────────────────────────────┐
│                      SCOPE 2: Indirect Energy Emissions                     │
├─────────────────────┬─────────────────────┬─────────────────────────────────┤
│  Electricity        │  Heat & Steam       │  Cooling                        │
├─────────────────────┼─────────────────────┼─────────────────────────────────┤
│  • Grid electricity │  • District heating │  • District cooling             │
│  • Supplier-specific│  • Purchased steam  │  • Purchased chilled water      │
│  • Renewable energy │  • Industrial heat  │  • Central cooling systems      │
│  • Green tariffs    │  • CHP outputs      │                                 │
└─────────────────────┴─────────────────────┴─────────────────────────────────┘

Dual Reporting RequirementThe GHG Protocol requires organizations to report Scope 2 emissions using two methods:

Location-based: Uses average grid emission factors for where energy is consumed
Market-based: Uses supplier-specific emission factors based on contractual instruments

Dcycle automatically calculates both methods when you upload electricity invoices.

Prerequisites

Before starting, ensure you have:

Dcycle API credentials (get them here)
At least one facility configured with the correct country
Energy consumption data: electricity bills, utility invoices, or meter readings
(Optional) Supplier information for market-based calculations

Using the Dcycle App?You can also manage your energy consumption through our web interface:

Upload utility invoices - Track electricity and heat consumption
Configure suppliers - Set up electricity suppliers for market-based
Datadis integration - Automatic electricity data import (Spain only)

Calculating Electricity Emissions

Electricity consumption is typically the largest component of Scope 2 emissions. In Dcycle, these are tracked through invoices with type: "electricity".

Emission Sources Covered

Source Type	Invoice Type	Examples
Grid electricity	`electricity`	Office buildings, warehouses, factories
Renewable electricity	`electricity` + supplier	Green tariffs, PPAs, renewable certificates
District heating	`COMING SOON!`	Centralized heating systems
District cooling	`COMING SOON!`	Centralized cooling systems

Calculation Methods: Location-based vs Market-based

Location-based Method
Market-based Method

The location-based method uses average grid emission factors based on where energy is consumed. This reflects the average emissions intensity of the local grid.

Facility (any country) → Invoice → Grid EF by Location → CO₂e
      ↓                     ↓              ↓                ↓
  Country from          kWh consumed    Grid emission    Reflects average
  facility address                      factors          grid emissions

Key characteristics:

Uses country/regional grid average emission factors
Emission factors from Ecoinvent and REE (Red Eléctrica Esañola)
Updated when new version of Ecoinvent or REE (annually) is released
Required for GHG Protocol compliance

Emission Factor Sources - Location-based

For location-based calculations, Dcycle uses emission factors from:

Ecoinvent - Global grid emission factors
REE (Red Eléctrica de España) - Spain-specific factors

Factors are automatically selected based on:

Facility country
Invoice year
Latest available data version

Calculation Details - Location-based

Location-based emissions are calculated as:CO₂e = Energy Consumed (kWh) × Grid Emission Factor (kg CO₂e/kWh)Where:

Energy Consumed: Electricity consumption in kWh
Grid EF: Average emission factor for the country/region grid

Example (Non-renewable electricity in Spain, 2024):

10,000 kWh × 0.1 kg CO₂e/kWh = 1,000 kg CO₂e

Note: Spain’s grid has been decarbonizing rapidly, so emission factors vary significantly by year.

The market-based method uses emission factors from contractual instruments that convey claims about the emissions attributes of purchased electricity.

Facility → Invoice + Supplier → Supplier-specific EF → CO₂e
      ↓           ↓                    ↓                  ↓
  Country     kWh + supplier      Contractual EF      Reflects supplier
              information                             energy mix

Key characteristics:

Uses supplier-specific emission factors (when available)
Reflects actual contractual arrangements
Can show zero emissions for 100% renewable suppliers

For Spain, Dcycle uses CNMC-published emission factors for each electricity supplier.

Emission Factor Sources - Market-based

For market-based calculations, Dcycle uses emission factors from:

CNMC (Spain) - Supplier-specific factors published annually
Supplier certificates - When provided by the user (custom emission factors)

Calculation Details - Market-based

Market-based emissions are calculated as:CO₂e = Energy Consumed (kWh) × Supplier Emission Factor (kg CO₂e/kWh)Where:

Energy Consumed: Electricity consumption in kWh
Supplier EF: Emission factor specific to your electricity supplier

Example (100% renewable supplier):

10,000 kWh × 0.00 kg CO₂e/kWh = 0 kg CO₂e

Note: Market-based can be higher or lower than location-based depending on your supplier’s energy mix.

Automatic Dual CalculationWhen you upload an electricity invoice, Dcycle automatically calculates both location-based and market-based emissions. Both values are stored and available in reports for GHG Protocol compliance.

What you’ll track:

Facility Setup → Electricity Invoice → Dual Calculation
      ↓                 ↓                     ↓
  Country config    kWh + supplier     Location-based + Market-based

Data Flow

Configure Facility

Ensure your facility has the correct country configured (determines location-based EF)

(Optional) Set Up Supplier

Link an electricity supplier to enable market-based calculation with specific factors

Create Electricity Invoice

Record electricity consumption in kWh with date range

Automatic Calculation

Dcycle calculates both location-based and market-based emissions

View Dual Results

Both emission values are stored for reporting compliance

Step 3.1: Create an Electricity Invoice (Location-based)

📋 Data Map: Electricity Invoice (Location-based)

Field	Type	Required	Description	Example
`type`	string	✅	Invoice type	`"electricity"`
`facility_id`	UUID	✅	Facility consuming the energy	`"abc-123-..."`
`base_quantity`	number	✅	Energy consumed	`10000`
`unit_id`	UUID	✅	Unit (kWh)	`"ba80e6cb-..."`
`start_date`	date	✅	Billing period start	`"2024-01-01"`
`end_date`	date	✅	Billing period end	`"2024-01-31"`
`invoice_id`	string	❌	Your reference number	`"ELEC-2024-001"`
`uploaded_by`	UUID	✅	User uploading	`"user-uuid"`

Where to get this data:

Facility ID: From Step 1 (company structure setup) or GET /api/v1/facilities
Unit ID: "ba80e6cb-86a4-4bb1-a0c5-8104365d523c" (kWh)
Quantity: From electricity bills, utility invoices, or smart meter data

No facility_fuel_id for electricity invoicesUnlike heat invoices, electricity invoices do not use facility_fuel_id. The emission factors are determined automatically based on the facility’s country (location-based) or supplier/custom emission factor (market-based).

Record electricity consumption at a facility (location-based calculation):

import requests
import os

headers = {
    "Authorization": f"Bearer {os.getenv('DCYCLE_API_KEY')}",
    "Content-Type": "application/json",
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    "x-user-id": os.getenv("DCYCLE_USER_ID"),
}

# Create invoice for electricity consumption (location-based)
# No supplier_id or custom_emission_factor_id needed - uses grid average EF
facility_id = "your-facility-uuid"

invoice_data = {
    "type": "electricity",
    "facility_percentages": [
        {
            "organization_id": os.getenv("DCYCLE_ORG_ID"),
            "facility_id": facility_id,
            "percentage": 1.0,  # 100% to this facility
        }
    ],
    "base_quantity": 10000,  # 10,000 kWh
    "unit_id": "ba80e6cb-86a4-4bb1-a0c5-8104365d523c",  # kWh
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "invoice_id": "ELEC-2024-001",
    "uploaded_by": os.getenv("DCYCLE_USER_ID"),
}

response = requests.post(
    "https://api.dcycle.io/api/v1/invoices",
    headers=headers,
    json=invoice_data,
)

invoice = response.json()
print(f"✅ Electricity invoice created: {invoice['id']}")
print(f"   Quantity: {invoice['quantity']} kWh")
print(f"   CO₂e (location-based): {invoice.get('co2e', 'Calculating...')} kg")

Utility Bill DataFor most accurate tracking, extract the following from your electricity bills:

kWh consumed: The actual energy consumption (not the cost)
Billing period: Start and end dates of the billing cycle
Supplier name: For market-based calculations

Step 3.2: Create an Electricity Invoice (Market-based - Spain)

For facilities in Spain, use supplier_id to enable market-based calculations with CNMC-published emission factors.

📋 Data Map: Electricity Invoice with Supplier (Spain)

Field	Type	Required	Description	Example
`type`	string	✅	Invoice type	`"electricity"`
`facility_id`	UUID	✅	Facility consuming the energy	`"abc-123-..."`
`base_quantity`	number	✅	Energy consumed (kWh)	`10000`
`unit_id`	UUID	✅	Unit (kWh)	`"ba80e6cb-..."`
`supplier_id`	UUID	✅	Electricity supplier (Spain only)	`"supplier-uuid"`
`start_date`	date	✅	Billing period start	`"2024-01-01"`
`end_date`	date	✅	Billing period end	`"2024-01-31"`
`invoice_id`	string	❌	Your reference number	`"ELEC-2024-001"`
`uploaded_by`	UUID	✅	User uploading	`"user-uuid"`

Where to get this data:

Supplier ID: GET /api/v1/suppliers?type=electricity - List electricity suppliers
Supplier-specific EFs: Automatically applied based on supplier selection
For Spain: Suppliers are linked to CNMC-published emission factors

# First, get available electricity suppliers (Spain)
suppliers = requests.get(
    "https://api.dcycle.io/api/v1/suppliers",
    headers=headers,
    params={"type": "electricity"},
).json()

# Find your electricity supplier (e.g., Iberdrola, Endesa, etc.)
my_supplier = next(
    (s for s in suppliers["items"] if "iberdrola" in s["name"].lower()),
    None
)

# Create invoice with supplier for market-based calculation (Spain)
invoice_data = {
    "type": "electricity",
    "facility_percentages": [
        {
            "organization_id": os.getenv("DCYCLE_ORG_ID"),
            "facility_id": facility_id,
            "percentage": 1.0,
        }
    ],
    "base_quantity": 10000,  # 10,000 kWh
    "unit_id": "ba80e6cb-86a4-4bb1-a0c5-8104365d523c",  # kWh
    "supplier_id": my_supplier["id"],  # Required for market-based in Spain
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "invoice_id": "ELEC-2024-002",
    "uploaded_by": os.getenv("DCYCLE_USER_ID"),
}

response = requests.post(
    "https://api.dcycle.io/api/v1/invoices",
    headers=headers,
    json=invoice_data,
)

invoice = response.json()
print(f"✅ Invoice with supplier created: {invoice['id']}")
print(f"   Supplier: {my_supplier['name']}")
print(f"   CO₂e (market-based): Based on {my_supplier['name']} emission factor")

Spain Market-based Emission FactorsFor Spanish facilities with linked suppliers, Dcycle uses emission factors published by CNMC:

Updated annually for each electricity retailer
Reflects the actual energy mix of each supplier
Renewable suppliers (100% green) will have 0 kg CO₂e/kWh

Step 3.3: Create an Electricity Invoice (Market-based - Outside Spain)

For facilities outside Spain, use custom_emission_factor_id to enable market-based calculations with your own emission factor.

📋 Data Map: Electricity Invoice with Custom EF (Non-Spain)

Field	Type	Required	Description	Example
`type`	string	✅	Invoice type	`"electricity"`
`facility_id`	UUID	✅	Facility consuming the energy	`"abc-123-..."`
`base_quantity`	number	✅	Energy consumed (kWh)	`10000`
`unit_id`	UUID	✅	Unit (kWh)	`"ba80e6cb-..."`
`custom_emission_factor_id`	UUID	✅	Your custom emission factor	`"custom-ef-uuid"`
`start_date`	date	✅	Billing period start	`"2024-01-01"`
`end_date`	date	✅	Billing period end	`"2024-01-31"`
`invoice_id`	string	❌	Your reference number	`"ELEC-2024-001"`
`uploaded_by`	UUID	✅	User uploading	`"user-uuid"`

Where to get this data:

Custom Emission Factor ID: Create via POST /api/v1/custom_emission_factors or use existing ones from GET /api/v1/custom_emission_factors
Custom EF value: Obtain from your electricity supplier’s disclosure or certificates (e.g., Guarantees of Origin)

# Create invoice with custom emission factor for market-based calculation (Non-Spain)
invoice_data = {
    "type": "electricity",
    "facility_percentages": [
        {
            "organization_id": os.getenv("DCYCLE_ORG_ID"),
            "facility_id": facility_id,  # Facility outside Spain
            "percentage": 1.0,
        }
    ],
    "base_quantity": 10000,  # 10,000 kWh
    "unit_id": "ba80e6cb-86a4-4bb1-a0c5-8104365d523c",  # kWh
    "custom_emission_factor_id": "your-custom-ef-uuid",  # Required for market-based outside Spain
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "invoice_id": "ELEC-2024-003",
    "uploaded_by": os.getenv("DCYCLE_USER_ID"),
}

response = requests.post(
    "https://api.dcycle.io/api/v1/invoices",
    headers=headers,
    json=invoice_data,
)

invoice = response.json()
print(f"✅ Invoice with custom EF created: {invoice['id']}")
print(f"   CO₂e (market-based): Based on custom emission factor")

Creating Custom Emission FactorsTo create a custom emission factor for your electricity supplier:

Obtain the emission factor from your supplier’s disclosure or certificate
Create the custom EF via POST /api/v1/custom_emission_factors
Use the returned ID in your electricity invoices

This is useful for:

Suppliers with Guarantees of Origin (GOs)
Power Purchase Agreements (PPAs)
Renewable Energy Certificates (RECs)

Step 3.4: Track District Heating and Cooling

📋 Data Map: District Heating/Cooling

Field	Type	Required	Description	Example
`type`	string	✅	Invoice type	`"district_heating"` or `"district_cooling"`
`facility_id`	UUID	✅	Facility receiving the service	`"abc-123-..."`
`facility_fuel_id`	UUID	✅	Heating/cooling fuel type	`"heat-456-..."`
`base_quantity`	number	✅	Energy consumed	`5000`
`unit_id`	UUID	✅	Unit (kWh or MJ)	`"ba80e6cb-..."`
`start_date`	date	✅	Service period start	`"2024-01-01"`
`end_date`	date	✅	Service period end	`"2024-03-31"`
`invoice_id`	string	✅	Your reference	`"HEAT-2024-Q1"`
`uploaded_by`	UUID	✅	User uploading	`"user-uuid"`
`supplier_id`	UUID	❌	District service provider	`"supplier-uuid"`

Where to get this data:

Heating bills: From district heating provider
Cooling bills: From district cooling provider
Energy units: Typically kWh, MJ, or GJ

District heating and cooling are purchased energy services that fall under Scope 2:

# Create invoice for district heating
heating_data = {
    "type": "district_heating",  # or "district_cooling"
    "facility_percentages": [
        {
            "organization_id": os.getenv("DCYCLE_ORG_ID"),
            "facility_id": facility_id,
            "percentage": 1.0,
        }
    ],
    "base_quantity": 5000,  # 5,000 kWh of heat
    "unit_id": "ba80e6cb-86a4-4bb1-a0c5-8104365d523c",  # kWh
    "facility_fuel_id": heating_fuel_id,  # District heating fuel
    "start_date": "2024-01-01",
    "end_date": "2024-03-31",
    "invoice_id": "HEAT-2024-Q1",
    "uploaded_by": os.getenv("DCYCLE_USER_ID"),
}

response = requests.post(
    "https://api.dcycle.io/api/v1/invoices",
    headers=headers,
    json=heating_data,
)

print(f"✅ District heating recorded: {response.json()['id']}")

Scope 2 vs Scope 1 Heat

Scope 2: Purchased heat/steam/cooling from external providers (district services)
Scope 1: Heat generated on-site from your own combustion (use type: "heat" invoices)

Make sure to classify correctly based on whether energy is purchased or generated on-site.

Automatic Data Import (Spain)

Datadis IntegrationFor facilities in Spain, Dcycle offers automatic electricity data import via Datadis (Sistema de Intercambio de Datos de Medida). This eliminates manual data entry for electricity consumption.To enable, follow these tutorial: How to connect Datadis account to Dcycle

Querying Scope 2 Emissions

Get Electricity Emissions by Facility

# Query total impacts for electricity
response = requests.get(
    "https://api.dcycle.io/api/v1/total_impacts",
    headers=headers,
    params={
        "organization_id": os.getenv("DCYCLE_ORG_ID"),
        "category": "electricity_generation",  # Scope 2 electricity
        "start_date": "2024-01-01",
        "end_date": "2024-12-31",
    },
).json()

print(f"📊 Scope 2 Electricity Emissions:")
total_co2e = 0
for impact in response["items"]:
    print(f"   Facility: {impact['facility_name']}")
    print(f"   CO₂e: {impact['co2e']} kg")
    total_co2e += impact['co2e']

print(f"\n   Total Scope 2: {total_co2e} kg CO₂e")

Get Both Location and Market-based Results

# For GHG Protocol compliant reporting, query both methods
# Location-based is stored in standard total_impacts
# Market-based is stored separately when supplier is specified

print("📊 Scope 2 Dual Reporting:")
print(f"   Location-based: {location_based_total} kg CO₂e")
print(f"   Market-based: {market_based_total} kg CO₂e")

Best Practice: Track All Energy SourcesFor complete Scope 2 accounting:

Electricity: All purchased grid electricity at all facilities
Renewable certificates: Track green energy purchases separately
District heating/cooling: Any purchased heat or cooling services
Steam: Industrial steam purchases from third parties

Use consistent units (kWh) across all energy types for easier aggregation.

Understanding Your Results

Why Location-based ≠ Market-based?

The two values represent different things:

Location-based reflects the average grid emissions where you consume energy
Market-based reflects your contractual arrangements with suppliers

Common scenarios:

Market > Location: Your supplier has a higher carbon intensity than the grid average
Market < Location: Your supplier uses more renewables than the grid average
Market = 0: You have 100% renewable electricity contracts

Reducing Scope 2 Emissions

Strategies to reduce Scope 2 emissions:

Switch suppliers: Choose suppliers with lower emission factors
Purchase green tariffs: 100% renewable electricity contracts
Install on-site renewables: Solar panels, wind (moves to Scope 1 or carbon-neutral)
Energy efficiency: Reduce overall consumption
PPAs: Power Purchase Agreements with renewable generators

Renewable Energy and Market-based

For renewable energy to count as zero emissions in market-based:

Must have contractual proof (certificates, PPA, green tariff)
Certificate must match consumption location and timing
Guarantees of Origin (GOs) or RECs must be retired on your behalf

Dcycle tracks supplier-reported renewable percentages automatically for supported suppliers.

Calculate Emissions

ISO 14064

GHG Protocol

Use Case Tutorials

Advanced

Automation & AI

Step 3 - Calculate Scope 2 Emissions

Understanding Scope 2 Emissions

Prerequisites

Calculating Electricity Emissions

Emission Sources Covered

Calculation Methods: Location-based vs Market-based

Data Flow

Step 3.1: Create an Electricity Invoice (Location-based)

Step 3.2: Create an Electricity Invoice (Market-based - Spain)

Step 3.3: Create an Electricity Invoice (Market-based - Outside Spain)

Step 3.4: Track District Heating and Cooling

Automatic Data Import (Spain)

Querying Scope 2 Emissions

Get Electricity Emissions by Facility

Get Both Location and Market-based Results

Understanding Your Results

Calculate Emissions

ISO 14064

GHG Protocol

Use Case Tutorials

Advanced

Automation & AI

​Understanding Scope 2 Emissions

​Prerequisites

​Calculating Electricity Emissions

​Emission Sources Covered

​Calculation Methods: Location-based vs Market-based

​Data Flow

​Step 3.1: Create an Electricity Invoice (Location-based)

​Step 3.2: Create an Electricity Invoice (Market-based - Spain)

​Step 3.3: Create an Electricity Invoice (Market-based - Outside Spain)

​Step 3.4: Track District Heating and Cooling

​Automatic Data Import (Spain)

​Querying Scope 2 Emissions

​Get Electricity Emissions by Facility

​Get Both Location and Market-based Results

​Understanding Your Results

Understanding Scope 2 Emissions

Prerequisites

Calculating Electricity Emissions

Emission Sources Covered

Calculation Methods: Location-based vs Market-based

Data Flow

Step 3.1: Create an Electricity Invoice (Location-based)

Step 3.2: Create an Electricity Invoice (Market-based - Spain)

Step 3.3: Create an Electricity Invoice (Market-based - Outside Spain)

Step 3.4: Track District Heating and Cooling

Automatic Data Import (Spain)

Querying Scope 2 Emissions

Get Electricity Emissions by Facility

Get Both Location and Market-based Results

Understanding Your Results