Hotels destination explorer

A destination explorer lets visitors browse every hotel in your portfolio with a “from” price per property. The Best Price Hotels (Arrivals) endpoint returns per-hotel pricing across your date window in a single call.

Prerequisites

Before building a destination explorer, make sure you have:

A working Best Price call. If not, follow the Quick start first.
A group ID covering the hotels you want to display.
A target date window (typically 30 to 90 days).

How it works

The Hotels (Arrivals) endpoint returns one entry per hotel 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 hotel in the group, with no aggregation on your side. A hotel with no bookable offer in the window comes back with status: NotAvailable. Keep only the entries whose status is Available or OnRequest; a hotel without one has nothing to display.

Build the explorer

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

Call Best Price Hotels (Arrivals) once

Send one request to /BestPrice/Hotels/Arrivals with your date range, group ID, and party. The response is an array with one entry per hotel.

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

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

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: { groupId: <groupId> },
      currency: "EUR",
    },
  }),
});
const data = await response.json();

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

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

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

HttpPost request = new HttpPost("https://{apiBaseUrl}/Planning/2018A/BestPrice/Hotels/Arrivals");
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 bookable entries by hotel

With a single strategy in behaviours, each hotel appears once, with its best totalPrice over the window and the arrivalDate it applies to. Keep the entries whose status is Available or OnRequest, and key them by hotelId to look up each hotel’s “from” price and currency.

function indexByHotel(data) {
  const byHotel = new Map();
  for (const entry of data) {
    if (entry.status !== "Available" && entry.status !== "OnRequest") continue;
    byHotel.set(entry.hotelId, entry);
  }
  return byHotel;
}

const byHotel = indexByHotel(data);

def index_by_hotel(data):
    by_hotel = {}
    for entry in data:
        if entry["status"] not in ("Available", "OnRequest"):
            continue
        by_hotel[entry["hotelId"]] = entry
    return by_hotel

by_hotel = index_by_hotel(data)

function indexByHotel(array $data): array {
    $byHotel = [];
    foreach ($data as $entry) {
        if (!in_array($entry['status'], ['Available', 'OnRequest'], true)) {
            continue;
        }
        $byHotel[$entry['hotelId']] = $entry;
    }
    return $byHotel;
}

$byHotel = indexByHotel($data);

var byHotel = data.EnumerateArray()
    .Where(d => d.GetProperty("status").GetString() is "Available" or "OnRequest")
    .ToDictionary(
        d => d.GetProperty("hotelId").GetInt32(),
        d => d
    );

Map<Integer, JsonNode> byHotel = new HashMap<>();
for (JsonNode entry : data) {
    String status = entry.get("status").asText();
    if (!status.equals("Available") && !status.equals("OnRequest")) continue;
    int hotelId = entry.get("hotelId").asInt();
    byHotel.put(hotelId, entry);
}

Render the property cards

Display each hotel with its “from” price, photo, location, and a CTA. For hotels with no bookable entry in the response, show a soft fallback rather than a hard “Sold out”, since availability changes throughout the day.

hotels.forEach(hotel => {
  const cheapest = byHotel.get(hotel.id);
  renderHotelCard({
    hotelId: hotel.id,
    name: hotel.name,
    location: hotel.location,
    photo: hotel.photo,
    from: cheapest
      ? { price: cheapest.totalPrice, currency: cheapest.currency }
      : { fallback: "Check availability" },
  });
});

for hotel in hotels:
    cheapest = by_hotel.get(hotel["id"])
    render_hotel_card({
        "hotelId": hotel["id"],
        "name": hotel["name"],
        "location": hotel["location"],
        "photo": hotel["photo"],
        "from": (
            {"price": cheapest["totalPrice"], "currency": cheapest["currency"]}
            if cheapest else {"fallback": "Check availability"}
        ),
    })

foreach ($hotels as $hotel) {
    $cheapest = $byHotel[$hotel['id']] ?? null;
    renderHotelCard([
        'hotelId'  => $hotel['id'],
        'name'     => $hotel['name'],
        'location' => $hotel['location'],
        'photo'    => $hotel['photo'],
        'from'     => $cheapest
            ? ['price' => $cheapest['totalPrice'], 'currency' => $cheapest['currency']]
            : ['fallback' => 'Check availability'],
    ]);
}

foreach (var hotel in hotels)
{
    var cheapest = byHotel.TryGetValue(hotel.Id, out var c) ? (JsonElement?)c : null;
    RenderHotelCard(new
    {
        hotelId = hotel.Id,
        name = hotel.Name,
        location = hotel.Location,
        photo = hotel.Photo,
        from = cheapest.HasValue
            ? (object)new
            {
                price = cheapest.Value.GetProperty("totalPrice").GetDecimal(),
                currency = cheapest.Value.GetProperty("currency").GetString()
            }
            : new { fallback = "Check availability" }
    });
}

for (Hotel hotel : hotels) {
    JsonNode cheapest = byHotel.get(hotel.id());
    Object from = cheapest != null
        ? Map.of(
            "price", cheapest.get("totalPrice").decimalValue(),
            "currency", cheapest.get("currency").asText()
        )
        : Map.of("fallback", "Check availability");
    renderHotelCard(Map.of(
        "hotelId", hotel.id(),
        "name", hotel.name(),
        "location", hotel.location(),
        "photo", hotel.photo(),
        "from", from
    ));
}

Tips

Cache aggressively. One call per (date range, party, group) combination. Easy cache key, big payoff for landing pages that get heavy browse traffic.
Use a tight date window. 30 days is usually enough for an explorer page. A 90-day window costs more per call without changing the “from” price most of the time.
Consider behaviours: ["EarliestAvailability"]. The default LowestLengthOfStay favours the shortest stay that clears the restrictions, and CheapestStay favours the lowest price. Switch to EarliestAvailability if your UI promises “earliest dates first”: useful for last-minute or “next weekend” widgets. Keep a single value in behaviours: list several only to replace separate calls you would otherwise make, since each extra strategy slows the call. The single behaviour property is deprecated.
Scope by sub-region with filter.hotels. If your group is large and your visitor is browsing a specific destination, filter the response to those hotels only with filter.hotels.default: "Excluded" and exceptions: [hotelId, ...]. Same allow-list pattern as the rooms filter.

Reference

Full schema for the Hotels (Arrivals) endpoint.

Best practices

Caching, performance, and resilience patterns.

Get started

Build

Resources

Hotels destination explorer

Prerequisites

How it works

Build the explorer

Call Best Price Hotels (Arrivals) once

Index the bookable entries by hotel

Render the property cards

Tips

Reference

Best practices

​Prerequisites

​How it works

​Build the explorer

Call Best Price Hotels (Arrivals) once

Index the bookable entries by hotel

Render the property cards

​Tips

​Related

Reference

Best practices

Prerequisites

How it works

Build the explorer

Tips

Related