Step 2 - Calculate Scope 1 Emissions

Understanding Scope 1 Emissions

Scope 1 emissions are direct greenhouse gas emissions from sources owned or controlled by your organization. According to the GHG Protocol Corporate Standard, these include:

Stationary combustion: Burning fuels in boilers, furnaces, heaters, and other fixed equipment
Mobile combustion: Burning fuels in company-owned or controlled vehicles
Process emissions: Emissions from industrial processes (e.g., chemical reactions)
Fugitive emissions: Intentional or unintentional releases (e.g., refrigerant leaks, CH₄ from wastewater treatment)

┌─────────────────────────────────────────────────────────────────────────────┐
│                           SCOPE 1: Direct Emissions                         │
├─────────────────────┬─────────────────────┬─────────────────────────────────┤
│  Stationary         │  Mobile             │  Process & Fugitive             │
│  Combustion         │  Combustion         │  Emissions                      │
├─────────────────────┼─────────────────────┼─────────────────────────────────┤
│  • Boilers          │  • Company cars     │  • Industrial processes         │
│  • Furnaces         │  • Trucks           │  • Refrigerant leaks            │
│  • Generators       │  • Forklifts        │  • Wastewater treatment CH₄     │
│  • Heaters          │  • Company fleet    │  • Natural gas leaks            │
└─────────────────────┴─────────────────────┴─────────────────────────────────┘

GHG Protocol Calculation FormulaFor most Scope 1 sources, emissions are calculated using:CO₂e = Activity Data × Emission Factor × GWPWhere:

Activity Data: Quantity of fuel consumed (liters, kg, m³, kWh)
Emission Factor: kg CO₂, CH₄, or N₂O per unit of fuel
GWP: Global Warming Potential to convert to CO₂ equivalent

Prerequisites

Before starting, ensure you have:

Dcycle API credentials (get them here)
At least one facility configured in your organization
Access to your facility data: fuel consumption records, stationary combustion equipment details, and fleet information

Using the Dcycle App?You can also manage your carbon footprint through our web interface:

Create facilities - Set up your emission sources
Upload invoices - Track fuel consumption
Manage vehicles - Fleet management and consumption tracking

Calculating Stationary Combustion

Stationary combustion emissions come from burning fuels in fixed equipment at your facilities. In Dcycle, these are tracked through invoices linked to facility fuels.

Emission Sources Covered

Source Type	Invoice Type	Examples
Combustion (heat)	`heat`	Natural gas boilers, diesel generators, propane heaters
Recharges	`recharge`	Refrigerant refills, fire suppression systems
Process emissions	`process`	Industrial furnaces, VOCs
Waste water treatment	Special endpoint	CH₄ and N₂O from wastewater facilities

Calculation Methods by Country

Dcycle automatically applies the appropriate calculation methodology based on your facility’s country:

Spain (MITECO)
Other Countries (GHG Protocol)

For facilities located in Spain, Dcycle uses emission factors from MITECO (Ministerio para la Transición Ecológica y el Reto Demográfico).

Facility (ES) → Invoice → MITECO Emission Factors → CO₂e
      ↓              ↓                ↓                ↓
  Country: ES    Fuel type     Spanish-specific    Compliant with
                 + quantity    factors by year     Spanish regulations

Key characteristics:

Emission factors specific to Spain, updated annually
Fuel types mapped to MITECO categories (e.g., natural_gas, gas_oil_b, lpg)
Required for Spanish regulatory compliance (ISO 14064, EINF)
Includes factors for CO₂, CH₄, and N₂O

Access MITECO emission factors here.

Emission Factor Sources - Spain (MITECO)

For Spanish facilities, Dcycle uses emission factors from:

MITECO (Ministerio para la Transición Ecológica y el Reto Demográfico)
Updated annually with Spanish-specific factors
Source: Factores de emisión

Factors are automatically selected based on:

Fuel type (mapped to MITECO categories)
Unit of measurement
Invoice year

Calculation Details - Spain (MITECO)

For Spanish facilities, stationary combustion emissions are calculated as:CO₂e = Fuel Quantity × (EF_CO₂ × GWP_CO₂ + EF_CH₄ × GWP_CH₄ + EF_N₂O × GWP_N₂O)Where:

