/aggregate

GET
https://api.houski.ca/aggregate

This endpoint returns averages of property data for a given location. You can use this endpoint to get an overview of the property market or property features in a specific area.

This endpoint handles single and batch requests. Batch requests, which enable multiple operations with varying fields, aggregations, and filters in one go, are more efficient than multiple single requests.

This endpoint conforms to Houski API's standard filtering functionality.

To see all the fields that can be aggregated or filtered by, see the fields page.

To find data on all available location values, such as country_abbreviation, province_abbreviation, city and community, you can use the /locations endpoint.

Example use cases

You can find examples for common use cases on our recipes page.
  1. Real estate analysts can perform granular market trend analysis by comparing average property prices, square footage, or other characteristics across different neighborhoods or cities.
  2. Provide potential buyers or renters with insights into the average costs of properties (e.g., rent, purchase price) in different areas, enhancing their search experience.
  3. Assist real estate investors in identifying undervalued areas by comparing the average property values against regional income levels.
  4. Portfolio managers can assess the performance of their real estate investments by tracking changes in the average value of properties within their portfolio over time.
  5. Support government housing authorities in monitoring and developing policies related to affordable housing by analyzing the average prices of properties across different zones.
  6. Assist urban researchers in studying the impact of infrastructure developments on property values by observing changes in average property prices before and after development projects.
  7. Enable CRE professionals to assess the viability of commercial projects by analyzing average lease rates, property sizes, and types in target areas.
  8. Enable preservationists to identify areas with significant cultural or historical properties by analyzing the average age of buildings or specific architectural features.

Request parameters

No
NameRequiredTypeDescription
api_keyYesUUID v4Authorization API key
fieldYesStringThe field to be aggregated - see fields for all available fields
aggregationYesStringThe aggregation can be one of the following values:
  • sum
  • mean
  • median
  • mode
  • quantile10
  • quantile25
  • quantile40
  • quantile60
  • quantile75
  • quantile80
  • quantile85
  • quantile90
  • quantile95
  • quantile99
country_abbreviationNoStringA country abbreviation
province_abbreviationNoStringA province abbreviation within the country
cityNoStringA city within the province
communityNoStringA community within the city
bbox_ne_latNoNumberNortheast latitude for bounding box.
bbox_ne_lngNoNumberNortheast longitude for bounding box.
bbox_sw_latNoNumberSouthwest latitude for bounding box.
bbox_sw_lngNoNumberSouthwest longitude for bounding box.
polygonNoPolygon filter stringGet results inside a polygon.

Response object

Type declarations are available at the bottom of this page.

NameTypeDescription
cache_hitBooleanIndicates if the response was a cache hit
cost_centsNumberCost of the request in cents
dataObjectContains the data for the aggregation
errorStringDetails about the error. Empty if no error
price_quoteBooleanIndicates whether the response is a price quote
time_msNumberTime taken for the request to complete in milliseconds

Example requests and responses

Programming language

Select the programming language you want to display the code examples in.

Get the average list price in a community

This request returns the median list price of properties in the Riverbend community in Calgary, Alberta, Canada.

Request
Shell session
curl -X GET "https://api.houski.ca/aggregate?aggregation=median&api_key=YOUR_API_KEY&city=calgary&community=riverbend&country_abbreviation=ca&field=estimate_list_price&province_abbreviation=ab"
TypeScript code
const houski_get_aggregate = async (): Promise<AggregateResponse> => {

    // You must copy the AggregateResponse type declarations from the 
    // Houski API documentation to strongly type the response

    const url = new URL('https://api.houski.ca/aggregate');
    url.searchParams.set('aggregation', 'median');
    url.searchParams.set('api_key', 'YOUR_API_KEY');
    url.searchParams.set('city', 'calgary');
    url.searchParams.set('community', 'riverbend');
    url.searchParams.set('country_abbreviation', 'ca');
    url.searchParams.set('field', 'estimate_list_price');
    url.searchParams.set('province_abbreviation', 'ab');

    const response = await fetch(url);
    const data = await response.json();

    return data;
}

(async () => {
let data: AggregateResponse = await houski_get_aggregate();

// Log the response
console.log(data);
})();
Response
JSON
{
  "cache_hit": false,
  "cost_cents": 0.35850000381469727,
  "data": [
    {
      "aggregation": "median",
      "field": "estimate_list_price",
      "value": "594491"
    }
  ],
  "error": "",
  "price_quote": false,
  "time_ms": 21
}
Multiple batched aggregate query

