---
title: "Search hotels"
method: POST
path: "/v1/hotels/search"
tags: ["Market intelligence"]
---

# Search hotels

`POST /v1/hotels/search`

Searches hotels and vacation rentals for a destination and returns matching properties with rates, ratings, and amenities.

<span>⚡ <strong>Rate limit:</strong> 120 requests per 1 minute</span>

<span>💰 <strong>Cost:</strong> 2 credits per search&nbsp;<span title="Pricing shown is default pricing. Actual pricing may vary.">ⓘ</span></span>

## Request body

- object
  - `apiKey` string, required — Your Fiber API key
  - `query` string, required — Destination or hotel search query (e.g. 'Hotels in Manhattan New York').
  - `checkInDate` string, required — Check-in date for the stay.
  - `checkOutDate` string, required — Check-out date for the stay.
  - `adults` integer — Number of adult guests (at least 1). Total guests (`adults` + `children`) must not exceed 6 for hotels or 10 for vacation rentals.
  - `children` integer — Number of child guests. Total guests (`adults` + `children`) must not exceed 6 for hotels or 10 for vacation rentals.
  - `childrenAges` integer[] — Ages of each child guest. Must contain exactly `children` entries when `children` is greater than zero.
  - `sortBy` 'relevance' | 'lowestPrice' | 'highestRating' | 'mostReviewed' | 'null', nullable — Sort criterion for results. 'relevance' ranks by overall match. 'lowestPrice' sorts cheapest first. 'highestRating' sorts by guest rating. 'mostReviewed' sorts by review count. Omit to sort by relevance.
  - `minRating` '3.5' | '4.0' | '4.5' | 'null', nullable — Minimum guest rating filter. Omit to include all ratings.
  - `priceRange` object, nullable — Filter by nightly price range in whole currency units.
    - `minPerNight` integer, nullable — Minimum nightly rate in whole currency units.
    - `maxPerNight` integer, nullable — Maximum nightly rate in whole currency units.
  - `category` union — Property category and its category-specific filters. 'hotel' accepts hotel filters (star class, property types, amenities, brands, and the free-cancellation/special-offers/eco-certified toggles); 'vacationRental' accepts bedroom/bathroom minimums. Defaults to a plain hotel search when omitted.
    - object
      - `propertyCategory` 'hotel', required — Search hotels (the default property category).
      - `hotelStarClasses` integer[], nullable — Filter to specific hotel star classes based on how upscale the property is (e.g. [4, 5] for 4- and 5-star hotels). This is not a guest review rating.
      - `propertyTypes` integer[], nullable — Filter to specific property types by ID. Call GET /v1/enums/hotels/property-types for valid values.
      - `amenities` integer[], nullable — Require properties that offer all of these amenities by ID. Call GET /v1/enums/hotels/amenities for valid values.
      - `brands` integer[], nullable — Filter to specific hotel brands by ID. Call GET /v1/enums/hotels/brands for valid values.
      - `freeCancellation` boolean — When true, only return properties with a booking option that can be cancelled without a cancellation fee.
      - `specialOffers` boolean — When true, only return properties marked by the booking provider as having a special offer or promotion.
      - `ecoCertified` boolean — When true, only return properties marked by the booking provider as having an environmental or sustainability certification.
    - object
      - `propertyCategory` 'vacationRental', required — Search vacation rentals instead of hotels.
      - `minBedrooms` integer, nullable — Minimum number of bedrooms.
      - `minBathrooms` integer, nullable — Minimum number of bathrooms.
  - `nextPageToken` string, nullable — Opaque pagination token from a prior search response's `nextPageToken`. Omit (or pass null) to fetch the first page.
  - `currencyCode` string — ISO 4217 currency code for prices in the response (e.g. 'EUR', 'GBP', 'CAD'). Case-insensitive. Defaults to USD.
  - `searchMarketCountryCode` string — ISO 3166-1 alpha-3 country code that sets the search market (e.g. 'GBR', 'BRA'). This affects regional pricing and availability. Case-insensitive.
  - `languageCode` string — Language for results such as property names and amenity labels. Pass a BCP-47 language tag such as 'en', 'en-US', 'pt-BR', 'zh-CN', 'ja', 'ko', 'fr', 'de', or 'es'. Defaults to en.

## Response `200`

Default Response