Fuel Quantity: Amount consumed (liters, m³, kg, kWh)
EF_XXX: MITECO emission factor for the specific GHG gas (CO₂, CH₄, N₂O) and fuel, unit, and year
GWP_XXX: Global Warming Potential for the specific GHG gas (CO₂, CH₄, N₂O) (IPCC AR6 GWP values)

Example (Natural Gas):

5,000 KWH × (0.182 kg CO₂/KWH x 1 + 0.000016 kg CH₄/KWH x 27.9 + 0.000000 kg N₂O/KWH x 273) = 912.23 kg CO₂e

For facilities in any other country, Dcycle uses emission factors from the IPCC/GHG Protocol database.

Facility (non-ES) → Invoice → IPCC Emission Factors → CO₂e
      ↓                 ↓                ↓                ↓
  Country: XX       Fuel type     Global default      GHG Protocol
                    + quantity    factors (IPCC)      compliant

Key characteristics:

IPCC-based emission factors (globally recognized)
Fuel types follow GHG Protocol naming conventions
Compatible with international reporting standards
Includes Net Calorific Value (NCV) calculations

Access GHG Protocol emission factors here.

Emission Factor Sources - Other Countries (GHG Protocol)

For non-Spanish facilities, Dcycle uses emission factors from:

IPCC (Intergovernmental Panel on Climate Change)
GHG Protocol Stationary Combustion Tool
Source: GHG Protocol Calculation Tools

Factors are automatically selected based on:

Fuel type (GHG Protocol naming conventions)
Net Calorific Value (NCV) of the fuel
Country-specific adjustments where available

Calculation Details - Other Countries (GHG Protocol)

For non-Spanish facilities, stationary combustion emissions follow the GHG Protocol methodology:CO₂e = Fuel Quantity × Density × NCV × EF_IPCC × GWPWhere:

Fuel Quantity: Amount consumed (converted to mass in Gg)
Density: Density of the fuel
NCV: Net Calorific Value (TJ/Gg) - energy content per unit mass
EF_IPCC: IPCC emission factor (kg gas/TJ)
GWP_XXX: Global Warming Potential for the specific GHG gas (CO₂, CH₄, N₂O) (IPCC AR6 GWP values)

The calculation process:

Convert fuel quantity to energy (TJ) using NCV
Apply emission factors for CO₂, CH₄, and N₂O
Convert each gas to CO₂e using GWP factors
Sum all gases for total CO₂e

Example (Natural Gas):

Step 1: 5,000 m³ × 0.7 kg/m³ (density) *0.001 (to convert to Gg)→ mass in Gg
Step 2: mass × 48.0 TJ/Gg (NCV) → energy in TJ
Step 3: energy × 56,100 kg CO₂/TJ → CO₂ emissions
Step 4: Add CH₄ and N₂O contributions and convert to CO₂e using GWP factors → total CO₂e

Automatic Method SelectionYou don’t need to specify which calculation method to use. Dcycle automatically detects the facility’s country and applies the correct emission factors:

country: "ES" → MITECO factors
Any other country → GHG Protocol/IPCC factors

What you’ll track:

Facility Setup → Invoice Creation → Emissions Calculation
      ↓                ↓                      ↓
  Facility config   Fuel consumption    CO2e per invoice
  (with country)    records (invoices)  (method auto-selected)

Data Flow

Set Up Facilities

Configure your facilities and link them to fuel types

Automatic Method Selection

Dcycle detects the facility country and applies MITECO (Spain) or GHG Protocol (other) emission factors

Create Invoices

Record fuel consumption, recharges, or process emissions via invoices

Calculate Emissions

CO₂e emissions are calculated using the appropriate country-specific factors

Generate Reports

View emissions by facility, fuel type, or period

Step 2.1: Create a Fuel Consumption Invoice

📋 Data Map: Fuel Consumption Invoice

