Search

GET/api/v1/search

Returns the listings that match the stay and filters, with availability-aware prices and cancellation terms. Search and pricing explains how to use the prices.

Query parameters

Every parameter is optional. Send checkInDate and checkOutDate together to search for a stay. radius is required when you send location.

Parameter	Type	Description
`checkInDate`	date	Check-in date, `YYYY-MM-DD`.
`checkOutDate`	date	Check-out date, `YYYY-MM-DD`. At least one day after check-in.
`guests`	integer	Party size. Minimum `1`.
`location`	string	Center of the search as `latitude,longitude`, for example `48.8566,2.3522`.
`radius`	number	Radius in kilometers. Above `0`.
`amenities`	string list	Comma-separated amenity IDs. A listing must have all of them.
`petFriendly`	boolean	`true` returns pet-friendly listings only.
`bedroomCount`	integer	Minimum bedrooms. Minimum `0`.
`bathroomCount`	integer	Minimum bathrooms. Minimum `0`.
`propertyType`	string list	Comma-separated categories, for example `Apartment,House,Hotel,Villa`.
`minPrice`	number	Minimum average nightly price in the display currency.
`maxPrice`	number	Maximum average nightly price in the display currency.
`displayCurrency`	string	ISO 4217 currency for every price.
`listingIDs`	UUID list	Comma-separated listing IDs to limit the search to. For many IDs, use Search by IDs.
`tags`	UUID list	Comma-separated tag IDs. A listing with any of them matches.
`page`	integer	Page number. Default `1`.
`limit`	integer	Results per page. Default `50`, maximum `100`.

Example

curl --get "https://zepl-staging.calry.app/api/v1/search" \
  --header "x-calry-api-key: <API_KEY>" \
  --data-urlencode "checkInDate=2026-12-02" \
  --data-urlencode "checkOutDate=2026-12-05" \
  --data-urlencode "guests=4" \
  --data-urlencode "location=48.8566,2.3522" \
  --data-urlencode "radius=25" \
  --data-urlencode "amenities=wifi,kitchen" \
  --data-urlencode "displayCurrency=EUR"

{
  "checkInDate": "2026-12-02",
  "checkOutDate": "2026-12-05",
  "location": "48.8566,2.3522",
  "radius": 25,
  "guests": 4,
  "amenities": ["wifi", "kitchen"],
  "listings": [
    {
      "id": "80e0e6d4-48cf-4ca7-8c85-6e8d7e9d969a",
      "providerID": "staging-property-101",
      "integrationAccountID": "50bfb7a4-cbc4-4c33-a8c8-37ba9a75c96d",
      "name": "Staging Apartment",
      "description": "Two-bedroom apartment available for API testing.",
      "address": {
        "city": "Paris",
        "line1": "10 Example Street",
        "line2": "",
        "state": "Ile-de-France",
        "country": "France",
        "postal_code": "75001"
      },
      "thumbnailURL": "https://example.com/images/staging-apartment.jpg",
      "pictures": [
        { "url": "https://example.com/images/staging-apartment-1.jpg", "description": "Living room" }
      ],
      "rating": { "count": 12, "average": 4.7 },
      "maxOccupancy": 4,
      "currency": "EUR",
      "latitude": 48.8566,
      "longitude": 2.3522,
      "bedroomCount": 2,
      "bathroomCount": 1,
      "avgNightlyPrice": 132,
      "totalPrice": 486,
      "distance": 1.8,
      "tags": [],
      "isPromoted": false,
      "amenities": {
        "categories": {
          "General": {
            "categoryID": "general",
            "values": [
              { "id": "wifi", "name": "Wi-Fi" },
              { "id": "kitchen", "name": "Kitchen" }
            ]
          }
        }
      },
      "priceModifications": {
        "defaultDiscount": { "percentage": 0, "value": 0 },
        "markup": { "percentage": 10, "value": 12 }
      },
      "cancellationPolicy": {
        "policyID": null,
        "name": "Non-refundable",
        "version": null,
        "source": "DEFAULT",
        "salesChannel": "acme",
        "timeZone": "Europe/Paris",
        "fixedAt": "2026-11-10T10:00:00.000Z",
        "refundable": false,
        "refundableTag": "NRFN",
        "freeCancellationUntil": null,
        "penalties": [
          { "from": "2026-11-10T10:00:00.000Z", "percentage": 100, "amount": 486, "currency": "EUR" }
        ],
        "description": "Non-refundable: no refund if cancelled."
      }
    }
  ],
  "meta": { "total": 1, "limit": 50, "totalPages": 1, "current": 1 }
}

The values are examples. Staging content, prices, and availability change.

Response

Field	Type	Description
`checkInDate`, `checkOutDate`	string	Stay dates used, when sent.
`location`, `radius`	string, number	Search center and radius used, when sent.
`guests`	number	Party size used, when sent.
`amenities`	string array	Amenity IDs used, when sent.
`listings`	array	Matching listings. See below.
`meta`	object	Pagination metadata.

Listing result

Field	Type	Description
`id`	UUID	OnSeason listing ID. Use it in quotes and reservations.
`providerID`	string	Listing ID in the source PMS.
`integrationAccountID`	UUID	The property's connected PMS account.
`name`, `description`	string	Title and description.
`address`	object	`city`, `line1`, `line2`, `state`, `country`, and `postal_code`.
`thumbnailURL`, `pictures`	string, array	Main image and images.
`rating`	object	`average` and `count`, when available.
`maxOccupancy`	number	Maximum number of guests, when available.
`latitude`, `longitude`	number	Coordinates.
`bedroomCount`, `bathroomCount`	number	Layout.
`currency`	string	Currency of every price on the result.
`avgNightlyPrice`	number	Average nightly price for the stay, with your channel's markup. Leaves out fees and taxes when `totalPrice` is absent.
`totalPrice`	number	Full price of the stay with fees, taxes, and markup, rounded up to a whole unit. Present only when OnSeason can rebuild the PMS's quote for the stay.
`priceModifications`	object	`defaultDiscount` and `markup` already applied, each with `percentage` and `value`. Discount values are negative and markup values are positive.
`distance`	number	Kilometers from `location`, for location searches.
`bookableCapacity`	number	Guests the property can host across the rooms free for the stay. `MULTI_UNIT` and `COMPLEX` only.
`roomsForParty`	number	Fewest rooms that seat the party. Above `1`, `avgNightlyPrice` is per room.
`amenities`	object	Amenities grouped by category.
`tags`	array	Tags on the listing.
`isPromoted`	boolean	Whether the listing is promoted.
`cancellationPolicy`	object	The cancellation terms a quote for this stay returns, with amounts based on the search price. Present only when you send both dates.

Status codes

Status	Meaning
`200`	Search completed. An empty `listings` array is a valid result.
`400`	A parameter is invalid.
`401`	The API key is missing or invalid.

Query parameters

Example

Response

Listing result

Status codes

On this page