Skip to content
Blog

Hotel availability API: designing for slow suppliers

Tekravel Editorial
Written with the help of AI

The ticket usually arrives looking innocent. "Add hotel search to the booking page — the supplier gave us a hotel availability API, there's a sandbox, should be a sprint." You read the docs, you send a request for two adults in Dubai for three nights, and a response comes back. Then you send the same request for a city with more properties, and nothing comes back for a long, uncomfortable while. When it does, it is a document large enough to make your JSON parser think about its life choices.

That is the moment the job changes shape. Hotel availability is not a lookup. It is a fan-out: one question from your user becomes many questions to many suppliers, each of which answers at its own speed, in its own vocabulary, with its own idea of what a "room" is. The client you build has to stay useful while that fan-out is still resolving. This piece is about designing that client — written for a developer who knows REST and JSON well and has never had to explain to a hotel why a guest's non-refundable rate was shown as free cancellation.

Why a hotel availability API is slower than the endpoints you are used to

A flight search and a hotel search look similar from the outside: a query goes out, priced options come back. Underneath, they are not the same problem. If you have read our notes on what a flight booking API integration really involves, you already know that the price you search is not always the price you book. Hotels add a second difficulty on top of that one: volume.

A single city can hold hundreds of properties. Each property sells several room types. Each room type is sold under several rate plans — with breakfast, without, refundable, non-refundable, a member rate, a package rate. Each rate plan may come from more than one supplier: a bedbank, a channel manager, a direct contract, a wholesaler you signed with because their allotment in one hotel was better than anyone else's. Multiply those out and a "simple" search is a large tree, assembled from several sources that do not agree on names or IDs.

So the slow part is rarely your code. It is the slowest supplier you chose to wait for.

Progressive results or the full answer: pick deliberately

There are two honest ways to return hotel search results, and most integrations end up somewhere unhappy in the middle.

Wait for everything. Your backend fans out, waits for every supplier to answer or time out, merges, deduplicates, sorts, and returns one complete list. The result is clean: one request, one response, prices that can be compared because they are all on the table. The cost is that your user stares at a spinner for as long as your slowest supplier takes, every single time.

Stream what you have. Your backend starts the fan-out and returns a search handle immediately. The client polls the handle, or holds a stream open, and receives results in batches as suppliers answer. The first hotels appear quickly. The cost is complexity everywhere else: the list reorders while the user is reading it, a "cheapest" badge can move, and a hotel that appeared from one supplier may later get a cheaper rate from another.

If your interface is a search page in front of a human, progressive is almost always right — the person is browsing, not running a batch job, and a page that is visibly working beats a page that is silently thinking. If your consumer is another machine — a rate-comparison job, a corporate booking tool that needs one definitive answer — waiting is often simpler and correct.

Whichever you pick, three rules keep a progressive client sane:

  • Every batch carries a completion state for the search as a whole, so the client knows the difference between "no more results yet" and "no more results ever".
  • Results are merged by a stable hotel key on the server, not appended. The client should never have to work out that two cards are the same building.
  • Sorting by price is provisional until the search completes, and the interface says so. Users forgive a list that settles; they do not forgive a "lowest price" label that turns out to be wrong.

Modelling rooms and rate plans so they do not collapse

This is where most hotel integrations quietly fail, and the failure shows up months later as a support ticket rather than a bug report.

The tempting model is flat: a hotel has a list of offers, each offer has a room name and a price. It renders nicely. Then a supplier returns "Deluxe King" and "Deluxe Room, 1 King Bed" for what is obviously the same room, another supplier returns the same name for two genuinely different rooms (one with a city view, one without), and a third returns a rate whose price is per night while everyone else's is per stay. A flat list cannot tell you which of these you are looking at. It just shows them.

A model that survives contact with real suppliers has at least four levels, and it keeps them apart:

LevelWhat it holdsThe mistake to avoid
HotelYour own stable ID, mapped to each supplier's codeUsing a supplier's hotel ID as your primary key
RoomOccupancy, bed configuration, the supplier's own room text kept verbatim"Cleaning up" room names until two different rooms merge into one
Rate planBoard basis, refundability, payment type, the supplier it came fromTreating breakfast or refundability as part of the room name
PriceTotal for the stay, currency, what taxes and fees are inside it and which are payable at the hotelShowing a per-night figure next to per-stay figures, or hiding fees paid on arrival

