Hotel Availability

POST 
/v2/hotels/availability

Introduction

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

Search destination

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

• 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: the search follows the same internal precedence order used by the availability engine (circleInfo > regionId > hotelIds), using only the first one present.

Pagination

Results are paginated at 50 hotels per page — see page on the request and totalPages on the response.

Request

application/json

Body

destinations 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).

checkout stringrequired

Check-out date (ISO 8601, e.g. 2026-10-02).

occupancy objectrequired

adults integerrequired

Number of adults per room.

children integer

Default value: 0

Number of children per room.

childrenAges integer[]

Ages of the children, one entry per child (must match the children count).

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.

bestOnly boolean

When true, returns only the cheapest rate per hotel/credential.

page integer

Default value: 1

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

includeUnavailableRoomRates boolean

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

locale stringnullable

Desired language/locale for the response's text.

Responses

200

application/json

Schema

Schema

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.
roomRates object[]
Available rates for the hotel, for the searched period/occupancy.
Array [
rateToken stringrequired
Opaque token identifying this rate. Pass it to v2/hotels/checkrate to re-confirm it before booking.
roomType objectrequired
id stringrequired
Room type ID.
name stringrequired
Room type name.
time objectrequired
startDate stringrequired
Rate start date.
endDate stringrequired
Rate end date.
priceComposition objectrequired
net objectnullable
Net value (before taxes), when available.
value numberrequired
Monetary amount.
currency stringrequired
Currency code (ISO 4217).
taxes objectnullable
Tax amount, when available.
value numberrequired
Monetary amount.
currency stringrequired
Currency code (ISO 4217).
total objectnullable
Total value (net + taxes), when available.
value numberrequired
Monetary amount.
currency stringrequired
Currency code (ISO 4217).
cancelPolicy objectrequired
nonRefundable booleannullable
Indicates whether the rate is non-refundable, when known.
inPenalty booleannullable
Indicates whether cancellation is currently within the penalty period.
penaltyDate stringnullable
Date from which cancellation starts incurring a penalty.
paymentOptions object[]nullable
Payment/guarantee options available for this rate.
Array [
type stringrequired
Payment option type (e.g. credit card, PIX, pay-at-hotel).
id stringrequired
Payment option ID.
enabled booleannullable
Whether this payment option is currently usable for this rate, when known.
internalType stringnullable
Internal payment-option classification.
alias stringnullable
Display name for the payment option.
description stringnullable
Human-readable description.
disabledReason stringnullable
Why this option is disabled, when enabled is false.
credentialType stringnullable
Supplier credential type behind this payment option, when relevant.
includeExtraOptions object[]nullable
Extras that can be bundled with this payment option.
Array [
id stringrequired
Extra item ID.
label stringnullable
Extra item label.
]
]
meal objectnullable
breakfast booleannullable
Whether breakfast is included.
lunch booleannullable
Whether lunch is included.
dinner booleannullable
Whether dinner is included.
allInclusive booleannullable
Whether the rate is all-inclusive.
name stringnullable
Meal plan name.
description stringnullable
Meal plan description.
ratePlan objectnullable
id stringnullable
Rate plan ID.
name stringnullable
Rate plan name.
type stringnullable
Rate plan type.
public booleannullable
Whether the rate plan is publicly published.
package booleannullable
Whether the rate plan is a package (bundled with extras).
inclusions object[]nullable
Items included in the rate plan.
Array [
id stringnullable
Inclusion ID.
name stringnullable
Inclusion name.
description stringnullable
Inclusion description.
]
descriptions objectnullable
roomType object[]nullable
Room type descriptions.
Array [
name stringnullable
Description name/title.
description stringnullable
Description text.
]
meal object[]nullable
Meal plan descriptions.
Array [
name stringnullable
Description name/title.
description stringnullable
Description text.
]
ratePlan object[]nullable
Rate plan descriptions.
Array [
name stringnullable
Description name/title.
description stringnullable
Description text.
]
cancelPolicy object[]nullable
Cancellation policy descriptions.
Array [
name stringnullable
Description name/title.
description stringnullable
Description text.
]
generalPolicies object[]nullable
General policy descriptions.
Array [
name stringnullable
Description name/title.
description stringnullable
Description text.
]
payment object[]nullable
Payment-related descriptions.
Array [
name stringnullable
Description name/title.
description stringnullable
Description text.
]
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.
]
]
unavailableRoomRates 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 rechecked via checkrate or booked.
roomType objectnullable
id stringrequired
Room type ID.
name stringrequired
Room type 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
nonRefundable booleannullable
Indicates whether the rate is non-refundable, when known.
inPenalty booleannullable
Indicates whether cancellation is currently within the penalty period.
penaltyDate stringnullable
Date from which cancellation starts incurring a penalty.
ratePlan objectnullable
id stringnullable
Rate plan ID.
name stringnullable
Rate plan name.
type stringnullable
Rate plan type.
public booleannullable
Whether the rate plan is publicly published.
package booleannullable
Whether the rate plan is a package (bundled with extras).
inclusions object[]nullable
Items included in the rate plan.
Array [
id stringnullable
Inclusion ID.
name stringnullable
Inclusion name.
description stringnullable
Inclusion description.
]
meal objectnullable
breakfast booleannullable
Whether breakfast is included.
lunch booleannullable
Whether lunch is included.
dinner booleannullable
Whether dinner is included.
allInclusive booleannullable
Whether the rate is all-inclusive.
name stringnullable
Meal plan name.
description stringnullable
Meal plan description.
priceComposition objectnullable
net objectnullable
Net value (before taxes), when available.
value numberrequired
Monetary amount.
currency stringrequired
Currency code (ISO 4217).
taxes objectnullable
Tax amount, when available.
value numberrequired
Monetary amount.
currency stringrequired
Currency code (ISO 4217).
total objectnullable
Total value (net + taxes), when available.
value numberrequired
Monetary amount.
currency stringrequired
Currency code (ISO 4217).
]
]
searchId stringnullable

