Skip to main content
GET
/
api
/
v1
/
search
Search for listings
curl --request GET \
  --url https://api.example.com/api/v1/search \
  --header 'x-calry-api-key: <api-key>'
{
  "checkInDate": "2025-06-15",
  "checkOutDate": "2025-06-22",
  "listings": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "providerID": "3827197",
      "integrationAccountID": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Cozy Apartment with Ocean View",
      "currency": "USD",
      "latitude": 37.7749,
      "longitude": -122.4194,
      "bedroomCount": 2,
      "bathroomCount": 1.5,
      "avgNightlyPrice": 150,
      "priceModifications": {
        "defaultDiscount": {
          "percentage": 10,
          "value": 15
        },
        "markup": {
          "percentage": 5,
          "value": 7.5
        },
        "promotionDiscount": {
          "percentage": 15,
          "value": 22.5,
          "promotionID": "123e4567-e89b-12d3-a456-426614174000",
          "promotionName": "Summer Sale"
        }
      },
      "description": "This beautiful apartment offers stunning ocean views...",
      "address": {
        "city": "San Francisco",
        "line1": "123 Main St",
        "line2": "Apt 1",
        "state": "CA",
        "country": "United States",
        "postal_code": "94101"
      },
      "thumbnailURL": "https://example.com/images/listing_thumbnail.jpg",
      "pictures": [
        {
          "url": "https://example.com/images/listing_1.jpg",
          "description": "Living room with ocean view"
        }
      ],
      "rating": {
        "count": 42,
        "average": 4.8
      },
      "maxOccupancy": 4,
      "distance": 3.5,
      "tags": [
        {
          "id": "a1111111-1111-1111-1111-111111111111",
          "name": "Beachfront"
        },
        {
          "id": "b2222222-2222-2222-2222-222222222222",
          "name": "Pet Friendly"
        }
      ],
      "isPromoted": true,
      "promotionValue": 20,
      "amenities": {
        "categories": {
          "Common Amenities": {
            "categoryID": "common",
            "values": [
              {
                "name": "Wifi",
                "id": "amenity-123"
              },
              {
                "name": "Kitchen",
                "id": "amenity-123"
              },
              {
                "name": "Iron",
                "id": "amenity-123"
              },
              {
                "name": "Pet friendly",
                "id": "amenity-123"
              },
              {
                "name": "Bed linens",
                "id": "amenity-123"
              }
            ]
          },
          "Outdoor": {
            "categoryID": "outdoor",
            "values": [
              {
                "name": "Smoking allowed",
                "id": "amenity-123"
              }
            ]
          }
        }
      }
    }
  ],
  "meta": {
    "count": 120,
    "limit": 20,
    "previous": 1,
    "current": 2,
    "next": 3,
    "pages": 6
  },
  "location": "37.7749,-122.4194",
  "radius": 10,
  "guests": 2,
  "amenities": [
    "wifi",
    "pool",
    "kitchen"
  ],
  "promotionID": "123e4567-e89b-12d3-a456-426614174000"
}

Authorizations

x-calry-api-key
string
header
required

Query Parameters

location
string

Location coordinates in format "latitude,longitude"

Example:

"37.7749,-122.4194"

radius
number

Search radius in kilometers from the specified location

Required range: x >= 0
Example:

10

guests
number

Number of guests

Required range: x >= 1
Example:

2

page
number
default:1

Page number for pagination

Required range: x >= 1
Example:

1

limit
number
default:50

Number of results per page

Required range: 1 <= x <= 100
Example:

20

displayCurrency
string

Currency to display prices in (ISO 4217 currency code)

Example:

"USD"

minPrice
number

Minimum price per night

Required range: x >= 0
Example:

100

maxPrice
number

Maximum price per night

Required range: x >= 0
Example:

500

bedroomCount
number

Minimum number of bedrooms

Required range: x >= 0
Example:

2

bathroomCount
number

Minimum number of bathrooms

Required range: x >= 0
Example:

1

amenities
string[]

Array of amenity IDs to filter by

Example:
["wifi", "pool", "kitchen"]
petFriendly
boolean

Filter for pet-friendly listings

Example:

true

promotionID
string

Filter by promotion ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

promoted
boolean

Filter for promoted listings only

Example:

true

zoom
number

Map zoom level for location-based searches

Example:

12

listingIDs
string[]

Array of listing IDs to filter the search results

Example:
[
"123e4567-e89b-12d3-a456-426614174000",
"987fcdeb-a89b-12d3-a456-426614174000"
]
tags
string[]

Array of tag IDs to filter listings

Example:
["tag-id-1", "tag-id-2"]
propertyType
enum<string>[]

Type of the property (single or multiple values, comma-separated)

Available options:
Apartment,
Aparthotel,
Bastide,
Barn,
Bed & breakfast,
Boat,
Building,
Boutique Hotel,
Bungalow,
Cabin,
Campsite,
Caravan,
Campground,
Casa Particular,
Castle,
Chacara,
Cave,
Chalet,
Chateau,
Condominium,
Corporate Apartment,
Cycladic House,
Cottage,
Country House,
Estate,
Dammuso,
Dorm,
Duplex,
Dome House,
Earth House,
Farmhouse,
Fourplex,
Gite,
Guest House,
Guest Suite,
Heritage Hotel,
Holiday Home,
Holiday Park,
Holiday Village,
House,
Houseboat,
Homestay,
Hotel,
Hostel,
Hut,
Igloo,
Island,
Kezhan,
Lighthouse,
Lodge,
Loft,
Longere,
Manor,
Mas,
Minsu,
Mill,
Motelroom,
Mobile Home,
Nature Lodge,
Pension,
Penthouse,
Plane,
Ranch,
Religious Building,
Camper/RV,
Resort,
Residence,
Riad,
Ryokan,
Room,
Sample,
Serviced Apartment,
Shepherd's Hut,
Shipping Container,
Studio,
Suites,
Tent,
Tiny House,
Tipi,
Tower,
Townhouse,
Train,
Treehouse,
Triplex,
Trullo,
Vacation Home,
Villa,
Windmill,
Yurt,
Yacht,
Dormitory,
Private room,
Private room in an apartment,
Private room in a house,
Other
Example:
["Apartment", "House"]
checkInDate
string<date-time>

Check-in date for the stay

Example:

"2025-06-15"

checkOutDate
string<date-time>

Check-out date for the stay

Example:

"2025-06-22"

Response

Search completed successfully

checkInDate
string
required

Check-in date for the search

Example:

"2025-06-15"

checkOutDate
string
required

Check-out date for the search

Example:

"2025-06-22"

listings
object[]
required

List of search results

meta
object
required

Pagination metadata

location
string

Location coordinates used in the search

Example:

"37.7749,-122.4194"

radius
number

Search radius in kilometers

Example:

10

guests
number

Number of guests specified in the search

Example:

2

amenities
string[]

Amenities specified in the search

Example:
["wifi", "pool", "kitchen"]
promotionID
string

Promotion ID used in the search

Example:

"123e4567-e89b-12d3-a456-426614174000"