Skip to main content
GET
/
v1
/
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)
curl --request GET \
  --url https://api.dcycle.io/v1/employee-historic/{employee_historic_id}/steps \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'
{
  "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": {}
    }
  }
}

​
Calculation Steps

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

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

​
Path Parameters

​
employee_historic_id
string
required
The commuting period UUIDExample: 660e8400-e29b-41d4-a716-446655440000

​
Response

Returns the calculation breakdown (HTTP 200).
​
total_co2e
number
Total CO2e emissions in kg for the entire commuting period.
​
periods
array[object]
Calculation steps grouped by year period.

​
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