Hotels API

We built hotel search so you can ask "what's available in this city for these dates?" and get priced, rated properties back — then open one property for the full page: amenities, photos, nearby places, and booking offers with links. Same authenticated API as the rest of Fiber; billed per request via chargeInfo.

What you get back is what you'd see on a major online travel agency (inventory, nightly rates, guest ratings, and booking links), returned as JSON instead of a booking-site page. Need Booking.com listings specifically? See Booking.com search.

There is no start/poll pair. Search and property detail are both synchronous, and both are live: every call fetches current rates and availability for your dates, so you never price a stay off a stored copy.

What it does

1. Search a destination for hotels or vacation rentals on a check-in / check-out window.
2. Filter by price, guest rating, star class, amenities, brands, or (for rentals) bedrooms and bathrooms.
3. Open one property for address, phone, photos, amenity detail, typical price range, and booking offers.

Typical agent prompt this answers: "Find a well-rated hotel under $200 in Austin next week, then give me the booking links."

Operations

The API reference is the primary spec. Each operation also has markdown for agents at /ai-docs/<operationId>.md.

Enum GETs are free. Search and property lookups are chargeable.

Latency and timeouts

Because every call is a live lookup, a hotel request takes longer than a stored-data lookup elsewhere in the API. Most searches and property lookups come back in a few seconds, and a slow one can take noticeably longer, so set your client timeout to 60 seconds and show a loading state rather than blocking a user on the first page.

• Fetch the first page, render it, and page further only when the user asks.
• Run property detail calls in parallel (within the rate limit below) when you need several properties at once.
• Cache results on your side for as long as a quote stays useful to you; every repeat call is a new paid lookup.

Search

Required: query, checkInDate, checkOutDate (ISO YYYY-MM-DD). Check-out must be at least one calendar day after check-in. Check-in must be today or a future date.

Defaults: adults: 2, children: 0, currencyCode: "USD", searchMarketCountryCode: "USA" (ISO 3166-1 alpha-3), languageCode: "en".

Prices are not always USD. Pass currencyCode as an ISO 4217 code (EUR, GBP, CAD, …). Every rate object and typicalPriceRange repeats that code as currencyCode, and the search/property envelope also returns a top-level currencyCode. Default is USD when you omit it.

import { hotelSearch } from "@fiberai/sdk";

const result = await hotelSearch({
  body: {
    apiKey: process.env.FIBER_API_KEY!,
    query: "Hotels in Austin Texas",
    checkInDate: "2027-06-10",
    checkOutDate: "2027-06-12",
    adults: 2,
    sortBy: "lowestPrice",
    minRating: "4.0",
    priceRange: { maxPerNight: 200 },
    category: {
      propertyCategory: "hotel",
      hotelStarClasses: [4, 5],
      amenities: [35],
      freeCancellation: true,
    },
  },
});

console.log("Matches:", result.data?.output.searchInformation?.totalResultCount);
console.log("First stay total:", result.data?.output.properties[0]?.totalRate);
console.log("Cost:", result.data?.chargeInfo);

Equivalent REST body:

{
  "apiKey": "YOUR_API_KEY",
  "query": "Hotels in Austin Texas",
  "checkInDate": "2027-06-10",
  "checkOutDate": "2027-06-12",
  "adults": 2,
  "sortBy": "lowestPrice",
  "minRating": "4.0",
  "priceRange": { "maxPerNight": 200 },
  "category": {
    "propertyCategory": "hotel",
    "hotelStarClasses": [4, 5],
    "amenities": [35],
    "freeCancellation": true
  }
}

Hotels vs vacation rentals

category picks the listing type. Omit it and you get a hotel search.

Hotel-only filters do not apply to vacation rentals, and bedroom/bathroom minimums do not apply to hotels.

Star class is how upscale the property is, not the guest review score. Guest rating is minRating on input ("3.5" | "4.0" | "4.5") and rating (0–5) on each result.

Sort and locale

sortBy: relevance (default), lowestPrice, highestRating, mostReviewed.

languageCode is a BCP-47 tag such as en, pt-BR, or ja — it affects names and amenity labels. searchMarketCountryCode sets the search market (regional pricing and availability), not a geographic fence around query.

When children is greater than zero, childrenAges must have exactly that many ages, each 1–17.

What a search result contains

Each item in properties includes propertyToken, name, optional description/URL/coordinates/city/countryCode, check-in/out times (HH:mm), ratePerNight and totalRate, guest rating / reviewCount / reviewsBreakdown, hotelStarClass, amenity lists, images, nearby places, and optional deal labels. Vacation rentals may also return essentialInfo (for example "Entire apartment", "Sleeps 4").