This request performs multiple aggregate operations batched together.

Request
Shell session
curl -X GET "https://api.houski.ca/aggregate?agg0_aggregation=sum&agg0_city=edmonton&agg0_country_abbreviation=ca&agg0_field=bedroom&agg0_property_type_eq=Apartment&agg0_province_abbreviation=ab&agg1_aggregation=median&agg1_city=calgary&agg1_country_abbreviation=ca&agg1_field=estimate_list_price&agg1_property_type_eq=House&agg1_province_abbreviation=ab&agg2_aggregation=mode&agg2_field=kitchen_countertop_material&agg2_polygon=51.0447_-114.0719,51.0452_-114.0719,51.0452_-114.073,51.0447_-114.073&agg2_property_type_eq=House&agg3_aggregation=mean&agg3_bbox_ne_lat=51.1005&agg3_bbox_ne_lng=-113.508&agg3_bbox_sw_lat=50.6668&agg3_bbox_sw_lng=-114.4593&agg3_field=estimate_rent_monthly&api_key=YOUR_API_KEY"
TypeScript code
const houski_get_aggregate = async (): Promise<AggregateResponse> => {

    // You must copy the AggregateResponse type declarations from the 
    // Houski API documentation to strongly type the response

    const url = new URL('https://api.houski.ca/aggregate');
    url.searchParams.set('agg0_aggregation', 'sum');
    url.searchParams.set('agg0_city', 'edmonton');
    url.searchParams.set('agg0_country_abbreviation', 'ca');
    url.searchParams.set('agg0_field', 'bedroom');
    url.searchParams.set('agg0_property_type_eq', 'Apartment');
    url.searchParams.set('agg0_province_abbreviation', 'ab');
    url.searchParams.set('agg1_aggregation', 'median');
    url.searchParams.set('agg1_city', 'calgary');
    url.searchParams.set('agg1_country_abbreviation', 'ca');
    url.searchParams.set('agg1_field', 'estimate_list_price');
    url.searchParams.set('agg1_property_type_eq', 'House');
    url.searchParams.set('agg1_province_abbreviation', 'ab');
    url.searchParams.set('agg2_aggregation', 'mode');
    url.searchParams.set('agg2_field', 'kitchen_countertop_material');
    url.searchParams.set('agg2_polygon', '51.0447_-114.0719,51.0452_-114.0719,51.0452_-114.073,51.0447_-114.073');
    url.searchParams.set('agg2_property_type_eq', 'House');
    url.searchParams.set('agg3_aggregation', 'mean');
    url.searchParams.set('agg3_bbox_ne_lat', '51.1005');
    url.searchParams.set('agg3_bbox_ne_lng', '-113.508');
    url.searchParams.set('agg3_bbox_sw_lat', '50.6668');
    url.searchParams.set('agg3_bbox_sw_lng', '-114.4593');
    url.searchParams.set('agg3_field', 'estimate_rent_monthly');
    url.searchParams.set('api_key', 'YOUR_API_KEY');

    const response = await fetch(url);
    const data = await response.json();

    return data;
}

(async () => {
let data: AggregateResponse = await houski_get_aggregate();

// Log the response
console.log(data);
})();
Response
JSON
{
  "cache_hit": false,
  "cost_cents": 206.6009063720703,
  "data": [
    {
      "aggregation": "sum",
      "field": "bedroom",
      "value": "50861"
    },
    {
      "aggregation": "median",
      "field": "estimate_list_price",
      "value": "691566"
    },
    {
      "aggregation": "mode",
      "field": "kitchen_countertop_material",
      "value": "Granite"
    },
    {
      "aggregation": "mean",
      "field": "estimate_rent_monthly",
      "value": "2544.31"
    }
  ],
  "error": "",
  "price_quote": false,
  "time_ms": 80
}

Response type declarations

TypeScript code
interface AggregateResponse {
    cache_hit: boolean;
    cost_cents: number;
    data: AggregateData[];
    error: string;
    price_quote: boolean;
    time_ms: number;
}

interface AggregateData {
    field: string;
    aggregation: string;
    value: string;
}