Using Aggregates To Determine Distinct Values For Filters

The Repliers real estate APIs include a powerful feature called "aggregates," which allows users to determine distinct values for certain parameters and filters. This guide will explain how to use this feature effectively.

Determining Distinct Values

To find out what values you can use for a specific parameter like propertyType, you can make a request to the Repliers API with the aggregates query parameter. For example:

https://api.repliers.io/listings?aggregates=details.propertyType

In the response, you will receive an aggregates object containing the possible values and their respective counts. Here is an example of what the response might look like:

{
    "aggregates": {
        "details": {
            "propertyType": {
                "Apartment/Condo": 8844,
                "House/Single Family": 8661,
                "Townhouse": 3114,
                "Vacant Land": 1021,
                "Business": 1001,
                "House With Acreage": 865,
                "Industrial": 804,
                "Office": 738,
                "Retail": 680,
                "1/2 Duplex": 594,
                "Land Commercial": 328,
                "Multi-Family Commercial": 136,
                "Manufactured": 134,
                "Business With Property": 83,
                "Other": 83,
                "Agri-Business": 70,
                "Duplex": 60,
                "Manufactured With Land": 41,
                "Row House (Non-Strata)": 38,
                "Recreational": 25,
                "Triplex": 17,
                "Fourplex": 15
            }
        }
    }
}

Filtering by Property Type

Once you know the possible values, you can use them to filter your listings. For example, to filter by Fourplex, you would include the propertyType parameter in your request like this:

https://api.repliers.io/listings?propertyType=Fourplex

Requesting Multiple Aggregates At The Same Time

You can request multiple aggregates at the same time by comma-separating the fields you wish to aggregate values for, here's an example:

https://api.repliers.io/listings?aggregates=details.propertyType,details.style,details.numBedrooms,address.city

The values specified in the aggregates parameter must match keys in the listings model using dot notation.

When you use the aggregates parameter like ?aggregates=address.city, the API looks for the exact path to that field in your listing model's structure. The dot notation ( .) represents nested object traversal.

For example, given the listing object structure:

{
  "address": {
    "area": "York",
    "city": "Richmond Hill",
    "country": null,
    ...
  }
}

The path address.city uses dot notation to specify:

Start at the root of the listing object
Access the address object
Then access the city field within that object

If you want to aggregate by other fields, you would use the same dot notation pattern:

address.area for the area values
address.neighborhood for neighborhoods
address.state for states

The aggregation will only work if these paths exactly match the structure of your listings data model. If a path doesn't exist or is misspelled, the aggregation won't function properly.

Conclusion

The aggregates feature in Repliers APIs provides a convenient way to determine and use acceptable values for parameters like propertyType. By making a request to get the aggregates and then using these values in your filters, you can refine your searches and obtain more relevant results.

If you have any questions or need further assistance, please contact our support team.

Updated on: 21/04/2025