Field	Type	Required	Description	Example
`type`	string	✅	Invoice type	`"heat"`
`facility_id`	UUID	✅	Target facility	`"abc-123-..."`
`facility_fuel_id`	UUID	✅	Fuel type for this facility	`"def-456-..."`
`base_quantity`	number	✅	Amount of fuel consumed	`5000`
`unit_id`	UUID	✅	Unit of measurement	`"2a09be22-..."` (m³)
`start_date`	date	✅	Consumption period start	`"2024-01-01"`
`end_date`	date	✅	Consumption period end	`"2024-01-31"`
`invoice_id`	string	✅	Your internal reference	`"INV-2024-001"`
`uploaded_by`	UUID	✅	User uploading the data	`"user-uuid"`
`custom_emission_factor_id`	UUID	❌	Custom EF override	`"custom-ef-uuid"`

Where to get this data:

Facility ID: From Step 1 (company structure setup) or GET /api/v1/facilities
Facility Fuel ID: GET /api/v1/facility_fuels/{facility_id}
Unit ID: GET /api/v1/units
Quantity: From utility bills, fuel purchase records, or meter readings

Record fuel consumption at a facility by creating an invoice:

import requests
import os
from datetime import datetime, timedelta

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"),
}

# Get facility fuels for your facility
facility_id = "your-facility-uuid"
facility_fuels = requests.get(
    f"https://api.dcycle.io/v1/facility_fuels/{facility_id}",
    headers=headers,
).json()

# Find the natural gas fuel option
natural_gas_fuel = next(
    (ff for ff in facility_fuels if "natural gas" in ff["fuel_name"].lower()),
    None
)

# Create invoice for natural gas consumption
invoice_data = {
    "type": "heat",  # Stationary combustion
    "facility_percentages": [
        {
            "organization_id": os.getenv("DCYCLE_ORG_ID"),
            "facility_id": facility_id,
            "percentage": 1.0,  # 100% to this facility
        }
    ],
    "base_quantity": 5000,  # 5,000 m³ of natural gas
    "unit_id": "2a09be22-a6e2-4317-a680-94aaa1048765",  # m³
    "facility_fuel_id": natural_gas_fuel["id"],
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "invoice_id": "INV-2024-001",
    "uploaded_by": os.getenv("DCYCLE_USER_ID"),
    # Optional: apply a custom emission factor
    # "custom_emission_factor_id": "your-custom-ef-id",
}

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

invoice = response.json()
print(f"✅ Invoice created: {invoice['id']}")
print(f"   Quantity: {invoice['quantity']} m³")
print(f"   CO₂e: {invoice.get('co2e', 'Calculating...')} kg")

Use Custom Emission FactorsIf you want to use custom emission factors, include custom_emission_factor_id in the invoice payload. See Custom Emission Factors for how to create and apply them.

const axios = require('axios');

const headers = {
  Authorization: `Bearer ${process.env.DCYCLE_API_KEY}`,
  'Content-Type': 'application/json',
  'x-organization-id': process.env.DCYCLE_ORG_ID,
  'x-user-id': process.env.DCYCLE_USER_ID,
};

// Get facility fuels for your facility
const facilityId = 'your-facility-uuid';
const facilityFuelsResponse = await axios.get(
  `https://api.dcycle.io/v1/facility_fuels/${facilityId}`,
  { headers }
);
const facilityFuels = facilityFuelsResponse.data;

// Find the natural gas fuel option
const naturalGasFuel = facilityFuels.find(
  ff => ff.fuel_name.toLowerCase().includes('natural gas')
);

// Create invoice for natural gas consumption
const invoiceData = {
  type: 'heat', // Stationary combustion
  facility_percentages: [
    {
      organization_id: process.env.DCYCLE_ORG_ID,
      facility_id: facilityId,
      percentage: 1.0, // 100% to this facility
    },
  ],
  base_quantity: 5000, // 5,000 m³ of natural gas
  unit_id: '2a09be22-a6e2-4317-a680-94aaa1048765', // m³
  facility_fuel_id: naturalGasFuel.id,
  start_date: '2024-01-01',
  end_date: '2024-01-31',
  invoice_id: 'INV-2024-001',
  uploaded_by: process.env.DCYCLE_USER_ID,
};

