Best rate per room type

A “from” price per room helps guests compare options at a glance, before they commit to a date. The Best Price Rooms endpoint returns per-room pricing across your date window in a single call.

Prerequisites

Before building a per-room listing, make sure you have:

A working Best Price call. If not, follow the Quick start first.
A hotel ID and a group ID.
A target date window (typically 30 to 90 days).

How it works

The Rooms endpoint returns one entry per available room and requested strategy, with the best price found over your date window and the arrival date it applies to. With a single call and a single strategy in behaviours (LowestLengthOfStay when you send none), you get one “from” price per room, with no aggregation on your side. Rooms that are not bookable on any day in the window are absent from the response.

Build the listing

The examples below assume the OAuth signing setup from the Quick start.

Call Best Price Rooms once

Send one request to /BestPrice/Rooms with your date range and party. The response is an array with one entry per room.

curl --request POST \
  --url https://{apiBaseUrl}/Planning/2018A/BestPrice/Rooms \
  --header 'Authorization: OAuth ...' \
  --header 'Content-Type: application/json' \
  --data '{
    "beginDate": "2026-12-07",
    "endDate": "2027-01-05",
    "guests": {"adults": 2},
    "filter": {
      "ratePlan": {"hotelId": <hotelId>, "groupId": <groupId>},
      "currency": "EUR"
    }
  }'

const url = "https://{apiBaseUrl}/Planning/2018A/BestPrice/Rooms";

const response = await fetch(url, {
  method: "POST",
  headers: { ...authHeaders, "Content-Type": "application/json" },
  body: JSON.stringify({
    beginDate: "2026-12-07",
    endDate: "2027-01-05",
    guests: { adults: 2 },
    filter: {
      ratePlan: { hotelId: <hotelId>, groupId: <groupId> },
      currency: "EUR",
    },
  }),
});
const data = await response.json();

response = session.post(
    "https://{apiBaseUrl}/Planning/2018A/BestPrice/Rooms",
    json={
        "beginDate": "2026-12-07",
        "endDate": "2027-01-05",
        "guests": {"adults": 2},
        "filter": {
            "ratePlan": {"hotelId": <hotelId>, "groupId": <groupId>},
            "currency": "EUR",
        },
    },
)
data = response.json()

$response = $client->post('Planning/2018A/BestPrice/Rooms', [
    'json' => [
        'beginDate' => '2026-12-07',
        'endDate'   => '2027-01-05',
        'guests'    => ['adults' => 2],
        'filter'    => [
            'ratePlan' => ['hotelId' => <hotelId>, 'groupId' => <groupId>],
            'currency' => 'EUR',
        ],
    ],
]);
$data = json_decode($response->getBody(), true);

var request = new RestRequest("/BestPrice/Rooms", Method.Post);
request.AddJsonBody(new
{
    beginDate = "2026-12-07",
    endDate = "2027-01-05",
    guests = new { adults = 2 },
    filter = new
    {
        ratePlan = new { hotelId = <hotelId>, groupId = <groupId> },
        currency = "EUR"
    }
});

var response = await client.ExecuteAsync(request);
var data = JsonDocument.Parse(response.Content!).RootElement;

String body = mapper.writeValueAsString(Map.of(
    "beginDate", "2026-12-07",
    "endDate", "2027-01-05",
    "guests", Map.of("adults", 2),
    "filter", Map.of(
        "ratePlan", Map.of("hotelId", <hotelId>, "groupId", <groupId>),
        "currency", "EUR"
    )
));

HttpPost request = new HttpPost("https://{apiBaseUrl}/Planning/2018A/BestPrice/Rooms");
request.setEntity(new StringEntity(body, "UTF-8"));
request.setHeader("Content-Type", "application/json");
consumer.sign(request);

JsonNode data;
try (CloseableHttpResponse response = client.execute(request)) {
    data = mapper.readTree(EntityUtils.toString(response.getEntity()));
}

Index the response by room

With a single strategy in behaviours, each room appears once, with its best totalPrice over the window and the arrivalDate it applies to. Key the entries by roomId to look up each room’s “from” price and currency.

