Home API Documentation Property Aggregations

Property Aggregations

Last updated on Dec 06, 2025

Get aggregated property statistics grouped by location and property type. Perfect for building mega menus, filter dropdowns, and third-party widgets that display property inventory.

Endpoint

Authentication

Required. All API requests must be authenticated using your API key. See the Authentication section in the API Overview documentation.

Query Parameters

Parameter Type Description Default filterByOrganization boolean Filter results to only your organization's properties false status string Filter by listing status (active, pending, inactive, sold, rented) active

Note: When filterByOrganization=false (default), the endpoint returns aggregations for all properties across all organizations, making it ideal for public-facing displays and mega menus.

Response

Success Response (200 OK)

Response Fields

Field Type Description byCity object Property counts grouped by city and property type byRegion object Property counts grouped by region and property type byPropertyType object Total counts for each property type across all locations byPropertyCategory object Total counts for each property category availableCities string[] Alphabetically sorted list of all cities with properties availableRegions string[] Alphabetically sorted list of all regions with properties availablePropertyTypes string[] Alphabetically sorted list of all property types available availablePropertyCategories string[] Alphabetically sorted list of all property categories available totalProperties number Total count of properties matching the filters

Location Aggregation Object

Each location (city or region) contains:

  • total: Total number of properties in that location

  • byType: Object with property type as key and count as value

Error Responses

401 Unauthorized

400 Bad Request

Example Requests

Get All Active Properties Aggregations

Get Organization's Properties Only

Filter by Status

Combined Filters

Code Examples

JavaScript/TypeScript

Python

PHP

Use Cases

1. Dynamic Mega Menu

Build a mega menu that displays available properties by location and type:

2. Filter Dropdown with Counts

Create dynamic filter options showing available counts:

3. Location-Based Landing Pages

Generate SEO-friendly landing pages for each location:

4. Third-Party Widget

Embed property inventory widget on external websites:

5. Interactive Map Sidebar

Build a sidebar that shows available properties in each region:

6. Search Suggestions with Counts

Show search suggestions with property counts:

7. Property Type Comparison Chart

Create a visual breakdown of property inventory:

8. Featured Locations Carousel

Showcase top locations with inventory counts:

Tips and Best Practices

  1. Caching: Cache aggregations for 5-15 minutes to reduce API calls:

  2. Combine with Search: Use aggregations to build filters, then use the search endpoint to fetch actual properties:

  3. Public vs Private:

    • Use filterByOrganization=false (default) for public-facing mega menus showing all inventory

    • Use filterByOrganization=true for internal dashboards showing only your listings

  4. Status Filtering:

    • Default status=active is ideal for public-facing displays

    • Use status=pending to build internal review interfaces

    • Multiple statuses not currently supported (use search endpoint for that)

  5. Empty Locations: Locations without properties won't appear in the response, making the data clean and ready for rendering

  6. Alphabetical Sorting: All available* arrays are pre-sorted alphabetically for consistent UI rendering

  7. Performance: This endpoint is highly optimized with database indexes and typically responds in under 150ms, making it suitable for real-time mega menus

  8. Link Generation: Use city/region names directly in URL parameters:

  9. Mobile Optimization: For mobile mega menus, consider showing only top N cities:

  10. SEO Benefits: Use aggregations to generate:

    • Dynamic sitemaps with property count estimates

    • Meta descriptions mentioning property counts

    • Structured data (Schema.org) with aggregate ratings

Response Time

This endpoint is optimized with database indexes and typically responds in under 150ms. It performs efficient GROUP BY queries on the property database and is safe to call for every page load.

Limitations

  • Only one status filter at a time (use search endpoint for multiple statuses)

  • No date range filtering (shows current snapshot only)

  • Empty locations (no properties) won't appear in results

  • Property type and category names are stored as-is (no normalization)

  • Maximum of 1000 unique cities/regions per request (unlikely to hit this limit)

Related Endpoints

  • Search Properties (POST /properties/search) - Fetch actual property listings after filtering

  • Property Stats (GET /properties/stats/counts) - Get status-based counts for your organization

  • Get Property (GET /properties/:id) - Fetch individual property details

Common Integration Pattern