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
View the detailed CO2e conversion steps for a commuting period
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": {}
}
}
}← 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
Path Parameters
Response
Returns the calculation breakdown (HTTP 200).Calculation steps grouped by year period.
Show Period Object
Show Period Object
Activity/unit normalization steps applied before emission factors.
Show Step Object
Show Step Object
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"}
Related Endpoints
List Commuting Periods
List all commuting periods
Get Commuting Period
Get a specific commuting period
Was this page helpful?