hotels

Search real, bookable hotel rates — look-to-book priced

Every rate type is returned, refundable and non-refundable; each offer says which (refundable, free_cancellation_until, cancellation_policy). price is what the guest is charged, in the requested currency (USD by default). Nothing is added at booking.

Look-to-book billing: free up to 1,000 searches since your last successful hotel booking. Past that allowance, searches are sold in blocks of 1,000 for $5.00, debited from your prepaid developer balance the moment you cross the current allowance. Booking a hotel resets the free hotel allowance back to 1,000 (the flight allowance is separate); a search counts only when it returns bookable rates. A connected payment method is required for every search regardless of allowance.

post/hotels/search

Request

  • Base URL: https://letsfg.co/developers/api/v1
  • URL: https://letsfg.co/developers/api/v1/hotels/search
  • Auth: API key in header X-API-Key

Request body

city_idinteger required

TBO city id, from POST /hotels/destinations.

city_namestring required
check_instring date required
check_outstring date required
adultsinteger
childreninteger
child_agesinteger[] nullable
nationalitystring

Guest nationality, used for rate eligibility.

currencystring

ISO code every price is quoted in. USD unless asked; PLN is the supplier currency and needs no conversion.

limitinteger
with_imagesboolean
amenitiesstring[] nullable

Canonical amenity ids, e.g. ["spa", "parking"]. A hotel must have all of them.

max_total_pricenumber nullable

Drop offers whose price is above this.

max_distance_kmnumber nullable

Keep hotels within this radius of near (the city centre when near is omitted).

nearstring nullable

Landmark or place name to measure max_distance_km from.

dietary_hintstring nullable

Free text such as "vegan". A best-effort text match against hotel descriptions, not verified data; see caveats.

room_flexibleboolean

Also try splitting the party across several rooms.

Example request

{
  "city_id": 148614,
  "city_name": "Warsaw, Poland",
  "check_in": "2026-11-10",
  "check_out": "2026-11-12",
  "adults": 2,
  "currency": "USD"
}

Response

Bookable hotel offers.

session_idstring

The search session. Each offer carries its own session_id; send the one on the chosen offer to POST /hotels/book.

currencystring

The currency every price is in.

supplier_currencystring
fx_ratenumber nullable
fx_as_ofstring nullable

When the exchange rate was published.

countinteger
termsobject

Cancellation ladder and booking terms shown to the guest.

caveatsstring[]

Anything a filter could not honour, in plain words.

Example response

{
  "supplier_currency": "PLN",
  "hotels": [
    {
      "offers": [
        {
          "supplier_currency": "PLN"
        }
      ]
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.