Calculation Steps

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/employee-historic/{employee_historic_id}/steps', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/employee-historic/{employee_historic_id}/steps"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "total_co2e": 123,
  "periods": {
    "start_date": "<string>",
    "end_date": "<string>",
    "co2e": 123,
    "common_steps": {
      "step": 123,
      "raw_value": {
        "value": 123,
        "unit": {
          "unit_id": "<string>",
          "unit_name": "<string>"
        }
      },
      "conversion_factor": {
        "value": 123,
        "type": "<string>"
      },
      "calculated_value": {},
      "source": {
        "source_id": "<string>",
        "source_name": "<string>",
        "source_version": "<string>",
        "source_reference_year": {}
      },
      "coincidence": {},
      "coincidence_concept_id": {}
    },
    "details": {
      "co2e_from_co2": {},
      "co2e_from_ch4": {},
      "co2e_from_n2o": {},
      "co2e": {}
    }
  }
}

GET

employee-historic

{employee_historic_id}

steps

Calculation Steps

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/employee-historic/{employee_historic_id}/steps', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/employee-historic/{employee_historic_id}/steps"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "total_co2e": 123,
  "periods": {
    "start_date": "<string>",
    "end_date": "<string>",
    "co2e": 123,
    "common_steps": {
      "step": 123,
      "raw_value": {
        "value": 123,
        "unit": {
          "unit_id": "<string>",
          "unit_name": "<string>"
        }
      },
      "conversion_factor": {
        "value": 123,
        "type": "<string>"
      },
      "calculated_value": {},
      "source": {
        "source_id": "<string>",
        "source_name": "<string>",
        "source_version": "<string>",
        "source_reference_year": {}
      },
      "coincidence": {},
      "coincidence_concept_id": {}
    },
    "details": {
      "co2e_from_co2": {},
      "co2e_from_ch4": {},
      "co2e_from_n2o": {},
      "co2e": {}
    }
  }
}

← Employees API Retrieve the full CO2e conversion breakdown for a commuting period. Each step shows the raw value, conversion factor applied, calculated result, and the emission factor source — useful for auditing and understanding how commuting emissions are computed. Steps are grouped by year period (since a commuting period can span multiple years) and split into:

common_steps — activity/unit normalization (e.g. person × km → pkm)
details — emission factor application, broken down by greenhouse gas (CO2, CH4, N2O)

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Path Parameters

string

required

The commuting period UUIDExample: 660e8400-e29b-41d4-a716-446655440000

Response

Returns the calculation breakdown (HTTP 200).

number

Total CO2e emissions in kg for the entire commuting period.

array[object]

Calculation steps grouped by year period.

Show Period Object

date

Period start date.

date

Period end date.

number

CO2e emissions in kg for this period.

array[object]

Activity/unit normalization steps applied before emission factors.

Show Step Object

integer

Step number in the conversion chain.

object

Input value and unit for this step.

Show Value Object

number

Numeric value.

object

Show Unit Object

string

Unit identifier.

string

Human-readable unit name.

object

Factor applied at this step.

Show Conversion Factor

number

Factor value.

string

Operator type (e.g. multiply, divide).

object

Result after applying the conversion factor (same structure as raw_value).

object

Emission factor source reference.

Show Source Object

string

Source database identifier.

string

Source name (e.g. DEFRA, GHG Protocol).

string

Source version.

integer | null

Reference year for the factor.

string | null

Matched concept description.

string | null

Matched concept UUID.

object

Emission factor steps broken down by greenhouse gas.

Show Details Object

array[object]

Steps for CO2 component (same structure as common_steps).

array[object]

Steps for CH4 component.

array[object]

Steps for N2O component.

array[object]

Steps for combined CO2e (when not broken down by gas).

Example

curl -X GET "https://api.dcycle.io/v1/employee-historic/660e8400-e29b-41d4-a716-446655440000/steps" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")

response = requests.get(
    "https://api.dcycle.io/v1/employee-historic/660e8400-e29b-41d4-a716-446655440000/steps",
    headers={
        "x-api-key": api_key,
        "x-organization-id": org_id
    }
)

data = response.json()
print(f"Total CO2e: {data['total_co2e']:.2f} kg")
for period in data["periods"]:
    print(f"\n  Period {period['start_date']} → {period['end_date']}: {period['co2e']:.2f} kg")
    for step in period["common_steps"]:
        raw = step["raw_value"]
        calc = step["calculated_value"]
        factor = step["conversion_factor"]
        print(f"    Step {step['step']}: {raw['value']} {raw['unit']['unit_name']} "
              f"× {factor['value']} = {calc['value']} {calc['unit']['unit_name']}")

const axios = require('axios');

const headers = {
  'x-api-key': process.env.DCYCLE_API_KEY,
  'x-organization-id': process.env.DCYCLE_ORG_ID,
};

const periodId = '660e8400-e29b-41d4-a716-446655440000';

axios.get(`https://api.dcycle.io/v1/employee-historic/${periodId}/steps`, { headers })
.then(({ data }) => {
  console.log(`Total CO2e: ${data.total_co2e.toFixed(2)} kg`);
  data.periods.forEach(period => {
    console.log(`\n  Period ${period.start_date} → ${period.end_date}: ${period.co2e.toFixed(2)} kg`);
  });
})
.catch(error => console.error(error));

Successful Response

{
  "total_co2e": 1245.5,
  "periods": [
    {
      "start_date": "2024-01-01",
      "end_date": "2024-12-31",
      "co2e": 1245.5,
      "common_steps": [
        {
          "step": 1,
          "raw_value": {
            "value": 1.0,
            "unit": { "unit_id": "person", "unit_name": "person" }
          },
          "conversion_factor": { "value": 15.0, "type": "multiply" },
          "calculated_value": {
            "value": 15.0,
            "unit": { "unit_id": "km", "unit_name": "km" }
          },
          "source": {
            "source_id": "user_input",
            "source_name": "User Input",
            "source_version": "1.0",
            "source_reference_year": null
          },
          "coincidence": null,
          "coincidence_concept_id": null
        }
      ],
      "details": {
        "co2e_from_co2": [
          {
            "step": 1,
            "raw_value": {
              "value": 3900.0,
              "unit": { "unit_id": "pkm", "unit_name": "pkm" }
            },
            "conversion_factor": { "value": 0.17148, "type": "multiply" },
            "calculated_value": {
              "value": 668.77,
              "unit": { "unit_id": "g_co2e", "unit_name": "g CO2" }
            },
            "source": {
              "source_id": "defra_2024",
              "source_name": "DEFRA",
              "source_version": "2024",
              "source_reference_year": 2024
            },
            "coincidence": "Cars (by size) - Medium car - Petrol",
            "coincidence_concept_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          }
        ],
        "co2e_from_ch4": [],
        "co2e_from_n2o": [],
        "co2e": []
      }
    }
  ]
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

403 Forbidden

Cause: The authenticated user is not a member of the organization

{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

404 Not Found

Cause: Commuting period not found

{"detail": "Employee Historic with id=UUID('...') not found", "code": "EMPLOYEE_HISTORIC_NOT_FOUND"}

List Commuting Periods

List all commuting periods

Get Commuting Period

Get a specific commuting period

​Request

​Headers

​Path Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Related Endpoints

List Commuting Periods

Get Commuting Period

Request

Headers

Path Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

Related Endpoints