const response = await axios.post(
  'https://api.dcycle.io/v1/invoices',
  invoiceData,
  { headers }
);

const invoice = response.data;
console.log(`✅ Invoice created: ${invoice.id}`);
console.log(`   Quantity: ${invoice.quantity} m³`);
console.log(`   CO₂e: ${invoice.co2e || 'Calculating...'} kg`);

Step 2.2: Track Refrigerant Recharges

📋 Data Map: Refrigerant Recharges

Field	Type	Required	Description	Example
`type`	string	✅	Invoice type	`"recharge"`
`facility_id`	UUID	✅	Facility with the equipment	`"abc-123-..."`
`facility_fuel_id`	UUID	✅	Refrigerant type (R-410A, R-134a, etc.)	`"ref-456-..."`
`base_quantity`	number	✅	Amount recharged (= amount leaked)	`15`
`unit_id`	UUID	✅	Unit (typically kg)	`"61743a63-..."` (kg)
`start_date`	date	✅	Recharge date	`"2024-03-15"`
`end_date`	date	✅	Recharge date (same as start)	`"2024-03-15"`
`invoice_id`	string	✅	Service invoice reference	`"RECHARGE-2024-001"`
`uploaded_by`	UUID	✅	User uploading	`"user-uuid"`
`custom_emission_factor_id`	UUID	❌	Custom EF override	`"custom-ef-uuid"`

Where to get this data:

Refrigerant type: From HVAC maintenance records or service invoices
Quantity: From recharge receipts (amount refilled = amount leaked)
Equipment register: Maintain a list of all cooling equipment and their refrigerant types

Refrigerant leaks (HFCs, PFCs) are fugitive emissions and often significant for organizations with cooling systems:

# Create invoice for refrigerant recharge (fugitive emissions)
recharge_data = {
    "type": "recharge",
    "facility_percentages": [
        {
            "organization_id": os.getenv("DCYCLE_ORG_ID"),
            "facility_id": facility_id,
            "percentage": 1.0,
        }
    ],
    "base_quantity": 15,  # 15 kg of R-410A refrigerant
    "unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",  # kg
    "facility_fuel_id": refrigerant_fuel_id,  # R-410A fuel ID
    "start_date": "2024-03-15",
    "end_date": "2024-03-15",
    "invoice_id": "RECHARGE-2024-001",
    "uploaded_by": os.getenv("DCYCLE_USER_ID"),
    # "custom_emission_factor_id": "your-custom-ef-id",
}

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

print(f"✅ Recharge recorded: {response.json()['id']}")
print(f"   R-410A has GWP of ~2,088 - high impact!")

Custom Factors for RechargesUse custom_emission_factor_id when you want to apply custom emissions data for a refrigerant. Learn how in the Custom Emission Factors guide.

High-GWP RefrigerantsSome refrigerants have extremely high Global Warming Potentials:

R-410A: GWP = 2,088
R-404A: GWP = 3,922
R-134a: GWP = 1,430

Even small leaks can represent a significant portion of your Scope 1 footprint. Track all recharges carefully.

Step 2.3: Track Process Emissions

📋 Data Map: Process Emissions

Field	Type	Required	Description	Example
`type`	string	✅	Invoice type	`"process"`
`facility_id`	UUID	✅	Facility with the process	`"abc-123-..."`
`facility_fuel_id`	UUID	✅	Process source/fuel type	`"proc-456-..."`
`base_quantity`	number	✅	Emission quantity	`250`
`unit_id`	UUID	✅	Unit (typically kg)	`"61743a63-..."` (kg)
`start_date`	date	✅	Period start	`"2024-01-01"`
`end_date`	date	✅	Period end	`"2024-03-31"`
`invoice_id`	string	✅	Internal reference	`"PROCESS-2024-Q1"`
`uploaded_by`	UUID	✅	User uploading	`"user-uuid"`
`custom_emission_factor_id`	UUID	⚠️	Custom EF (often required)	`"custom-ef-uuid"`

Where to get this data:

Process type: From environmental permits, process flow diagrams
Quantity: From production records, mass balance calculations, or direct measurements
Custom EF: Industry-specific factors from permits, sector guidelines, or IPCC

