Search
Searching for listings in Calry OTA
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
GET /api/v1/searchDate Filters
| Parameter | Type | Description |
|---|---|---|
| checkInDate | Date | Desired check-in date (YYYY-MM-DD) |
| checkOutDate | Date | Desired check-out date (YYYY-MM-DD) |
Dates must be in the future, and check-out must be after check-in.
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) |
When a location is provided, results include a 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 |
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
| 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 |
| collectionId | string | Restrict results to a collection. If the collection cannot be resolved (unknown, deleted, or not accessible to the requesting tenant), the search returns an empty result set rather than an error — a stale collection reference on a booking site degrades to "no results", never a broken page. |
Pagination
| 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=USDResponse 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/flexibleAdditional 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=2This 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" }
],
...
}
]
}Search by IDs
When you already know which listings you want (for example, rendering a curated set or refreshing prices for a shortlist), post the IDs instead of encoding them in a query string:
POST /api/v1/search/idsThe body accepts listingIDs plus the optional booking criteria checkInDate, checkOutDate, guests, displayCurrency, and pagination (page, limit). The response has the same structure as standard search — availability and pricing are computed for the given dates, and unavailable listings are filtered out.
Destinations
To build a destination picker or map overview, use the portfolio-locations endpoint on the Listing resource:
GET /api/v1/listing/locationsIt returns one entry per distinct city across all of the tenant's active listings (not just one page of search results). Each entry carries the listing count, the centroid of that city's listings, and their bounding box, so a client can center and frame a map on the destination. Results are ordered by listing count descending, capped by limit (default 50, max 200). See List every destination city across the portfolio.
Promotion-Scoped Search
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: