Skip to main content

Hotel Availability

POST 

/v2.0/hotels/availability

Introduction​

Returns rate availability for specific hotels, a registered region, or a geographic radius search, for a given period and one or more rooms.

Search destination​

Exactly one of the three destination criteria must be provided in destination:

  • hotelIds: list of internal Niara hotel IDs.
  • regionId: ID of a registered region.
  • circleInfo: radius search around a geographic point (latitude/longitude/radius).

Providing more than one is not an error. Only one is used, in this order of priority: circleInfo, then regionId, then hotelIds.

Rooms​

rooms lists every room wanted, each with its own occupancy and an optional ref. Rooms with the same occupancy are searched together, and each hotel's rates come back grouped by occupancy in hotels[].rooms[], each group naming the rooms it serves. A hotel is returned only when every room can be filled (unless includeUnavailableRoomRates is set), and cheapestCombination sums the cheapest bookable rate for every room.

With more than one occupancy, the first one decides which hotels are on the page; the others are then searched only in those hotels.

Pagination​

Results are paginated at 50 hotels per page — 25 with filterStrategy ALL_RATES, which returns far more rates per hotel (see page on the request and totalPages on the response).

Promotional code​

promoCode is passed on to suppliers that support it (Omnibees PromotionCode). Each rate the supplier applied a code to comes back with its own promoCode, which travels in the rateToken through the price check and the booking — nothing else needs to be sent again.

Request​

Body

    externalRequestId stringnullable

    Your id for this call, up to 128 printable characters. Returned as is in the response, success or error, and kept in our logs: quote it when contacting support, even if the response never reached you. Use a new value for each call.

    timestamp stringnullable

    When you sent this request, by your clock: ISO 8601 with a timezone offset, e.g. 2026-11-13T14:32:05.120-03:00. Kept in our logs.

    destination objectrequired
    hotelIds string[]nullable

    List of Niara hotel IDs to search. Mutually exclusive with regionId and circleInfo.

    regionId stringnullable

    ID of a region registered in Niara. Mutually exclusive with hotelIds and circleInfo.

    circleInfo objectnullable

    Radius search around a geographic point. Mutually exclusive with hotelIds and regionId.

    lat numberrequired

    Latitude of the search circle's center.

    lon numberrequired

    Longitude of the search circle's center.

    radius numberrequired

    Search radius from the center.

    unit

    Possible values: [km, mi]

    Default value: km

    Unit of measure for the radius: kilometers ("km") or miles ("mi").

    checkin stringrequired

    Check-in date (ISO 8601, e.g. 2026-10-01). Cannot be in the past.

    checkout stringrequired

    Check-out date (ISO 8601, e.g. 2026-10-02). Must be after checkin.

    rooms object[]required

    One entry per room wanted, 1 to 8. Rooms with the same occupancy are searched together; each hotel's rates come back grouped by occupancy (hotels[].rooms[]).

  • Array [
  • adults integerrequired

    Number of adults in this room (at least 1).

    childrenAges integer[]

    Ages of the children in this room (0 to 17), one entry per child.

    ref stringnullable

    Client name for this room: 1 to 20 characters [A-Za-z0-9_-], unique in the request. Defaults to r1, r2… by position. The response, the price check and the booking refer to the room by this name.

  • ]
  • preferredOnly boolean

    When true, restricts the result to the client's favorite hotels.

    awards undefined[]nullable

    Possible values: [1, 2, 3, 4, 5]

    Filters hotels by star rating. A hotel is included only if its rating exactly matches one of the values listed here (e.g. [4, 5] returns only 4- and 5-star hotels — it is not a "4 stars and up" threshold). Hotels with no rating on file are always excluded once this filter is set.

    filterStrategy

    Possible values: [BEST_ONLY, BEST_PER_TYPE, ALL_RATES]

    Default value: BEST_ONLY

    How much to narrow down each hotel's rates. BEST_ONLY: only the cheapest overall rate per room group, regardless of type. BEST_PER_TYPE: the cheapest rate per distinct combination of room type, rate plan, cancel policy, meal plan and payment options (a group can still return multiple rates under this strategy). ALL_RATES: every available rate, unfiltered.

    page integer

    Default value: 1

    Page number (1-indexed). Each page returns up to 50 hotels (25 with filterStrategy ALL_RATES) — see totalPages on the response.

    includeUnavailableRoomRates boolean

    When true, room groups also include unavailableRates: rates that were found but aren't currently bookable, with the reason why.

    includePriceBreakdown boolean

    When true, each rate's price also has its breakdown (nights, taxes, discounts). v2.0/orders/checkPrice always returns it.

    language stringnullable

    Language for the texts in the response: pt-BR (default), en-US or es-ES. pt, en and es are also accepted. Carried in the rateToken, so the price check uses it too.

    quotationRequest objectnullable
    buyerName stringrequired

    Full name of the person requesting the quotation.

    buyerEmail stringnullable
    buyerPhone stringnullable
    sendMail booleannullable

    When true, the chatbot flow should send the quotation by email.

    promoCode stringnullable

    Promotional code to search with, up to 64 characters. Sent to suppliers that support it (Omnibees PromotionCode). Rates the code applies to come back with promoCode.

Responses​

Schema
    requestId stringnullable

    Our id for this call, also in the X-Request-Id header. Quote it when contacting support.

    externalRequestId stringnullable

    The externalRequestId of the request, as sent. Absent when it wasn't sent.

    timestamp stringnullable

    When we answered, by our clock: ISO 8601 in UTC, e.g. 2026-11-13T17:32:05.874Z.

    hotels object[]

    List of hotels found with their rates.

  • Array [
  • hotel objectrequired
    id stringrequired

    Internal Niara ID of the hotel.

    name stringrequired

    Hotel name.

    cityName stringnullable

    Name of the hotel's city.

    countryName stringnullable

    Name of the hotel's country.

    address stringnullable

    Hotel address.

    position objectnullable

    Geographic coordinates of the hotel.

    latitude numbernullable

    Latitude of the hotel.

    longitude numbernullable

    Longitude of the hotel.

    imageUrl stringnullable

    URL of the hotel's main image.

    detailsUrl stringnullable

    URL with the hotel's full descriptive content.

    rating integernullable

    Hotel star rating, when known.

    preferred boolean

    Whether this is one of the client's preferred hotels.

    rooms object[]

    One group per distinct occupancy requested, each listing the rooms it serves and its rates.

  • Array [
  • refs string[]required

    The requested rooms (rooms[].ref) this group serves.

    occupancy objectrequired
    adults integerrequired

    Number of adults per room.

    childrenAges integer[]

    Ages of the children per room.

    rates object[]

    Available rates for one room of this occupancy, for the whole stay.

  • Array [
  • rateToken stringrequired

    Token identifying this rate for this occupancy. Pass it to v2.0/orders/checkPrice (one entry per room, so rooms with the same occupancy may reuse it) to re-confirm it before booking. Expires 24 hours after the search.

    roomType objectrequired
    id stringrequired

    Room type ID.

    name stringrequired

    Room type name.

    description stringnullable

    Room description, as the supplier gives it. Only returned by v2.0/orders/checkPrice, not by the search, and left out when it only repeats the name.

    unitsAvailable integernullable

    Rooms of this rate still available: the smallest count over the stay's nights. Absent when the supplier doesn't say.

    price objectrequired
    currency stringnullable

    Currency of every amount in this price (ISO 4217), except payAtProperty.

    base decimalnullable

    Price before taxes, when available.

    taxes decimalnullable

    Tax amount, when available.

    total decimalnullable

    Total value (base + taxes), when available.

    discounts decimalnullable

    Total discount on the rate. Informative: base and total already have it taken off. Absent when there is none.

    commission objectnullable

    What the client earns on this rate. Absent on rates without commission.

    amount decimalrequired

    Commission amount, in the price's currency.

    percentage decimalnullable

    Commission rate, in percent (10.00 is 10%).

    payAtProperty object[]nullable

    Fees the guest pays at the hotel, each in the currency the hotel charges. Never included in total. Only returned by v2.0/orders/checkPrice. Absent when there is none.

  • Array [
  • description stringnullable

    What the fee is, as the supplier names it.

    amount decimalrequired

    Monetary amount.

    currency stringrequired

    Currency the hotel charges the fee in (ISO 4217).

  • ]
  • breakdown objectnullable

    How the price splits up. See PriceBreakdown for when it is returned.

    nights object[]nullable

    Price of each night, in stay order. The nights' base add up to the rate's base. Absent when the supplier doesn't price each night.

  • Array [
  • date stringrequired

    Date of the night (YYYY-MM-DD).

    base decimalrequired

    Price of the night before taxes, in the price's currency.

  • ]
  • taxes object[]nullable

    The taxes in taxes, as the supplier details them. Informative. Absent when not detailed.

  • Array [
  • description stringnullable

    What the amount is, as the supplier names it.

    amount decimalrequired

    Monetary amount, in the price's currency.

  • ]
  • discounts object[]nullable

    The discounts in discounts, as detailed. Informative. Absent when not detailed.

  • Array [
  • description stringnullable

    What the amount is, as the supplier names it.

    amount decimalrequired

    Monetary amount, in the price's currency.

  • ]
  • cancelPolicy objectrequired
    refundable booleannullable

    Whether cancelling can be free at some point. false for non-refundable rates. Absent when unknown.

    currency stringnullable

    Currency of the penalty amounts (ISO 4217). Absent when no step has an amount.

    penalties object[]nullable

    Penalty steps in time order. Before the first step, cancelling is free. Absent when the supplier gives no penalty information.

  • Array [
  • from stringnullable

    When this step starts (ISO 8601 with UTC offset). Absent means from the moment of booking, as for non-refundable rates.

    amount decimalnullable

    What cancelling costs from then on, for this room and the whole stay, in the policy's currency. Absent when the supplier doesn't say.

  • ]
  • description stringnullable

    Cancellation policy as the supplier words it. Only returned by v2.0/orders/checkPrice, not by the search.

    supplier objectnullable
    name stringnullable

    Name of the supplier providing this rate.

    logo stringnullable

    URL of the supplier's logo. Absent when the credential has none on file.

    offers object[]nullable

    Promotional offers applied to the rate.

  • Array [
  • name stringnullable

    Offer name.

    discount numbernullable

    Discount value/percentage.

    freeNights integernullable

    Number of free nights granted by the offer, when applicable.

    discountType nullable

    Possible values: [STAY_DISCOUNT, DISCOUNT, FREE_NIGHT, LAST_MINUTE, null]

    Discount type.

    nightsRequired integernullable

    Nights required to qualify for the offer, when applicable.

  • ]
  • paymentOptions object[]nullable

    Payment/guarantee options available for this rate.

  • Array [
  • id stringrequired

    Payment option ID: pass it as is to v2.0/orders/booking (payments[].paymentOptionId). Opaque: don't parse it.

    type required

    Possible values: [CREDITCARD, PAY_AT_PROPERTY, INVOICE, PAY_LATER]

    CREDITCARD: paid by credit card. PAY_AT_PROPERTY: paid at the hotel, with a card as guarantee. INVOICE: billed to the client account. PAY_LATER: paid after booking, before a deadline. More types may be added: accept values you don't know.

    name stringnullable

    Display name for the payment option.

  • ]
  • mealPlan objectnullable
    meals undefined[]

    Possible values: [breakfast, lunch, dinner]

    Meals included in the rate. An empty list means room only.

    allInclusive booleannullable

    true when the rate is all-inclusive: every meal and usually drinks and more. Absent otherwise.

    name stringnullable

    Meal plan name, as the supplier gives it.

    description stringnullable

    Meal plan description, as the supplier gives it. Only returned by v2.0/orders/checkPrice, not by the search, and left out when it only repeats the name.

    ratePlan objectnullable
    id stringnullable

    Rate plan ID.

    name stringnullable

    Rate plan name.

    public booleannullable

    Whether the rate plan is publicly published.

    package booleannullable

    Whether the rate plan is a package (bundled with extras).

    description stringnullable

    Rate plan description, as the supplier gives it. Only returned by v2.0/orders/checkPrice, not by the search, and left out when it only repeats the name.

    promoCode stringnullable

    Promotional code the supplier applied to this rate (Omnibees PromotionCode). Carried in the rateToken, so the price check and the booking keep it. Absent when no code applies.

    quotationLink stringnullable

    URL to a quotation generated for this specific rate. Only present when quotationRequest was sent, the search was for a single hotel (destination.hotelIds with exactly one ID), and this rate is Omnibees-supplied.

  • ]
  • unavailableRates object[]nullable

    Rates that were found but aren't currently bookable. Only present when includeUnavailableRoomRates was set on the request.

  • Array [
  • id stringrequired

    Rate/room ID. Informational only — cannot be price-checked or booked.

    roomType objectnullable
    id stringrequired

    Room type ID.

    name stringrequired

    Room type name.

    description stringnullable

    Room description, as the supplier gives it. Only returned by v2.0/orders/checkPrice, not by the search, and left out when it only repeats the name.

    reason stringnullable

    Why this rate is unavailable.

    minAdultCount integernullable

    Minimum number of adults required, when the unavailability is an occupancy restriction.

    maxAdultCount integernullable

    Maximum number of adults allowed, when the unavailability is an occupancy restriction.

    minChildCount integernullable

    Minimum number of children required, when the unavailability is an occupancy restriction.

    maxChildCount integernullable

    Maximum number of children allowed, when the unavailability is an occupancy restriction.

    cancelPolicy objectnullable
    refundable booleannullable

    Whether cancelling can be free at some point. false for non-refundable rates. Absent when unknown.

    currency stringnullable

    Currency of the penalty amounts (ISO 4217). Absent when no step has an amount.

    penalties object[]nullable

    Penalty steps in time order. Before the first step, cancelling is free. Absent when the supplier gives no penalty information.

  • Array [
  • from stringnullable

    When this step starts (ISO 8601 with UTC offset). Absent means from the moment of booking, as for non-refundable rates.

    amount decimalnullable

    What cancelling costs from then on, for this room and the whole stay, in the policy's currency. Absent when the supplier doesn't say.

  • ]
  • description stringnullable

    Cancellation policy as the supplier words it. Only returned by v2.0/orders/checkPrice, not by the search.

    ratePlan objectnullable
    id stringnullable

    Rate plan ID.

    name stringnullable

    Rate plan name.

    public booleannullable

    Whether the rate plan is publicly published.

    package booleannullable

    Whether the rate plan is a package (bundled with extras).

    description stringnullable

    Rate plan description, as the supplier gives it. Only returned by v2.0/orders/checkPrice, not by the search, and left out when it only repeats the name.

    mealPlan objectnullable
    meals undefined[]

    Possible values: [breakfast, lunch, dinner]

    Meals included in the rate. An empty list means room only.

    allInclusive booleannullable

    true when the rate is all-inclusive: every meal and usually drinks and more. Absent otherwise.

    name stringnullable

    Meal plan name, as the supplier gives it.

    description stringnullable

    Meal plan description, as the supplier gives it. Only returned by v2.0/orders/checkPrice, not by the search, and left out when it only repeats the name.

    price objectnullable
    currency stringnullable

    Currency of every amount in this price (ISO 4217), except payAtProperty.

    base decimalnullable

    Price before taxes, when available.

    taxes decimalnullable

    Tax amount, when available.

    total decimalnullable

    Total value (base + taxes), when available.

    discounts decimalnullable

    Total discount on the rate. Informative: base and total already have it taken off. Absent when there is none.

    commission objectnullable

    What the client earns on this rate. Absent on rates without commission.

    amount decimalrequired

    Commission amount, in the price's currency.

    percentage decimalnullable

    Commission rate, in percent (10.00 is 10%).

    payAtProperty object[]nullable

    Fees the guest pays at the hotel, each in the currency the hotel charges. Never included in total. Only returned by v2.0/orders/checkPrice. Absent when there is none.

  • Array [
  • description stringnullable

    What the fee is, as the supplier names it.

    amount decimalrequired

    Monetary amount.

    currency stringrequired

    Currency the hotel charges the fee in (ISO 4217).

  • ]
  • breakdown objectnullable

    How the price splits up. See PriceBreakdown for when it is returned.

    nights object[]nullable

    Price of each night, in stay order. The nights' base add up to the rate's base. Absent when the supplier doesn't price each night.

  • Array [
  • date stringrequired

    Date of the night (YYYY-MM-DD).

    base decimalrequired

    Price of the night before taxes, in the price's currency.

  • ]
  • taxes object[]nullable

    The taxes in taxes, as the supplier details them. Informative. Absent when not detailed.

  • Array [
  • description stringnullable

    What the amount is, as the supplier names it.

    amount decimalrequired

    Monetary amount, in the price's currency.

  • ]
  • discounts object[]nullable

    The discounts in discounts, as detailed. Informative. Absent when not detailed.

  • Array [
  • description stringnullable

    What the amount is, as the supplier names it.

    amount decimalrequired

    Monetary amount, in the price's currency.

  • ]
  • ]
  • ]
  • cheapestCombination objectnullable
    total objectrequired

    Sum of the chosen rates over all requested rooms.

    amount decimalrequired

    Monetary amount.

    currency stringrequired

    Currency code (ISO 4217).

    rooms objectrequired

    Room ref → the rateToken to check the price for.

    property name* string
  • ]
  • totalCount integernullable

    Total number of hotels available for the given criteria (before pagination).

    page integernullable

    The page number returned, echoing the request's page.

    totalPages integernullable

    Total number of pages available for the given criteria.

    language stringnullable

    The language actually used for the texts, after normalization.

Loading...