Process emissions arise from industrial activities where the emissions are not from fuel combustion, but from chemical or physical transformations. Common examples include:

Chemical manufacturing: CO₂ from calcination (e.g., cement, lime production)
Metal production: CO₂ from reduction processes
Volatile organic compounds (VOCs): Emissions from solvents, coatings, and industrial cleaning
Industrial furnaces: Non-combustion emissions from high-temperature processes

Process emissions are tracked as invoices with type: "process":

# Create invoice for process emissions (e.g., VOC from painting operations)
process_data = {
    "type": "process",
    "facility_percentages": [
        {
            "organization_id": os.getenv("DCYCLE_ORG_ID"),
            "facility_id": facility_id,
            "percentage": 1.0,
        }
    ],
    "base_quantity": 250,  # 250 kg of VOC emissions
    "unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",  # kg
    "facility_fuel_id": process_fuel_id,  # Fuel/source associated with the process
    "start_date": "2024-01-01",
    "end_date": "2024-03-31",
    "invoice_id": "PROCESS-2024-Q1",
    "uploaded_by": os.getenv("DCYCLE_USER_ID"),
    # "custom_emission_factor_id": "your-custom-ef-id",
}

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

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

Use Custom Emission Factors for Process EmissionsProcess emissions often require facility-specific or industry-specific emission factors. Use custom_emission_factor_id to apply factors from your environmental permits or industry calculations. See Custom Emission Factors for setup instructions.

When to Use Process vs. Heat Invoices

Use type: "heat" when emissions come from burning fuel (combustion)
Use type: "process" when emissions come from chemical/physical transformations not related to combustion

Example: A cement plant would use heat for fuel burned in kilns, but process for CO₂ released from limestone calcination.

Step 2.4: Track Waste Water Treatment Emissions

📋 Data Map: Waste Water Treatment

Field	Type	Required	Description	Example
`facility_id`	UUID	✅	WWT facility	`"wwt-123-..."`
`name`	string	✅	Record identifier	`"WWT-2024-01-01"`
`measurement_date`	date	✅	Measurement date	`"2024-01-01"`
`m3_water_in`	number	✅	Daily influent volume (m³)	`10000`
`m3_water_out`	number	✅	Daily effluent volume (m³)	`9500`
`kg_bod_per_m3_wwt_line`	number	✅	BOD concentration in treatment	`0.25`
`kg_n_per_m3_wwt_line`	number	✅	Nitrogen concentration	`0.04`
`kg_sludge`	number	✅	Sludge produced (kg)	`500`
`kg_bod_per_kg_sludge_line`	number	✅	BOD in sludge	`0.6`
`kg_bod_per_m3_wwd_line`	number	✅	BOD in discharge	`0.02`
`kg_n_per_m3_wwd_line`	number	✅	Nitrogen in discharge	`0.01`
`m3_biogas_engine`	number	❌	Biogas to engine (m³)	`200`
`m3_biogas_flare`	number	❌	Biogas flared (m³)	`50`
`m3_biogas_boiler`	number	❌	Biogas to boiler (m³)	`100`
`st`	number	❌	Solids content	`0.25`
`methane`	number	❌	Methane content in biogas	`0.65`

Where to get this data:

Flow data: SCADA systems, flow meters at inlet/outlet
BOD/Nitrogen: Laboratory analyses, online sensors
Sludge: Weighing systems, sludge removal records
Biogas: Gas meters on digesters, engines, flares

Wastewater treatment facilities generate CH₄ (methane) and N₂O (nitrous oxide) emissions through biological processes. Dcycle provides a specialized bulk upload endpoint:

import requests
import os
from datetime import date, timedelta

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"),
}

# Prepare daily waste water treatment data
daily_data = []
base_date = date(2024, 1, 1)

