The Rooms.aero API is built around a small set of objects that every endpoint shares. An id returned by one endpoint can always be passed to another.

Sources

A source is one hotel loyalty program. Every hotel, availability and alert carries its source. Use the key in the first column as the value of any source parameter.

Cash rates are recorded for every program when the program publishes them alongside the award rate. Countries are display names as shown on rooms.aero, such as "United States" or "Japan".

Reference Data

Hotel.brand and Hotel.award_category are the programs' own codes. The tables below map them to names; they are the same lists the rooms.aero filters use.

Hilton Honors (hilton)

Brand codes for Hotel.brand:

World of Hyatt (hyatt)

Brand codes for Hotel.brand:

Award categories for Hotel.award_category:

IHG Rewards (ihg)

Brand codes for Hotel.brand:

Marriott Bonvoy (marriott)

Brand codes for Hotel.brand:

Choice Privileges (choice)

Brand codes for Hotel.brand:

Award categories for Hotel.award_category:

Wyndham Rewards (wyndham)

Brand codes for Hotel.brand:

Award categories for Hotel.award_category:

I Prefer Hotel Rewards (iprefer)

Brand codes for Hotel.brand:

Objects

Hotel

A Hotel is one property in one program. Its id is the value you pass as hotel_id elsewhere; internal_id is the program's own property code. brand and award_category are program codes mapped to names in the reference data above. Get Hotels and Search also return lowest_award, the cheapest award seen on any upcoming date in the last two weeks. To fetch one hotel, filter Get Hotels by id.

Availability

An Availability is one hotel, one check-in date, one stay length: the cheapest standard room and the cheapest suite, each as an award (points) and as a cash rate, with a flag per rate saying whether it was offered. When the hotel is embedded, the row also carries a booking_link into the program's booking flow for that exact stay.

{
  "id": "2S8Cm9dHORWWKpoCkxfRkZa0e5l",
  "hotel_id": "2PPrELk9WcfJaNREWEPXypvhXAD",
  "source": "hyatt",
  "arrival_date": "2026-11-21",
  "departure_date": "2026-11-22",
  "num_nights": 1,
  "cash_currency_code": "USD",
  "standard_award_available": true,
  "standard_award_cost": 30000,
  "standard_cash_available": true,
  "standard_cash_cost": 68500,
  "standard_cpp": 2.28,
  "suite_award_available": false,
  "suite_award_cost": 0,
  "suite_cash_available": false,
  "suite_cash_cost": 0,
  "suite_cpp": 0,
  "booking_link": {
    "label": "Book via World of Hyatt",
    "url": "https://www.hyatt.com/shop/rooms/tyoph?checkinDate=2026-11-21&checkoutDate=2026-11-22&..."
  },
  "last_checked_at": "2026-09-07T03:58:01Z",
  "created_at": "2026-08-30T02:11:40Z"
}

Room

A Room is one room type offered on one availability, with its award and cash price for the stay. Only Get Availability Details returns rooms, cheapest award first.

Alert

An Alert asks rooms.aero to email you when matching availability appears at one hotel. Alerts are created and deleted on the site (rooms.aero/alerts); the API lists the ones on your Rooms.aero account. A one_off alert fires once and is then marked expired; a continuous alert keeps notifying about new or cheaper matches until you delete it.

Dates and Stay Length

rooms.aero tracks stays by check-in date and number of nights, not by check-in and check-out. Every availability has an arrival_date and a num_nights from 1 to 5; departure_date is derived from them.

Searches follow the same model. On Search and Get Availability, start_date and end_date bound the check-in date: a search for start_date=2026-11-20&end_date=2026-11-27 returns stays that begin on any of those days, whatever their length. To look for a particular length of stay, add nights (1 to 5); leave it out to see every length. There is no check-out parameter.

Dates are YYYY-MM-DD; timestamps (*_at) are RFC 3339 in UTC.

Units

• Points are whole numbers for the stay.
• Cash is an integer in the minor unit (cents) of the currency named beside it (cash_currency_code, cash_cost_currency or currency_code), for the stay.
• CPP is the cash value of one point in US cents, from the cash and award rates seen together; 0 when either is missing.

Freshness

last_checked_at on an availability says when that date's rates were last retrieved. Get Availability and Search only return upcoming check-in dates retrieved within the last 21 days. To get newer data for one property, call Refresh Hotel (one request per user every 24 hours, shared with the site) and read the hotel back a few minutes later.

Pagination

List endpoints wrap results in the same envelope:

{
  "data": [],
  "count": 100,
  "has_more": true,
  "more_url": "https://rooms.aero/partnerapi/hotels?skip=100&source=hyatt&take=100"
}

Request the next page with skip increased by take, or follow more_url, which is omitted on the last page. Orderings end in the row id so pages are stable, but live data can still shift between pages; deduplicate by id (or hotel.id for search results). Search results come cheapest award first.

Errors

Every non-2xx response is JSON with a stable error code and a human-readable message:

{ "error": "invalid_parameter", "message": "The nights parameter is invalid: must be between 1 and 5." }