You can disagree with where the lines fall — some teams split occupancy into its own level, which is reasonable once you sell multi-room bookings. What you cannot do is merge levels because the user interface only shows two of them. The interface can flatten at render time. The data must not.

One detail deserves its own sentence: keep the supplier's raw room description alongside whatever you normalise. When a guest arrives and is given a different room from the one on their voucher, the first thing anyone will ask is what the supplier actually sent.

Cancellation policies are data, not a paragraph

Many suppliers return cancellation terms as free text: "Free cancellation until 3 days before arrival, after that 1 night penalty." It is very tempting to display that string and move on.

Don't. Text cannot be compared, sorted, filtered or enforced. Your user wants to filter to refundable rates. Your finance team wants to know which bookings become non-refundable tomorrow so the agency can chase the client before the deadline passes. Your post-booking flow needs to tell the customer, at the moment they press cancel, exactly what they will be charged. None of that works on a sentence.

Model each policy as an ordered list of penalty windows: from this instant, until that instant, the charge is this amount (or this share of the stay, or this many nights). The boundaries are timestamps with a timezone — the hotel's timezone, not your server's and not the user's — because "3 days before arrival" means a different moment depending on whose midnight you count from. Store the supplier's original text next to the structured version, show the structured version, and treat a mismatch between them as something to investigate rather than something to hide.

And re-check the policy at booking time, not just at search time. Policies change between the two calls more often than anyone expects.

What getting it wrong actually costs

A slow search costs you conversions, which is bad but visible — someone will complain. The expensive failures are the quiet ones.

A rate shown as refundable that the supplier treats as non-refundable is a dispute with a customer who has a screenshot, and the agency usually ends up paying the penalty itself. A per-night price displayed as a per-stay total sells rooms below cost until someone in accounting notices. A room merged with a different room sends a family of four to a room built for two. Fees payable at the hotel that were never shown turn a five-star review into a chargeback. Each of these is a modelling decision made in the first sprint, usually under the label "we'll clean it up later".

Caching: what you may keep and what you must not

Every team that integrates a hotel API eventually asks whether it can cache results to make search faster and cheaper. The answer is yes, for some things, and the line between them matters more than any performance number.

Static content — hotel names, addresses, coordinates, photos, amenity lists, room descriptions — changes rarely and is exactly what you should cache, aggressively, in your own store. Check the supplier's terms on how you may store and display it; some licences restrict that. Fetching it live on every search is slow for no benefit.

Live rates and availability are a different matter. A cached price is a guess about what the supplier will charge, and suppliers do not honour your guesses. Short-lived caching of search results can be acceptable for showing a page — as long as every booking path re-prices against the supplier before taking money, and the interface treats a changed price as a normal outcome rather than an error. Some suppliers also limit how often you may search relative to how often you book; aggressive caching that hides your real traffic from them is not a loophole worth relying on.

What you must never cache is anything that represents a commitment: a held price token, a booking reference, a cancellation quote. Those belong to one user and one moment.

Before you call it done

A short check, worth running against your own integration before it carries real bookings:

  • The search returns a completion state, and the client behaves differently before and after it.
  • Hotels are keyed by your own ID, with each supplier's code mapped to it.
  • Room, rate plan and price are separate objects in your data, whatever the screen shows.
  • Every price says whether it is per night or per stay, and what is payable on arrival.
  • Cancellation policies are stored as timed penalty windows in the hotel's timezone, with the original text kept.
  • The booking path re-prices and re-reads the policy before it charges anyone.
  • Nothing that represents a commitment is ever served from a cache.

If you are weighing whether to build all of this against individual suppliers or to start from a platform that has already met these problems, the contract side matters as much as the code — our piece on hotel consolidator contracts and bedbank rates covers what to ask for. Our own flight and hotel APIs are opened by conversation rather than by a self-serve key; if that is the route you want to explore, start that conversation on the travel APIs page.

The fan-out never goes away. A good client simply stops pretending it isn't there.

Tekravel Editorial

Travel technology desk

The Tekravel travel-technology desk writes for the trade: agency owners, consolidators and the developers who integrate them. Every article is checked against the platform it describes before it is published.