Search identifier to be included in the payload of the subsequent calls of the booking flow, useful for correlating them.

count integernullable

Number of hotels returned on this page.

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.

Example (from schema)

{
  "hotels": [
    {
      "hotel": {
        "id": "string",
        "name": "string",
        "cityName": "string",
        "countryName": "string",
        "address": "string",
        "position": {
          "latitude": 0,
          "longitude": 0
        }
      },
      "roomRates": [
        {
          "rateToken": "string",
          "roomType": {
            "id": "string",
            "name": "string"
          },
          "time": {
            "startDate": "string",
            "endDate": "string"
          },
          "priceComposition": {
            "net": {
              "value": 0,
              "currency": "string"
            },
            "taxes": {
              "value": 0,
              "currency": "string"
            },
            "total": {
              "value": 0,
              "currency": "string"
            }
          },
          "cancelPolicy": {
            "nonRefundable": true,
            "inPenalty": true,
            "penaltyDate": "string"
          },
          "paymentOptions": [
            {
              "type": "string",
              "id": "string",
              "enabled": true,
              "internalType": "string",
              "alias": "string",
              "description": "string",
              "disabledReason": "string",
              "credentialType": "string",
              "includeExtraOptions": [
                {
                  "id": "string",
                  "label": "string"
                }
              ]
            }
          ],
          "meal": {
            "breakfast": true,
            "lunch": true,
            "dinner": true,
            "allInclusive": true,
            "name": "string",
            "description": "string"
          },
          "ratePlan": {
            "id": "string",
            "name": "string",
            "type": "string",
            "public": true,
            "package": true,
            "inclusions": [
              {
                "id": "string",
                "name": "string",
                "description": "string"
              }
            ]
          },
          "descriptions": {
            "roomType": [
              {
                "name": "string",
                "description": "string"
              }
            ],
            "meal": [
              {
                "name": "string",
                "description": "string"
              }
            ],
            "ratePlan": [
              {
                "name": "string",
                "description": "string"
              }
            ],
            "cancelPolicy": [
              {
                "name": "string",
                "description": "string"
              }
            ],
            "generalPolicies": [
              {
                "name": "string",
                "description": "string"
              }
            ],
            "payment": [
              {
                "name": "string",
                "description": "string"
              }
            ]
          },
          "offers": [
            {
              "name": "string",
              "discount": 0,
              "freeNights": 0,
              "nightsRequired": 0
            }
          ]
        }
      ],
      "unavailableRoomRates": [
        {
          "id": "string",
          "roomType": {
            "id": "string",
            "name": "string"
          },
          "reason": "string",
          "minAdultCount": 0,
          "maxAdultCount": 0,
          "minChildCount": 0,
          "maxChildCount": 0,
          "cancelPolicy": {
            "nonRefundable": true,
            "inPenalty": true,
            "penaltyDate": "string"
          },
          "ratePlan": {
            "id": "string",
            "name": "string",
            "type": "string",
            "public": true,
            "package": true,
            "inclusions": [
              {
                "id": "string",
                "name": "string",
                "description": "string"
              }
            ]
          },
          "meal": {
            "breakfast": true,
            "lunch": true,
            "dinner": true,
            "allInclusive": true,
            "name": "string",
            "description": "string"
          },
          "priceComposition": {
            "net": {
              "value": 0,
              "currency": "string"
            },
            "taxes": {
              "value": 0,
              "currency": "string"
            },
            "total": {
              "value": 0,
              "currency": "string"
            }
          }
        }
      ]
    }
  ],
  "searchId": "string",
  "count": 0,
  "totalCount": 0,
  "page": 0,
  "totalPages": 0
}

Loading...