Rates use whole currency units in the requested currencyCode:

• allInCost — taxes and fees included, when available
• baseCost — pre-tax; not the final amount charged to a guest

Search also returns brands (useful for subsequent brand filters; empty on vacation-rental-only searches), currencyCode, and searchInformation.totalResultCount (approximate). Major groups you can narrow to via the brand ID list include Marriott, Hilton, Hyatt, and IHG (and their sub-brands).

Pagination

Hotels search pages with nextPageToken (not the nextCursor used on people/company search). Pass the token from the previous response on the next request, with the same query and filters. Omit it (or pass null) for the first page. Null means there are no more pages. Each page is a separate charged search.

Property detail

Get propertyToken from a hotels search result, then pass it here. Do not invent one.

import { hotelProperty } from "@fiberai/sdk";

const detail = await hotelProperty({
  body: {
    apiKey: process.env.FIBER_API_KEY!,
    propertyToken: "PROPERTY_TOKEN_FROM_SEARCH",
    checkInDate: "2027-06-10",
    checkOutDate: "2027-06-12",
    adults: 2,
  },
});

const property = detail.data?.output.property;
console.log(property?.address, property?.phone);
console.log("Offers:", property?.offers.length);

The detail payload extends the search property with:

• address, E.164 phone, directionsUrl
• amenitiesDetailed
• offers — booking sources (sourceName, url, isOfficial, nightly and stay totals). The url is an external booking link; Fiber does not complete the reservation.
• typicalPriceRange (lowerBound / upperBound, plus currencyCode)
• ratingsBreakdown (counts of 1-star through 5-star reviews)

A propertyToken identifies the property, not the stay, so you can store it and call property detail again later with different dates.

HTTP 404 means that propertyToken did not match a property. Hotels still bill that lookup — it is not refunded. (A 404 is not "you forgot to search first"; search does not require a token.) If a token you stored starts returning 404, run the search again to get a fresh one.

Building a hotel catalog

A common pattern is a catalog of properties you keep on your side (names, locations, star class, amenities) plus live rates on demand. You can build it with these two operations:

1. Collect properties. Run searches by destination for a representative stay (any future dates) and page through every result. Store each property's propertyToken with the static fields you need: name, coordinates, hotelStarClass, amenities, rating.
2. Price on demand. When a user picks dates, call property detail with the stored token and their stay to get current rates, offers, and booking links.
3. Refresh the catalog on a slow cadence (monthly, say) to pick up new properties and retire ones that stop resolving.

Each search page and each property lookup is a paid call, so size the collection step before you run it: a city usually takes a few pages, a country many. Need static hotel data for a large region in bulk? Talk to us at adi@fiber.ai.

Filter enums

These lists are what the enum endpoints return today. Prefer the live endpoints if you need a fresh copy.

Property types

GET /v1/enums/hotels/property-types returns the property-type IDs. Pass id values in category.propertyTypes.

Amenities

GET /v1/enums/hotels/amenities returns the amenity IDs. Pass id values in category.amenities; every listed ID must be present on the property.

Brand groups

GET /v1/enums/hotels/brands returns the brand IDs. Pass a group id or a child id in category.brands. The endpoint also returns children (sub-brands).

Using it effectively

• Pull filter IDs from the enum endpoints above instead of hard-coding guessed numbers.
• Tighten with priceRange, minRating, and freeCancellation before you page. Broad destination queries plus many pages burn credits fast.
• Keep query as a destination or property name people would type ("Hotels in Manhattan New York"), not a paragraph of constraints — put constraints in the typed filters.
• Honor HTTP 429 (this route allows 120 requests / minute). Temporary failures return 503 with a retry message and an errorCode for support; a failed call isn't charged, so retrying after a short wait is safe.
• Wire these into MCP if an agent should search stays and open a property without leaving the editor.

Use cases

• Travel-app backends: search a city → show a list → property page with booking links.
• Per-trip price checks: same query and dates on a schedule; compare totalRate.allInCost. Each check is a paid call, so pick a cadence that matches how often you actually need a new quote.
• Agent workflows: "hotel under $200, 4.0+, free cancellation, Austin".
• Deal research: filter specialOffers or read deal / dealDescription on results.

Credits

Listed credits are defaults — custom pricing is available for bulk use cases.

Empty result pages still bill as a search. A request that fails (a 503) or is rejected before the lookup runs is refunded in full; a property 404 is billed. Trust chargeInfo on the response for the amount charged. See Billing & credits.

Related: Market intelligence · MCP · SDKs