Hotel Stay Impact Calculation

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}/impact-calculation', 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}/impact-calculation"

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>",
      "coincidence": "<string>",
      "co2e": 123,
      "details": [
        {}
      ]
    }
  ]
}

GET

hotel-stays

{hotel_stay_id}

impact-calculation

Hotel Stay Impact Calculation

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}/impact-calculation', 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}/impact-calculation"

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>",
      "coincidence": "<string>",
      "co2e": 123,
      "details": [
        {}
      ]
    }
  ]
}

Hotel Stay Impact Calculation

Returns the step-by-step emission calculation for a specific hotel stay, showing exactly how the CO2e figure was derived from the DEFRA room-night emission factor.

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 unique identifier (UUID) of the hotel stay recordExample: 550e8400-e29b-41d4-a716-446655440000

Response

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

Calculation periods, one per date range

Show Period object

date

Period start date

date

Period end date

string

How well the period matches the emission factor (exact, interpolated)

number

Total CO2e for this period (kg)

array

Breakdown by scope and category, each with step-by-step co2e calculation array showing raw value, conversion factor, calculated value, and source

Calculation Methodology

CO2e is computed as:

CO2e (kg) = rooms × nights × EF (kg CO2e / room-night)

Where:

nights = check_out_date − check_in_date in days
EF = DEFRA hotel room-night emission factor for the stay’s country (from the defra_hotel_stays kernel activity, HOTEL_STAYS category)

One total_impacts row is written per night so that partial-period exports and dashboards pro-rate correctly.

Example

curl -X GET "https://api.dcycle.io/v1/hotel-stays/550e8400-e29b-41d4-a716-446655440000/impact-calculation" \
  -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/impact-calculation",
    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}/impact-calculation`, {
  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",
      "coincidence": "exact",
      "co2e_scope_3": 0.312,
      "co2e": 0.312,
      "details": [
        {
          "scope": "scope_3",
          "category": "hotel_stays",
          "co2e": [
            {
              "step": 1,
              "raw_value": { "value": 3, "unit": "room-night" },
              "conversion_factor": { "value": 0.104, "type": "final_conversion" },
              "calculated_value": { "value": 0.312, "unit": "kg CO2e" },
              "source": {
                "source_id": "defra-2025",
                "source_name": "DEFRA",
                "source_version": "2025",
                "source_reference_year": 2025
              },
              "coincidence": "exact"
            }
          ],
          "co2e_from_ch4": [],
          "co2e_from_n2o": [],
          "co2e_from_co2": [],
          "co2_biogenic": []
        }
      ]
    }
  ]
}

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

Get Hotel Stay

Retrieve full stay details

List Hotel Stays

Browse all stays for the organization

​Hotel Stay Impact Calculation

​Request

​Headers

​Path Parameters

​Response

​Calculation Methodology

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Related Endpoints

Get Hotel Stay

List Hotel Stays

Hotel Stay Impact Calculation

Request

Headers

Path Parameters

Response

Calculation Methodology

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

Related Endpoints