Documentation Index
Fetch the complete documentation index at: https://ota-docs.calry.app/llms.txt
Use this file to discover all available pages before exploring further.
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.
Standard Search
Date Filters
| Parameter | Type | Description |
|---|
| checkInDate | Date | Desired check-in date (YYYY-MM-DD) |
| checkOutDate | Date | Desired check-out date (YYYY-MM-DD) |
Location Filters
| Parameter | Type | Description |
|---|
| location | string | Latitude and longitude as lat,lng (e.g., 40.7128,-74.0060) |
| radius | number | Search radius in kilometers (required if location is provided) |
distance field showing how far each listing is from the search point.
Guest & Property Filters
| Parameter | Type | Description |
|---|
| guests | number | Minimum guest capacity required |
| bedroomCount | number | Minimum number of bedrooms |
| bathroomCount | number | Minimum number of bathrooms |
| petFriendly | boolean | Filter for pet-friendly properties |
| propertyType | array | Filter by property types |
Amenity Filters
| Parameter | Type | Description |
|---|
| amenities | string | Comma-separated list of amenity IDs |
petFriendly=true automatically adds the pet-friendly amenity to the filter.
Price Filters
| Parameter | Type | Description |
|---|
| minPrice | number | Minimum average nightly price |
| maxPrice | number | Maximum average nightly price |
| displayCurrency | string | ISO 4217 currency code for price display |
Additional Filters
| Parameter | Type | Description |
|---|
| tags | array | Filter by tag IDs (returns listings with any of the specified tags) |
| promotionID | UUID | Filter to listings assigned to a specific promotion |
| promoted | boolean | Filter to only promoted listings |
| listingIDs | array | Restrict search to specific listing IDs |
| Parameter | Type | Default | Description |
|---|
| page | number | 1 | Page number |
| limit | number | 50 | Results 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)
Flexible Date Search
For guests with flexible travel dates, the flexible search endpoint returns available date ranges for each listing:
GET /api/v1/search/flexible
Additional Parameters
| Parameter | Type | Description |
|---|
| flexibility | string | Duration format: {number}_{UNIT} where UNIT is DAY, WEEKEND, WEEK, MONTH, or YEAR |
| searchRange | array | Date ranges to search, format: YYYY-MM-DD_YYYY-MM-DD |
Flexibility Values
| Value | Duration |
|---|
1_DAY | 1 day |
1_WEEKEND | 2 days |
1_WEEK | 7 days |
1_MONTH | 30 days |
2_WEEK | 14 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
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" }
],
...
}
]
}
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:
