Hotel Stays API

​

Key Features

• Accommodation Records Management: Create and manage hotel stay records
• Room-Night Emissions: Automatic CO2e calculation with the room-night emission factor of each country, or your own
• Pagination Support: Efficiently retrieve large lists of hotel stays with filtering

​

Authentication

​

Headers

​

Available Endpoints

​

Hotel Stay Attributes

​

Core Information

• name (string, optional): Free-text description of the stay
• check_in_date (date, required): Date the guest checked in
• check_out_date (date, required): Date the guest checked out
• country (string, required): ISO-3166 alpha-2 country code (e.g. ES, GB, US)
• address (string, optional): The hotel’s address or city, to place it on a map
• hotel_name (string, optional): Name of the hotel
• rooms (integer, required): Number of rooms booked (1–10000)

​

Status

• status (string, read-only): active, pending, or error
• source (string, read-only): How the record was created (manual, bulk_upload, etc.)
• co2e (number, read-only): Calculated CO2 equivalent emissions in kg — sourced from total_impacts, not stored on the record

​

Emission Methodology

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

• nights = check_out_date − check_in_date in days
• EF = the hotel room-night emission factor of the stay’s country (DEFRA, or Greenview where DEFRA has none), or of its custom emission factor record

​

Response Format

​

Hotel Stay Object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "name": "Team offsite — Madrid",
  "check_in_date": "2024-11-04",
  "check_out_date": "2024-11-07",
  "country": "ES",
  "city": "Madrid",
  "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",
  "uploaded_by": {
    "id": "b9f1e2d3-...",
    "first_name": "Ana",
    "last_name": "García"
  }
}

​

Pagination Response

{
  "items": [
    { "hotel stay object" }
  ],
  "total": 42,
  "page": 1,
  "size": 50,
  "filter_hash": "abc123..."
}

​

Error Handling

​

Common HTTP Status Codes

​

Error Response Format

{
  "detail": "Error description",
  "code": "ERROR_CODE"
}

​

GHG Protocol Context

• Scope 3: Indirect emissions from value chain activities
• Category 6: Business Travel — emissions from employee travel and accommodation for work purposes

​

Related Documentation