Skip to main content

​
Hotel Stay Tools

Manage hotel stay records — accommodation bookings with check-in/check-out dates, room counts, and associated CO₂e emissions. This is Scope 3 Category 6 (business travel) data.

​
list_hotel_stays

List hotel stay records with optional filters. Parameters:
ParameterTypeRequiredDefaultDescription
organization_idstringNodefault orgOrganization UUID
statusstringNo—Status filter: active, deleted
start_datestringNo—Filter stays from this date (YYYY-MM-DD)
end_datestringNo—Filter stays until this date (YYYY-MM-DD)
namestringNo—Filter by hotel name (partial match)
pageintegerNo1Page number
sizeintegerNo50Results per page
Example response: 
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Team offsite — Madrid",
      "check_in_date": "2024-11-04",
      "check_out_date": "2024-11-07",
      "country": "ES",
      "address": "Gran Vía 28, Madrid, Spain",
      "hotel_name": "Hotel Gran Vía",
      "rooms": 3,
      "status": "active",
      "source": "manual",
      "co2e": 18.54,
      "file_id": null,
      "file_name": null,
      "created_at": "2024-11-01T09:00:00Z",
      "updated_at": "2024-11-01T09:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "size": 50,
  "pages": 1
}
Key response fields:
FieldDescription
nameDescription or label for the stay (e.g. “Team offsite — Madrid”)
hotel_nameName of the hotel
check_in_date / check_out_dateStay dates (number of nights = difference between these)
roomsNumber of rooms booked
countryISO country code of the hotel location
co2eCalculated CO₂e emissions in kg
sourceHow the record was created: manual, bulk_upload, or api
Example prompts: 
"List our hotel stays for Q1 2024"
"Show hotel stays at Marriott properties"
"How many hotel nights did we book last year?"
"What are the emissions from our hotel stays in 2025?"

​
Write Operations

​
create_hotel_stay

Create a hotel stay record for Scope 3 accommodation emissions. CO₂e is calculated based on the country and number of nights — the response will initially show co2e as null. Duration can be specified in two ways:
  • Provide check_out_date directly.
  • Provide nights — the check-out date is calculated as check_in_date + nights.
At least one of these must be given. Parameters:
ParameterTypeRequiredDefaultDescription
check_in_datestringYes—Check-in date (YYYY-MM-DD)
countrystringYes—ISO-2 country code of the hotel (e.g. "ES", "FR", "US")
check_out_datestringNo—Check-out date (YYYY-MM-DD), must be on or after check_in_date
nightsintegerNo—Number of nights (alternative to check_out_date, min 1)
roomsintegerNo1Number of rooms booked (max 10,000)
namestringNo—Guest or trip name for identification
hotel_namestringNo—Name of the hotel
addressstringNo—Hotel address (used for geocoding)
organization_idstringNodefault orgOrganization UUID
You can provide either check_out_date or nights — the backend calculates the other. If both are omitted, the API returns a validation error.
CO₂e emissions are calculated in the background after creation. The initial response will show co2e: null. Call list_hotel_stays after a few seconds to see the calculated value.
Example response: 
{
  "id": "550e8400-...",
  "check_in_date": "2025-06-01",
  "check_out_date": "2025-06-04",
  "country": "ES",
  "hotel_name": "Hotel Gran Vía",
  "rooms": 1,
  "status": "active",
  "co2e": null,
  "created_at": "2025-06-01T10:30:00Z"
}
Example prompts: 
"Log a 3-night hotel stay in Spain starting June 1st"
"Create a hotel stay at Hotel Berlin, check-in March 10, check-out March 12, 3 rooms"
"Add a hotel stay in France for the team offsite, 5 nights"
Common errors:
ErrorCause
422: “Either check_out_date or nights must be provided”Neither duration method was given
422: “check_out_date must be on or after check_in_date”Check-out is before check-in

​
update_hotel_stay

Update an existing hotel stay record. Only the fields you provide are changed. CO₂e is recalculated after update. Duration can be updated in two ways:
  • Provide check_out_date directly.
  • Provide nights (with or without a new check_in_date) — the check-out date is recalculated automatically.
Parameters:
ParameterTypeRequiredDefaultDescription
hotel_stay_idstringYes—UUID of the record. Use list_hotel_stays to find it
check_in_datestringNo—New check-in date (YYYY-MM-DD)
check_out_datestringNo—New check-out date (YYYY-MM-DD)
nightsintegerNo—Number of nights (alternative to check_out_date, min 1)
countrystringNo—New ISO-2 country code (e.g. "ES", "FR", "US")
namestringNo—New guest or trip name
hotel_namestringNo—New hotel name
addressstringNo—New hotel address
roomsintegerNo—New number of rooms (1-10,000)
organization_idstringNodefault orgOrganization UUID
Example prompts: 
"Change hotel stay abc-123 to 5 nights"
"Update the hotel stay country to France"
"Fix the hotel name on stay xyz to 'Hotel Gran Vía'"
"Change the check-in date to March 15th"
Common errors:
ErrorCause
404: “Hotel stay not found”Invalid hotel stay UUID
422: “check_out_date must be on or after check_in_date”Update would set check-out before check-in

​
Workflows

​
Querying hotel stays

  1. List hotel stays — list_hotel_stays to query stays by date range or hotel name
  2. View travel emissions — get_greenhouse_gas_emissions with category=travels for aggregated business travel totals
  3. Compare with flights — list_business_travels to see flight/train records alongside hotel data

​
Logging a hotel stay

  1. Create the stay — create_hotel_stay with check-in date, country, and nights or check-out date
  2. Verify — list_hotel_stays after a few seconds to confirm creation and CO₂e calculation

API: Create Hotel Stay

REST API endpoint for hotel stay creation

API: List Hotel Stays

REST API equivalent with additional filters

Business Travels

Flight and train journey records

Emissions

Aggregated Scope 3 travel emissions