for i in range(31):  # January 2024
    measurement_date = base_date + timedelta(days=i)
    daily_data.append({
        "name": f"WWT-{measurement_date.isoformat()}",
        "measurement_date": measurement_date.isoformat(),
        "m3_water_in": 10000 + (i * 100),  # Daily influent (m³)
        "m3_water_out": 9500 + (i * 95),   # Daily effluent (m³)
        "kg_bod_per_m3_wwt_line": 0.25,    # BOD concentration
        "kg_n_per_m3_wwt_line": 0.04,      # Nitrogen concentration
        "kg_sludge": 500 + (i * 10),       # Sludge produced (kg)
        "kg_bod_per_kg_sludge_line": 0.6,
        "kg_bod_per_m3_wwd_line": 0.02,
        "kg_n_per_m3_wwd_line": 0.01,
        "m3_biogas_engine": 200,           # Biogas to engine (m³)
        "m3_biogas_flare": 50,             # Biogas flared (m³)
        "m3_biogas_boiler": 100,           # Biogas to boiler (m³)
        "st": 0.25,                        # Solids content
        "methane": 0.65,                   # Methane content in biogas
    })

wwt_data = {
    "facility_id": "your-wwt-facility-uuid",
    "daily_waste_water_treatment_data": daily_data,
}

response = requests.post(
    "https://api.dcycle.io/v1/bulk/waste_water_treatments",
    headers=headers,
    json=wwt_data,
)

wwt_records = response.json()
print(f"✅ Created {len(wwt_records)} waste water treatment records")
print(f"   Emissions calculated from CH₄ and N₂O")

Waste Water Treatment CalculationsDcycle calculates emissions from:

CH₄ from anaerobic treatment: Based on BOD removal and MCF (Methane Correction Factor)
N₂O from biological processes: Based on nitrogen load and EF
Biogas combustion: CO₂ from burning recovered biogas (often biogenic)

The endpoint handles data imputation for missing values using moving averages.

Calculating Mobile Combustion

Mobile combustion emissions come from company-owned or controlled vehicles. In Dcycle, these are tracked through vehicles and vehicle consumptions.

Prefer using the Dcycle App?If you want to manage your fleet through our web interface instead of the API, check out these guides:

What you’ll track:

Vehicle Registration → Fuel Consumption → Emissions Calculation
      ↓                      ↓                    ↓
  Fleet database      Monthly records        CO2e per vehicle

Supported Units for Vehicle Consumption

This part of the documentation is still in progress.

Emission Factor Sources

Dcycle uses country-specific emission factors from:

DEFRA (UK Department for Environment, Food & Rural Affairs) Comming soon!
MITECO (Spanish Ministry for Ecological Transition)

Factors are automatically selected based on vehicle country and fuel type.

Calculation Details

Mobile combustion emissions are calculated as:CO₂e = Fuel Quantity × (EF_CO₂ × GWP_CO₂ + EF_CH₄ × GWP_CH₄ + EF_N₂O × GWP_N₂O)Where emission factors (EF) are specific to:

Fuel type (diesel, petrol, LPG, etc.)
Vehicle type (passenger car, light truck, heavy truck)
Country (regional emission factors)
Unit (liters, kilometers, etc.)

Data Flow

Add all company vehicles to Dcycle

Track Fuel Consumption

Upload fuel purchases (manually or from fuel cards)

Calculate Emissions

Dcycle automatically calculates CO2e emissions

Generate Reports

View emissions by vehicle, driver, or period

Step 2.5: Create a Vehicle

📋 Data Map: Vehicle Registration

Field	Type	Required	Description	Example
`name`	string	✅	Vehicle identifier	`"Delivery Truck 01"`
`type`	string	✅	Vehicle category	`"truck"`, `"car"`, `"van"`
`license_plate`	string	✅	License plate number	`"1234ABC"`
`country`	string	✅	Registration country (ISO)	`"ES"`, `"FR"`, `"PT"`
`vehicle_fuel_id`	UUID	✅	Fuel type	`"diesel-uuid"`
`ownership`	string	✅	Ownership type	`"owned"` or `"rented"`

Where to get this data:

Vehicle details: Fleet management system, vehicle registration documents
Fuel type: Vehicle specifications, fuel cards
Vehicle fuel ID: GET /api/v1/vehicle_fuels
Vehicle type: GET /api/v1/unknown_vehicles (for generic vehicle types)

First, register your company vehicle:

