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.

We consider data sources including Google Hotels. What you get back is similar to results you may find on Expedia, Hotwire, Booking.com, Trivago, and other online travel agencies — inventory, nightly rates, guest ratings, and booking links — returned as JSON instead of a booking-site page.

There is no start/poll pair. Search and property detail are both synchronous.

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.

Search (hotelSearch)

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 getHotelBrands include Marriott, Hilton, Hyatt, and IHG (and their sub-brands).

Pagination

hotelSearch 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 (hotelProperty)

Get propertyToken from a hotelSearch 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)

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

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 (getHotelPropertyTypes) — pass id values in category.propertyTypes. Agent markdown: getHotelPropertyTypes.md.

Amenities

GET /v1/enums/hotels/amenities (getHotelAmenities) — pass id values in category.amenities. Every listed ID must be present on the property. Agent markdown: getHotelAmenities.md.

Brand groups

GET /v1/enums/hotels/brands (getHotelBrands) — pass a group id or a child id in category.brands. The endpoint also returns children (sub-brands). Agent markdown: getHotelBrands.md.

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.
• 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

Empty result pages still bill as a search. Trust chargeInfo on the response for the amount charged. See Billing & credits.

Related: Market intelligence · MCP · SDKs