Skip to main content
GET
/
v1
/
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)
curl --request GET \
  --url https://api.dcycle.io/v1/hotel-stays \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'
{
  "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

x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Query Parameters

status[]
array[string]
Filter by statusAvailable values: active, pending, loading, completed, errorExample: status[]=active
start_date
date
Filter for stays that overlap this start date (inclusive)Format: YYYY-MM-DDExample: 2024-01-01
end_date
date
Filter for stays that overlap this end date (inclusive)Format: YYYY-MM-DDExample: 2024-12-31
name
string
Filter by name (partial match, case-insensitive)Example: offsite
file_id[]
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
created_at_from
datetime
Filter by minimum creation time (inclusive)Format: YYYY-MM-DDTHH:MM:SSZ
created_at_to
datetime
Filter by maximum creation time (inclusive)Format: YYYY-MM-DDTHH:MM:SSZ
sort
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
page
integer
default:"1"
Page number for pagination
size
integer
default:"50"
Items per page (max 100)

Response

items
array[object]
Array of hotel stay objects
total
integer
Total number of records matching the filter
page
integer
Current page number
size
integer
Items per page
filter_hash
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