Using the Dcycle App?You can also register vehicles through our web interface:

For known vehicles: Create vehicles automatically by entering license plate (works in Spain, Portugal, France)
For any vehicle: Create vehicles manually with custom specifications

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"),
}

# Get available vehicle fuels
vehicle_fuels = requests.get(
    "https://api.dcycle.io/v1/vehicle_fuels",
    headers=headers,
).json()

diesel_fuel = next(
    (vf for vf in vehicle_fuels["items"] if "diesel" in vf["name"].lower()),
    None
)

# Get vehicles (vehicle types)
vehicle_types = requests.get(
    "https://api.dcycle.io/v1/unknown_vehicles",
    headers=headers,
).json()

medium_truck = next(
    (
        vt
        for vt in vehicle_types["items"]
        if "medium" in vt["name"].lower() and "truck" in vt["name"].lower()
    ),
    None
)

# Create vehicle via bulk CSV upload (get presigned URL)
bulk_upload = requests.post(
    "https://api.dcycle.io/v1/vehicles/bulk/csv",
    headers=headers,
    json={"file_name": "company_vehicles.csv"},
).json()

print(f"✅ Upload URL generated: {bulk_upload['upload_url'][:50]}...")
print(f"   Upload your CSV with columns:")
print(f"   name, type, license_plate, country, vehicle_fuel_id, ownership, unknown_vehicle_id")

const axios = require('axios');

const headers = {
  Authorization: `Bearer ${process.env.DCYCLE_API_KEY}`,
  'Content-Type': 'application/json',
  'x-organization-id': process.env.DCYCLE_ORG_ID,
  'x-user-id': process.env.DCYCLE_USER_ID,
};

// Get available vehicle fuels
const vehicleFuelsResponse = await axios.get(
  'https://api.dcycle.io/v1/vehicle_fuels',
  { headers }
);
const vehicleFuels = vehicleFuelsResponse.data;

const dieselFuel = vehicleFuels.items.find(
  vf => vf.name.toLowerCase().includes('diesel')
);

// Get vehicles (vehicle types)
const vehicleTypesResponse = await axios.get(
  'https://api.dcycle.io/v1/unknown_vehicles',
  { headers }
);
const vehicleTypes = vehicleTypesResponse.data;

const mediumTruck = vehicleTypes.items.find(
  vt =>
    vt.name.toLowerCase().includes('medium') &&
    vt.name.toLowerCase().includes('truck')
);

// Create vehicle via bulk CSV upload (get presigned URL)
const bulkUploadResponse = await axios.post(
  'https://api.dcycle.io/v1/vehicles/bulk/csv',
  { file_name: 'company_vehicles.csv' },
  { headers }
);

const bulkUpload = bulkUploadResponse.data;
console.log(`✅ Upload URL generated: ${bulkUpload.upload_url.slice(0, 50)}...`);
console.log('   Upload your CSV with columns:');
console.log('   name, type, license_plate, country, vehicle_fuel_id, ownership, unknown_vehicle_id');

Step 2.6: Record Vehicle Fuel Consumption

📋 Data Map: Vehicle Fuel Consumption

Field	Type	Required	Description	Example
`vehicle_license_plate`	string	✅	Vehicle identifier	`"1234ABC"`
`start_date_recharge`	date	✅	Consumption period start	`"2024-01-01"`
`end_date_recharge`	date	✅	Consumption period end	`"2024-01-31"`
`quantity`	number	✅	Fuel amount	`450`
`unit_measure`	string	✅	Unit of measurement	`"l"`, `"km"`
`organization_id`	UUID	✅	Organization identifier	`"org-uuid"`
`description`	string	❌	Optional note	`"January fuel"`

Supported units:

Volume: l (liters) - for fuel purchases
Distance: km (kilometers) - when using average consumption

Where to get this data:

Fuel cards: Automatic reports from fuel card providers
Fuel receipts: Manual collection of fuel purchase receipts
Odometer readings: For distance-based calculations
Charging records: For electric vehicles (charging station data)

Once vehicles are created, track their fuel consumption:

# Get presigned URL for bulk vehicle consumption upload
consumption_upload = requests.post(
    "https://api.dcycle.io/v1/vehicle_consumptions/bulk/csv",
    headers=headers,
    json={"file_name": "vehicle_consumptions_q1_2024.csv"},
).json()

print(f"✅ Upload URL generated for consumptions")
print(f"   CSV columns required:")
print(f"   description(optional), vehicle_license_plate, start_date_recharge,")
print(f"   end_date_recharge, quantity, unit_measure, organization_id")

CSV Format for Vehicle Consumptions

description(optional),vehicle_license_plate,start_date_recharge,end_date_recharge,quantity,unit_measure,organization_id
January fuel,1234ABC,2024-01-01,2024-01-31,450,l,your-org-uuid
February fuel,1234ABC,2024-02-01,2024-02-29,420,l,your-org-uuid
Q1 fuel,5678XYZ,2024-01-01,2024-03-31,1250,l,your-org-uuid

Query Vehicle Consumptions

# Get vehicle consumptions for a specific vehicle
vehicle_id = "your-vehicle-uuid"

consumptions = requests.get(
    f"https://api.dcycle.io/v1/vehicle_consumptions/vehicle/{vehicle_id}",
    headers=headers,
    params={
        "page": 1,
        "size": 50,
        "start_date": 1704067200,  # 2024-01-01 timestamp
        "end_date": 1711929600,    # 2024-04-01 timestamp
    },
).json()

print(f"📊 Vehicle Consumptions:")
for consumption in consumptions["items"]:
    print(f"   {consumption['start_date']} - {consumption['end_date']}")
    print(f"   Quantity: {consumption['quantity']} {consumption['unit_name']}")
    print(f"   CO₂e: {consumption.get('co2e', 'N/A')} kg")
    print()

Best Practice: Track All Company VehiclesFor complete Scope 1 accounting:

Owned vehicles: Full emissions count toward Scope 1
Leased vehicles (operational control): Include in Scope 1
Employee-owned vehicles for business: May be Scope 3 (business travel)

Use the ownership field (owned or rented) to distinguish.

Calculate Emissions

ISO 14064

GHG Protocol

GLEC v3.0 Framework

Use Case Tutorials

Life Cycle Assessment (LCA)

Own Workforce (Social Data)

ISO 14001 Management Systems

Advanced

Automation & AI

Step 2 - Calculate Scope 1 Emissions

Understanding Scope 1 Emissions

Prerequisites

Calculating Stationary Combustion

Emission Sources Covered

Calculation Methods by Country

Data Flow

Step 2.1: Create a Fuel Consumption Invoice

Step 2.2: Track Refrigerant Recharges

Step 2.3: Track Process Emissions

Step 2.4: Track Waste Water Treatment Emissions

Calculating Mobile Combustion

Data Flow

Step 2.5: Create a Vehicle

Step 2.6: Record Vehicle Fuel Consumption

CSV Format for Vehicle Consumptions

Query Vehicle Consumptions

​Understanding Scope 1 Emissions

​Prerequisites

​Calculating Stationary Combustion

​Emission Sources Covered

​Calculation Methods by Country

​Data Flow

​Step 2.1: Create a Fuel Consumption Invoice

​Step 2.2: Track Refrigerant Recharges

​Step 2.3: Track Process Emissions

​Step 2.4: Track Waste Water Treatment Emissions

​Calculating Mobile Combustion

​Data Flow

​Step 2.5: Create a Vehicle

​Step 2.6: Record Vehicle Fuel Consumption

​CSV Format for Vehicle Consumptions

​Query Vehicle Consumptions

Understanding Scope 1 Emissions

Prerequisites

Calculating Stationary Combustion

Emission Sources Covered

Calculation Methods by Country

Data Flow

Step 2.1: Create a Fuel Consumption Invoice

Step 2.2: Track Refrigerant Recharges

Step 2.3: Track Process Emissions

Step 2.4: Track Waste Water Treatment Emissions

Calculating Mobile Combustion

Data Flow

Step 2.5: Create a Vehicle

Step 2.6: Record Vehicle Fuel Consumption

CSV Format for Vehicle Consumptions

Query Vehicle Consumptions