Hotel Stay 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/hotel-stays/{hotel_stay_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/hotel-stays/{hotel_stay_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/hotel-stays/{hotel_stay_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,
"details": {}
}
]
}Hotel Stay Calculation Steps
Get a step-by-step CO2e breakdown for a specific hotel stay
GET
/
v1
/
hotel-stays
/
{hotel_stay_id}
/
steps
Hotel Stay 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/hotel-stays/{hotel_stay_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/hotel-stays/{hotel_stay_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/hotel-stays/{hotel_stay_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,
"details": {}
}
]
}← Hotel Stays API
Returns the step-by-step emission calculation for a specific hotel stay, showing exactly how the CO2e figure was derived from the room-night emission factor that was applied.
Where:
Request
Headers
string
required
Your API key for authenticationExample:
sk_live_1234567890abcdefstring
required
Your organization UUIDExample:
a8315ef3-dd50-43f8-b7ce-d839e68d51faPath Parameters
string
required
The unique identifier (UUID) of the hotel stay recordExample:
550e8400-e29b-41d4-a716-446655440000Response
The response contains the full step-by-step calculation breakdown as used by the Dcycle kernel.number
Total CO2e in kg across all periods
array
One entry per calendar year the stay spans
Show Period object
Show Period object
date
Period start date
date
Period end date
number
CO2e for this period, in kg
object
Calculation steps grouped by GHG type:
co2e, co2e_from_ch4, co2e_from_n2o and
co2e_from_co2, each an array of steps. A hotel stay always resolves in a single final
step, so only co2e carries entries — the per-gas arrays come back empty and exist to keep
the response shape identical across activity categories.Each step object has step (position in the chain), raw_value and calculated_value
(both { value, unit: { unit_id, unit_name } }), conversion_factor
({ value, type }, where value is the applied ratio calculated / raw), source
({ source_id, source_name, source_version, source_reference_year }) and the match
metadata coincidence and coincidence_concept_id, either of which may be null.Calculation Methodology
CO2e is computed as:CO2e (kg) = rooms × nights × EF (kg CO2e / room-night)
- nights =
check_out_date − check_in_datein days - EF = the hotel room-night emission factor for the stay’s country. Sources resolve in priority order DEFRA → Greenview, unless the organization pinned a different source for the
HOTEL_STAYScategory. Thesourceblock of each step tells you which one was used
total_impacts row is written per calendar year the stay spans, which is why a stay crossing 31 December comes back as two periods.
Example
curl -X GET "https://api.dcycle.io/v1/hotel-stays/550e8400-e29b-41d4-a716-446655440000/steps" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}"
import requests
import os
response = requests.get(
"https://api.dcycle.io/v1/hotel-stays/550e8400-e29b-41d4-a716-446655440000/steps",
headers={
"x-api-key": os.getenv("DCYCLE_API_KEY"),
"x-organization-id": os.getenv("DCYCLE_ORG_ID")
}
)
print(response.json())
const axios = require('axios');
const hotelStayId = '550e8400-e29b-41d4-a716-446655440000';
axios.get(`https://api.dcycle.io/v1/hotel-stays/${hotelStayId}/steps`, {
headers: {
'x-api-key': process.env.DCYCLE_API_KEY,
'x-organization-id': process.env.DCYCLE_ORG_ID,
},
}).then(response => {
console.log(`Total CO2e: ${response.data.total_co2e} kg`);
});
Successful Response
{
"total_co2e": 0.312,
"periods": [
{
"start_date": "2025-03-10",
"end_date": "2025-03-13",
"co2e": 0.312,
"details": {
"co2e": [
{
"step": 1,
"raw_value": {
"value": 3.0,
"unit": {
"unit_id": "981216d5-9008-4958-a57e-8eac95fd53e5",
"unit_name": "room_per_night"
}
},
"conversion_factor": { "value": 0.104, "type": "final_conversion" },
"calculated_value": {
"value": 0.312,
"unit": {
"unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"unit_name": "kilogram_(kg)"
}
},
"source": {
"source_id": "8e3c1f42-0b6d-4a7c-9f21-5c7de4b9a013",
"source_name": "DEFRA",
"source_version": "2025",
"source_reference_year": 2025
},
"coincidence": "exact",
"coincidence_concept_id": "b41d7f90-2c58-4e6a-8d31-7a9f0c2e5b46"
}
],
"co2e_from_ch4": [],
"co2e_from_n2o": [],
"co2e_from_co2": []
}
}
]
}
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: The hotel stay ID does not exist or belongs to a different organization.{
"detail": "Hotel stay not found",
"code": "HOTEL_STAY_NOT_FOUND"
}
Related Endpoints
Get Hotel Stay
Retrieve full stay details
List Hotel Stays
Browse all stays for the organization
Was this page helpful?