Bundled Searches Developer Guide

Overview

The bundled searches feature allows you to combine multiple search criteria into a single API call, enabling complex property searches that would otherwise require multiple separate requests. This is particularly useful when you need different filter combinations that can't be achieved with standard query parameters alone.

When to Use Bundled Searches

Bundled searches are ideal when you need to search for properties with different criteria that can't be combined in a single standard request. Common scenarios include:

• Mixed Property Types by Location: Searching for apartments in one city and houses in another
• Variable Bedroom Requirements: Looking for 1-bedroom units in downtown areas and 3-bedroom homes in suburbs
• Location-Specific Price Ranges: Different budget ranges for different cities or neighborhoods

How It Works

Instead of making a GET request with query parameters, you make a POST request to the /listings endpoint with a JSON body containing an array of search queries. Each request in the array represents a distinct set of search criteria.

In addition, query string filters are supported and are applied globally to all bundled queries. These can be combined with body-level filters inside each query object for even greater flexibility.

Basic Structure

Make a POST request to /listings with this structure:

{
    "queries": [
        {
            // First search criteria
        },
        {
            // Second search criteria
        }
    ]
}

Request Examples

Example 1: Different Property Types and Budgets by City

{
    "queries": [
        {
            "city": "Toronto",
            "propertyType": "Single Family Residence",
            "minPrice": 800000,
            "maxPrice": 1200000
        },
        {
            "city": "New York",
            "propertyType": "Apartment",
            "minPrice": 500000,
            "maxPrice": 900000
        }
    ]
}

Example 2: Different Bedroom Requirements by City

{
    "queries": [
        {
            "minBedrooms": 1,
            "maxBedrooms": 1,
            "city": "New York"
        },
        {
            "minBedrooms": 3,
            "maxBedrooms": 3,
            "city": "Toronto"
        }
    ]
}

Example 3: Mixed Criteria Across Multiple Locations

{
    "queries": [
        {
            "city": "San Francisco",
            "propertyType": "Condo",
            "minBedrooms": 2,
            "maxBedrooms": 2,
            "minPrice": 800000
        },
        {
            "city": "Austin",
            "propertyType": "Single Family Residence",
            "minBedrooms": 4,
            "maxBedrooms": 4,
            "maxPrice": 600000
        },
        {
            "city": "Miami",
            "propertyType": "Apartment",
            "minBedrooms": 1,
            "maxBedrooms": 2,
            "minPrice": 300000,
            "maxPrice": 500000
        }
    ]
}

Example 4: Neighborhood-Specific Requirements

{
    "queries": [
        {
            "city": "Chicago",
            "neighborhood": "Lincoln Park",
            "propertyType": "Apartment",
            "minBedrooms": 2,
            "maxBedrooms": 3
        },
        {
            "city": "Chicago",
            "neighborhood": "Wicker Park",
            "propertyType": "Condo",
            "minBedrooms": 1,
            "maxBedrooms": 2,
            "maxPrice": 450000
        }
    ]
}

Using Query String and Non-Filter Parameters

You can use both filter and non-filter query string parameters with bundled searches:

• Filter parameters (e.g., city, propertyType, status) are applied globally across all queries in the bundle.
• Body-level filters inside each query object are applied in addition to global query string filters.
• Non-filter parameters like statistics, sorting, and pagination apply to the entire bundled request.

Examples of Supported Non-Filter Parameters

• statistics=true - Include market statistics
• aggregates=details.propertyType,address.city - Get aggregated data
• sortBy=listPriceDesc - Sort results
• resultsPerPage=50 - Limit number of results per page
• pageNum=2 - Pagination offset

Example with Query String Filters and Non-Filter Parameters

URL:

POST /listings?status=A&statistics=true&sortBy=listPriceDesc&resultsPerPage=50

Body:

{
    "queries": [
        {
            "city": "Boston",
            "propertyType": "Condo",
            "minBedrooms": 2
        },
        {
            "city": "Seattle",
            "propertyType": "Single Family Residence",
            "minBedrooms": 3
        }
    ]
}

In this example:

• status=A applies to both bundled queries.
• Each query adds its own city and property filters.

Important Limitations

1. POST Method Only: Bundled searches must use the POST method, not GET.
2. Array Structure Required: The JSON body must contain a "queries" array, even for a single request.

Response Format

The API returns a single response containing all results from your bundled searches. Results are merged and can be distinguished by the property details that match your different criteria.

Best Practices

• Optimize Request Count: While there's flexibility in the number of searches you can bundle, consider performance implications with very large arrays.
• Logical Grouping: Group related searches together to make the most of the bundled feature.
• Clear Criteria: Make each request in your bundle distinct enough that the results provide meaningful differentiation.
• Use Appropriate Sorting: When bundling diverse searches, consider how sorting will affect the mixed results.
• Leverage Global Filters: Use query string filters when you want criteria applied consistently across all bundled queries, and reserve body-level filters for per-query differences.

Updated on: 22/08/2025