- object
  - `output` object, required
    - `properties` object[], required — Matching hotel and vacation rental properties.
      - `type` 'hotel' | 'vacationRental' | 'null', nullable — Property category.
      - `propertyToken` string, required — Opaque token identifying this property. Pass as `propertyToken` in POST /v1/hotels/property to retrieve full details. Always present on returned properties.
      - `name` string, required — Property display name.
      - `description` string, nullable — Property description.
      - `url` string, nullable — Property website URL.
      - `coordinates` object, nullable — Geographic coordinates of the property in decimal degrees.
        - `latitude` number, required — Latitude in decimal degrees.
        - `longitude` number, required — Longitude in decimal degrees.
      - `city` string, nullable — City name.
      - `countryCode` string, nullable — ISO 3166-1 alpha-3 country code (e.g. 'USA').
      - `checkInTime` string, nullable — Check-in time in 24-hour `HH:mm` format, where `HH` is 00 through 23 (e.g. '15:00'). Null when unavailable.
      - `checkOutTime` string, nullable — Check-out time in 24-hour `HH:mm` format, where `HH` is 00 through 23 (e.g. '11:00'). Null when unavailable.
      - `ratePerNight` object, nullable — Nightly rate summary for one night.
        - `currencyCode` string, required — ISO 4217 currency code for the amounts in this rate.
        - `allInCost` integer, nullable — All-in cost in whole currency units, including taxes and fees. Null when only a pre-tax rate is available, in which case only `baseCost` is populated.
        - `baseCost` integer, nullable — Base cost before taxes and fees in whole currency units; this is not the final amount charged.
      - `totalRate` object, nullable — Total rate summary for the entire requested stay, from check-in through check-out. The all-in amount includes taxes and fees when supplied; otherwise `baseCost` is provided.
        - `currencyCode` string, required — ISO 4217 currency code for the amounts in this rate.
        - `allInCost` integer, nullable — All-in cost in whole currency units, including taxes and fees. Null when only a pre-tax rate is available, in which case only `baseCost` is populated.
        - `baseCost` integer, nullable — Base cost before taxes and fees in whole currency units; this is not the final amount charged.
      - `rating` number, nullable — Guest rating from 0 to 5.
      - `reviewCount` integer, nullable — Total number of guest reviews.
      - `reviewsBreakdown` object[], required — Breakdown of reviews by category.
        - `name` string, nullable — Review category name.
        - `description` string, nullable — Review category description.
        - `totalCount` integer, nullable — Total reviews mentioning this category.
        - `positiveCount` integer, nullable — Positive mentions for this category.
        - `neutralCount` integer, nullable — Neutral mentions for this category.
        - `negativeCount` integer, nullable — Negative mentions for this category.
      - `hotelStarClass` integer, nullable — Observed hotel star class indicating how upscale the property is, from 1 to 5 whole stars. This is a property classification, not a guest review rating.
      - `amenities` string[], required — Amenities offered by this property.
      - `excludedAmenities` string[], required — Amenities explicitly not offered.
      - `images` object[], required — Property images.
        - `thumbnailUrl` string, nullable — Thumbnail image URL.
        - `originalUrl` string, nullable — Full-size image URL.
      - `nearbyPlaces` object[], required — Notable nearby places and transit options.
        - `name` string, nullable — Nearby place name.
        - `transportations` object[], required — Transportation options to reach this place.
          - `type` string, nullable — Transportation mode (e.g. 'Walking').
          - `durationMinutes` integer, nullable — Travel duration in minutes.
      - `locationRating` number, nullable — Location quality rating from 0 to 5.
      - `deal` string, nullable — Deal label when the booking provider marks a promotion; may be present without `dealDescription`.
      - `dealDescription` string, nullable — Short deal description when supplied by the booking provider; may be absent even when `deal` is present.
      - `essentialInfo` string[], required — Key facts for vacation rentals (e.g. 'Entire apartment', 'Sleeps 4').
    - `brands` object[], required — Hotel brand groups available for filtering in this market. Empty when searching vacation rentals only.
      - `id` integer, required — Brand group identifier.
      - `name` string, required — Brand group display name.
      - `children` object[], required — Sub-brands within this group.
        - `id` integer, required — Brand identifier.
        - `name` string, required — Brand display name.
    - `nextPageToken` string, nullable — Token to retrieve the next page. Pass as `nextPageToken` in the next request. Null if no more pages.
    - `currencyCode` string, nullable — ISO 4217 currency code for prices in this response (e.g. 'USD', 'EUR', 'GBP').
    - `searchInformation` object, nullable — Summary information about the search results.
      - `totalResultCount` integer, nullable — Approximate total number of matching properties.
  - `chargeInfo` union, required
    - object — Credits were charged immediately for this operation
      - `method` 'charged-now', required
      - `creditsCharged` number, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
    - object — Credits will be charged after the operation completes
      - `method` 'charging-later', required
      - `message` string, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
    - object — Credits that were charged for an asynchronous operation
      - `method` 'charged-for-async-process', required
      - `creditsCharged` number, required
      - `message` string, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
    - object — No credits were charged for this operation
      - `method` 'free', required
      - `message` string, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
    - object — Credits were refunded for this operation
      - `method` 'credits-refunded', required
      - `creditsRefunded` number, required
      - `message` string, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
  - `warnings` object[], nullable — Warnings about extraneous fields in request
    - `field` string, required — Full path to extraneous field (e.g., 'searchParams.ExtraField')
    - `message` string, required — Warning message
  - `advice` string[], nullable — Tips, recommendations, and suggestions for using this API effectively.

## Other responses

- `400` — Default Response
- `401` — Default Response
- `402` — Default Response
- `403` — Default Response
- `404` — Default Response
- `422` — Default Response
- `429` — Default Response
- `500` — Default Response
- `503` — Default Response

---

[API](https://skmtc.net/fiber/apis/fiber-ai-api.md) · [All operations](https://skmtc.net/fiber/apis/fiber-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fiber/fiber-ai-api/versions/0c537984b99f/schema)