function indexByRoom(data) {
  const byRoom = new Map();
  for (const entry of data) {
    byRoom.set(entry.roomId, entry);
  }
  return byRoom;
}

const byRoom = indexByRoom(data);

def index_by_room(data):
    by_room = {}
    for entry in data:
        by_room[entry["roomId"]] = entry
    return by_room

by_room = index_by_room(data)

function indexByRoom(array $data): array {
    $byRoom = [];
    foreach ($data as $entry) {
        $byRoom[$entry['roomId']] = $entry;
    }
    return $byRoom;
}

$byRoom = indexByRoom($data);

var byRoom = data.EnumerateArray()
    .ToDictionary(
        d => d.GetProperty("roomId").GetInt32(),
        d => d
    );

Map<Integer, JsonNode> byRoom = new HashMap<>();
for (JsonNode entry : data) {
    int roomId = entry.get("roomId").asInt();
    byRoom.put(roomId, entry);
}

Render the room cards

Display each room with its “from” price. For rooms with no entry in the response, show a soft fallback rather than a hard “Sold out”, since availability changes throughout the day.

rooms.forEach(room => {
  const cheapest = byRoom.get(room.id);
  renderRoomCard({
    roomId: room.id,
    name: room.name,
    from: cheapest
      ? { price: cheapest.totalPrice, currency: cheapest.currency }
      : { fallback: "Check availability" },
  });
});

for room in rooms:
    cheapest = by_room.get(room["id"])
    render_room_card({
        "roomId": room["id"],
        "name": room["name"],
        "from": (
            {"price": cheapest["totalPrice"], "currency": cheapest["currency"]}
            if cheapest else {"fallback": "Check availability"}
        ),
    })

foreach ($rooms as $room) {
    $cheapest = $byRoom[$room['id']] ?? null;
    renderRoomCard([
        'roomId' => $room['id'],
        'name'   => $room['name'],
        'from'   => $cheapest
            ? ['price' => $cheapest['totalPrice'], 'currency' => $cheapest['currency']]
            : ['fallback' => 'Check availability'],
    ]);
}

foreach (var room in rooms)
{
    var cheapest = byRoom.TryGetValue(room.Id, out var c) ? (JsonElement?)c : null;
    RenderRoomCard(new
    {
        roomId = room.Id,
        name = room.Name,
        from = cheapest.HasValue
            ? (object)new
            {
                price = cheapest.Value.GetProperty("totalPrice").GetDecimal(),
                currency = cheapest.Value.GetProperty("currency").GetString()
            }
            : new { fallback = "Check availability" }
    });
}

for (Room room : rooms) {
    JsonNode cheapest = byRoom.get(room.id());
    Object from = cheapest != null
        ? Map.of(
            "price", cheapest.get("totalPrice").decimalValue(),
            "currency", cheapest.get("currency").asText()
        )
        : Map.of("fallback", "Check availability");
    renderRoomCard(Map.of(
        "roomId", room.id(),
        "name", room.name(),
        "from", from
    ));
}

Tips

Cache aggressively. One call per (date range, party) combination, easy cache key. Listings load instantly from cache between API refreshes.
Use a tight date window. 30 days is usually enough for listing display. A 90-day window costs more per call without changing the “from” price most of the time.
Handle rooms missing from the response. The endpoint returns entries only for rooms bookable on at least one arrival date in the window. A room that never appears might be fully sold across the period. Show a soft fallback rather than hiding the room from the listing.

Reference

Full schema for the Rooms endpoint.

Best practices

Caching, performance, and resilience patterns.

Get started

Build

Resources

Best rate per room type

Prerequisites

How it works

Build the listing

Call Best Price Rooms once

Index the response by room

Render the room cards

Tips

Reference

Best practices

​Prerequisites

​How it works

​Build the listing

Call Best Price Rooms once

Index the response by room

Render the room cards

​Tips

​Related

Reference

Best practices

Prerequisites

How it works

Build the listing

Tips

Related