List Hotel Stays

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', 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"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "items": {
    "id": "<string>",
    "organization_id": "<string>",
    "name": {},
    "check_in_date": "<string>",
    "check_out_date": "<string>",
    "country": "<string>",
    "address": {},
    "hotel_name": {},
    "rooms": 123,
    "status": "<string>",
    "source": {},
    "co2e": {},
    "file_id": {},
    "file_name": {},
    "created_at": {},
    "updated_at": {},
    "uploaded_by": {
      "id": "<string>",
      "first_name": {},
      "last_name": {},
      "profile_img_url": {}
    },
    "location_geocode": {
      "country_code": "<string>",
      "place_id": "<string>",
      "address_formatted": "<string>",
      "latitude": 123,
      "longitude": 123
    }
  },
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>"
}

GET

hotel-stays

List Hotel Stays

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', 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"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "items": {
    "id": "<string>",
    "organization_id": "<string>",
    "name": {},
    "check_in_date": "<string>",
    "check_out_date": "<string>",
    "country": "<string>",
    "address": {},
    "hotel_name": {},
    "rooms": 123,
    "status": "<string>",
    "source": {},
    "co2e": {},
    "file_id": {},
    "file_name": {},
    "created_at": {},
    "updated_at": {},
    "uploaded_by": {
      "id": "<string>",
      "first_name": {},
      "last_name": {},
      "profile_img_url": {}
    },
    "location_geocode": {
      "country_code": "<string>",
      "place_id": "<string>",
      "address_formatted": "<string>",
      "latitude": 123,
      "longitude": 123
    }
  },
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>"
}

List Hotel Stays

Retrieve a paginated list of hotel stay records for your organization, with support for filtering by status, date range, name, and file.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Query Parameters

array[string]

Filter by statusAvailable values: active, pending, loading, completed, errorExample: status[]=active

date

Filter for stays that overlap this start date (inclusive)Format: YYYY-MM-DDExample: 2024-01-01

date

Filter for stays that overlap this end date (inclusive)Format: YYYY-MM-DDExample: 2024-12-31

string

Filter by name (partial match, case-insensitive)Example: offsite

array[uuid]

Filter by source file UUID. Pass 00000000-0000-0000-0000-000000000000 to filter for stays with no associated file.Example: file_id[]=3fa85f64-5717-4562-b3fc-2c963f66afa6

datetime

Filter by minimum creation time (inclusive)Format: YYYY-MM-DDTHH:MM:SSZ

datetime

Filter by maximum creation time (inclusive)Format: YYYY-MM-DDTHH:MM:SSZ

array[string]

Sort order. Prefix with - for descending.Available values: check_in_date, check_out_date, name, created_at, updated_atExample: sort=-check_in_date

integer

default:"1"

Page number for pagination

integer

default:"50"

Items per page (max 100)

Response

array[object]

Array of hotel stay objects

Show Hotel Stay Object

string

Unique identifier (UUID)

string

Organization UUID this stay belongs to

string | null

Free-text description of the stay

date

Check-in date

date

Check-out date

string

ISO-3166 alpha-2 country code

string | null

Plain-text hotel address (used for geocoding)

string | null

Hotel name

integer

Number of rooms booked

string

active, pending, loading, completed, or error

string | null

How the record was created (manual, bulk_upload, etc.)

number | null

Calculated CO2e in kg (sourced from total_impacts)

string | null

UUID of the source bulk-upload file, if any

string | null

Name of the source file, if any

datetime

Record creation timestamp

datetime | null

Last update timestamp

object | null

User who created the record

Show User Object

string

UUID

string | null

First name

string | null

Last name

string | null

Profile image URL

object | null

Geocoded location (populated when address is resolved)

Show Location Geocode Object

string

ISO country code

string

Geocoding provider place ID

string

Full formatted address

number

Latitude coordinate

number

Longitude coordinate

integer

Total number of records matching the filter

integer

Current page number

integer

Items per page

string

Hash of the current filter state — use to detect if filters have changed

Example

curl -X GET "https://api.dcycle.io/v1/hotel-stays?page=1&size=50&status[]=active&start_date=2024-01-01&end_date=2024-12-31" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

headers = {
    "x-api-key": os.getenv("DCYCLE_API_KEY"),
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
}

params = {
    "page": 1,
    "size": 50,
    "status[]": ["active"],
    "start_date": "2024-01-01",
    "end_date": "2024-12-31"
}

response = requests.get(
    "https://api.dcycle.io/v1/hotel-stays",
    headers=headers,
    params=params
)

result = response.json()
for stay in result["items"]:
    nights = (
        (stay["check_out_date"] and stay["check_in_date"])
        and "N/A"  # compute externally if needed
    )
    print(f"{stay['hotel_name']} ({stay['country']}): {stay['rooms']} rooms — {stay['co2e']} kg CO2e")

const axios = require('axios');

const headers = {
  'x-api-key': process.env.DCYCLE_API_KEY,
  'x-organization-id': process.env.DCYCLE_ORG_ID
};

axios.get('https://api.dcycle.io/v1/hotel-stays', {
  headers,
  params: {
    page: 1,
    size: 50,
    'status[]': ['active'],
    start_date: '2024-01-01',
    end_date: '2024-12-31'
  }
})
.then(response => {
  response.data.items.forEach(stay => {
    console.log(`${stay.hotel_name} (${stay.country}): ${stay.rooms} rooms — ${stay.co2e} kg CO2e`);
  });
})
.catch(error => console.error(error));

Successful Response

{
  "items": [
    {
      "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",
      "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",
      "uploaded_by": {
        "id": "b9f1e2d3-0000-0000-0000-000000000001",
        "first_name": "Ana",
        "last_name": "García",
        "profile_img_url": null
      },
      "location_geocode": {
        "country_code": "ES",
        "place_id": "ChIJgTwKgJcpQg0RaSKMYcHeNsQ",
        "address_formatted": "Gran Vía 28, 28013 Madrid, Spain",
        "latitude": 40.4200,
        "longitude": -3.7025
      }
    }
  ],
  "total": 42,
  "page": 1,
  "size": 50,
  "filter_hash": "d4f9a2..."
}

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

422 Unprocessable Entity

Cause: Invalid query parameters (e.g. malformed date)

{
  "detail": [
    {
      "loc": ["query", "start_date"],
      "msg": "invalid date format",
      "type": "value_error.date"
    }
  ]
}

Get Hotel Stay

Get a specific stay by ID

Get Totals

Get aggregated stats across all stays

​List Hotel Stays

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​422 Unprocessable Entity

​Related Endpoints

Get Hotel Stay

Get Totals

List Hotel Stays

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

Related Endpoints