Skip to main content

​
Introduction

The Search API allows you to find available listings based on a combination of dates, location, guest requirements, amenities, and other filters. There are two search modes: standard search with fixed dates and flexible date search for discovering availability across date ranges. 
GET /api/v1/search

​
Date Filters

ParameterTypeDescription
checkInDateDateDesired check-in date (YYYY-MM-DD)
checkOutDateDateDesired check-out date (YYYY-MM-DD)
Dates must be in the future, and check-out must be after check-in.

​
Location Filters

ParameterTypeDescription
locationstringLatitude and longitude as lat,lng (e.g., 40.7128,-74.0060)
radiusnumberSearch radius in kilometers (required if location is provided)
When a location is provided, results include a distance field showing how far each listing is from the search point.

​
Guest & Property Filters

ParameterTypeDescription
guestsnumberMinimum guest capacity required
bedroomCountnumberMinimum number of bedrooms
bathroomCountnumberMinimum number of bathrooms
petFriendlybooleanFilter for pet-friendly properties
propertyTypearrayFilter by property types

​
Amenity Filters

ParameterTypeDescription
amenitiesstringComma-separated list of amenity IDs
When amenity IDs are provided, only listings that have all specified amenities are returned. Setting petFriendly=true automatically adds the pet-friendly amenity to the filter.

​
Price Filters

ParameterTypeDescription
minPricenumberMinimum average nightly price
maxPricenumberMaximum average nightly price
displayCurrencystringISO 4217 currency code for price display

​
Additional Filters

ParameterTypeDescription
tagsarrayFilter by tag IDs (returns listings with any of the specified tags)
promotionIDUUIDFilter to listings assigned to a specific promotion
promotedbooleanFilter to only promoted listings
listingIDsarrayRestrict search to specific listing IDs

​
Pagination

ParameterTypeDefaultDescription
pagenumber1Page number
limitnumber50Results per page (max 100)

​
Example Request

GET /api/v1/search?checkInDate=2025-07-01&checkOutDate=2025-07-05&location=40.7128,-74.0060&radius=25&guests=2&amenities=pool,wifi&displayCurrency=USD

​
Response Structure

The response includes:
  • listings — Array of matching listings with details (name, description, location, pricing, amenities, tags, promotion info)
  • meta — Pagination info (count, limit, current page, total pages)
  • The echoed search parameters (checkInDate, checkOutDate, location, etc.)
Each listing in the results includes:
  • Basic info (name, description, address, pictures)
  • Property details (bedrooms, bathrooms, max occupancy)
  • Pricing (average nightly price in the requested currency)
  • Rating (average rating and review count)
  • Tags applied to the listing
  • Promotion status and discount value (if applicable)
  • Price modifications breakdown (default discount, markup, promotion discount)
For guests with flexible travel dates, the flexible search endpoint returns available date ranges for each listing: 
GET /api/v1/search/flexible

​
Additional Parameters

ParameterTypeDescription
flexibilitystringDuration format: {number}_{UNIT} where UNIT is DAY, WEEKEND, WEEK, MONTH, or YEAR
searchRangearrayDate ranges to search, format: YYYY-MM-DD_YYYY-MM-DD

​
Flexibility Values

ValueDuration
1_DAY1 day
1_WEEKEND2 days
1_WEEK7 days
1_MONTH30 days
2_WEEK14 days

​
Example Request

GET /api/v1/search/flexible?flexibility=1_WEEK&searchRange=2025-07-01_2025-07-31,2025-08-01_2025-08-31&location=40.7128,-74.0060&radius=25&guests=2
This searches for listings available for a 1-week stay within July or August 2025.

​
Response

The flexible search response has the same structure as standard search, with the addition of a dateRanges field on each listing containing the available date ranges: 
{
  "listings": [
    {
      "id": "...",
      "name": "Beachfront Villa",
      "dateRanges": [
        { "from": "2025-07-05", "to": "2025-07-12" },
        { "from": "2025-07-19", "to": "2025-07-26" },
        { "from": "2025-08-02", "to": "2025-08-09" }
      ],
      ...
    }
  ]
}
When searching with a promotionID, the search is automatically constrained to:
  • Only listings assigned to that promotion
  • Only dates within the promotion’s booking period
If no dates are provided with a promotion search, the system defaults to the promotion’s bookingPeriodStart with a 3-day stay.

​
API Reference

For detailed API documentation, refer to the following endpoints: