Filtering

Most Houski API endpoints let you filter by any field, or geographically via bounding box or polygon (examples below).

Filter by adding query parameters to the request URL. To filter the properties endpoint by full bathrooms, use any of:

FilterNameExample
Greater thangtbathroom_full_gt=3
Greater than or equal togtebathroom_full_gte=3
Less thanltbathroom_full_lt=3
Less than or equal toltebathroom_full_lte=3
Equal toeqbathroom_full_eq=3
Not equal toneqbathroom_full_neq=3
In the given listinproperty_type_in=House,Apartment
Matches a regular expressionregexbathroom_full_regex=1|3
Does not match a regular expressionnregexbathroom_full_nregex=1|3
Programming language

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

Filtering by number of bedrooms
Request
Shell session
curl -X GET "http://127.0.0.1:8080/properties?api_key=YOUR_API_KEY&bedroom_eq=3&country_abbreviation=ca&page=1&province_abbreviation=ab&results_per_page=3&select=bedroom,den,estimate_list_price,latitude,longitude"
TypeScript code
const houski_properties_data = async (): Promise<PropertiesResponse> => {

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

    const url = new URL('http://127.0.0.1:8080/properties');
    url.searchParams.set('api_key', 'YOUR_API_KEY');
    url.searchParams.set('bedroom_eq', '3');
    url.searchParams.set('country_abbreviation', 'ca');
    url.searchParams.set('page', '1');
    url.searchParams.set('province_abbreviation', 'ab');
    url.searchParams.set('results_per_page', '3');
    url.searchParams.set('select', 'bedroom,den,estimate_list_price,latitude,longitude');

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

    return data;
}

(async () => {
let data: PropertiesResponse = await houski_properties_data();

// Log the response
console.log(data);
})();
Response
JSON
{
  "cache_hit": false,
  "cost_cents": 1.0199999809265137,
  "data": [
    {
      "address": "12819 121 Avenue NW",
      "bedroom": 3,
      "den": 0,
      "estimate_list_price": 392855,
      "latitude": 53.574344635009766,
      "longitude": -113.54380798339844,
      "property_id": "1000286b73c1dbe3"
    },
    {
      "address": "622 Highway Avenue",
      "bedroom": 3,
      "den": 0,
      "estimate_list_price": 368301,
      "latitude": 49.88071060180664,
      "longitude": -113.05328369140624,
      "property_id": "100044b2b8107ebb"
    },
    {
      "address": "6 1744 7 Street SW",
      "bedroom": 3,
      "den": 0,
      "estimate_list_price": 985289,
      "latitude": 51.03611755371094,
      "longitude": -114.0792007446289,
      "property_id": "10004f7afe0c1946"
    }
  ],
  "error": "",
  "pagination": {
    "current_page": 1,
    "has_next_page": true,
    "has_previous_page": false,
    "page_total": 498467
  },
  "price_quote": false,
  "result_total": 1495401,
  "time_ms": 142,
  "ui_info": {
    "country": "Canada",
    "country_abbreviation": "CA",
    "country_abbreviation_id": "9ace2b6431b7f1be",
    "country_abbreviation_link": "ca",
    "country_slug": "canada",
    "province": "Alberta",
    "province_abbreviation": "AB",
    "province_abbreviation_id": "aae1f05a0f89d2c7",
    "province_abbreviation_link": "ca/ab",
    "province_slug": "alberta"
  }
}
Filtering by a bounding box
A bounding box is a rectangular geographic region defined by its northeast and southwest corner coordinates. Requests using these parameters only return properties inside the box.
Request
Shell session
curl -X GET "http://127.0.0.1:8080/properties?api_key=YOUR_API_KEY&bbox_ne_lat=51.1005&bbox_ne_lng=-113.508&bbox_sw_lat=50.6668&bbox_sw_lng=-114.4593&country_abbreviation=ca&page=1&province_abbreviation=ab&results_per_page=3&select=bedroom,den,estimate_list_price,latitude,longitude"
TypeScript code
const houski_properties_data = async (): Promise<PropertiesResponse> => {

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

    const url = new URL('http://127.0.0.1:8080/properties');
    url.searchParams.set('api_key', 'YOUR_API_KEY');
    url.searchParams.set('bbox_ne_lat', '51.1005');
    url.searchParams.set('bbox_ne_lng', '-113.508');
    url.searchParams.set('bbox_sw_lat', '50.6668');
    url.searchParams.set('bbox_sw_lng', '-114.4593');
    url.searchParams.set('country_abbreviation', 'ca');
    url.searchParams.set('page', '1');
    url.searchParams.set('province_abbreviation', 'ab');
    url.searchParams.set('results_per_page', '3');
    url.searchParams.set('select', 'bedroom,den,estimate_list_price,latitude,longitude');

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

    return data;
}

(async () => {
let data: PropertiesResponse = await houski_properties_data();

// Log the response
console.log(data);
})();
Response
JSON
{
  "cache_hit": false,
  "cost_cents": 1.0199999809265137,
  "data": [
    {
      "address": "6 1744 7 Street SW",
      "bedroom": 3,
      "den": 0,
      "estimate_list_price": 985289,
      "latitude": 51.03611755371094,
      "longitude": -114.0792007446289,
      "property_id": "10004f7afe0c1946"
    },
    {
      "address": "384 Copperpond Landng SE",
      "bedroom": 3,
      "den": 0,
      "estimate_list_price": 590394,
      "latitude": 50.925743103027344,
      "longitude": -113.92975616455078,
      "property_id": "10007f9761f49940"
    },
    {
      "address": "52 Cedargrove Way SW",
      "bedroom": 5,
      "den": 0,
      "estimate_list_price": 645001,
      "latitude": 50.95145034790039,
      "longitude": -114.12571716308594,
      "property_id": "1000c277cd905d3b"
    }
  ],
  "error": "",
  "pagination": {
    "current_page": 1,
    "has_next_page": true,
    "has_previous_page": false,
    "page_total": 175000
  },
  "price_quote": false,
  "result_total": 525000,
  "time_ms": 177,
  "ui_info": {
    "country": "Canada",
    "country_abbreviation": "CA",
    "country_abbreviation_id": "9ace2b6431b7f1be",
    "country_abbreviation_link": "ca",
    "country_slug": "canada",
    "province": "Alberta",
    "province_abbreviation": "AB",
    "province_abbreviation_id": "aae1f05a0f89d2c7",
    "province_abbreviation_link": "ca/ab",
    "province_slug": "alberta"
  }
}
Filtering by a polygon
A polygon is an arbitrary shape defined by ordered latitude-longitude pairs. Only properties inside the polygon are returned. Format: lat-lng pairs separated by underscores, with each pair separated by a comma. A polygon may have at most 100 points, because every point is tested against every property the request reaches. Simplify a hand-drawn shape before sending it.
Request
Shell session
curl -X GET "http://127.0.0.1:8080/properties?api_key=YOUR_API_KEY&country_abbreviation=ca&page=1&polygon=51.0447_-114.0719,51.0544_-114.0719,51.0544_-114.0856,51.0452_-114.0856&province_abbreviation=ab&results_per_page=3&select=bedroom,den,estimate_list_price,latitude,longitude"
TypeScript code
const houski_properties_data = async (): Promise<PropertiesResponse> => {

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

    const url = new URL('http://127.0.0.1:8080/properties');
    url.searchParams.set('api_key', 'YOUR_API_KEY');
    url.searchParams.set('country_abbreviation', 'ca');
    url.searchParams.set('page', '1');
    url.searchParams.set('polygon', '51.0447_-114.0719,51.0544_-114.0719,51.0544_-114.0856,51.0452_-114.0856');
    url.searchParams.set('province_abbreviation', 'ab');
    url.searchParams.set('results_per_page', '3');
    url.searchParams.set('select', 'bedroom,den,estimate_list_price,latitude,longitude');

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

    return data;
}

(async () => {
let data: PropertiesResponse = await houski_properties_data();

// Log the response
console.log(data);
})();
Response
JSON
{
  "cache_hit": false,
  "cost_cents": 1.0199999809265137,
  "data": [
    {
      "address": "2018 608 9 Street SW",
      "bedroom": 3,
      "den": 0,
      "estimate_list_price": 1079219,
      "latitude": 51.04768371582031,
      "longitude": -114.0837173461914,
      "property_id": "100556b0922cfec"
    },
    {
      "address": "2101 888 4 Avenue SW",
      "bedroom": 2,
      "den": 0,
      "estimate_list_price": 1278152,
      "latitude": 51.05002975463867,
      "longitude": -114.08051300048828,
      "property_id": "100a3285ac5dd6b1"
    },
    {
      "address": "1001 730 2 Avenue SW",
      "bedroom": 2,
      "den": 0,
      "estimate_list_price": 388944,
      "latitude": 51.0519905090332,
      "longitude": -114.0774917602539,
      "property_id": "100f44b3b8d53d1c"
    }
  ],
  "error": "",
  "pagination": {
    "current_page": 1,
    "has_next_page": true,
    "has_previous_page": false,
    "page_total": 3076
  },
  "price_quote": false,
  "result_total": 9227,
  "time_ms": 308,
  "ui_info": {
    "country": "Canada",
    "country_abbreviation": "CA",
    "country_abbreviation_id": "9ace2b6431b7f1be",
    "country_abbreviation_link": "ca",
    "country_slug": "canada",
    "province": "Alberta",
    "province_abbreviation": "AB",
    "province_abbreviation_id": "aae1f05a0f89d2c7",
    "province_abbreviation_link": "ca/ab",
    "province_slug": "alberta"
  }
}

Filtering expansion data

When using expand to include datasets (listings, permits, assessments), expand filters control which expanded records are returned. They work independently of your main property filters and only affect expanded data.

Format: expand_[field]_[operator]=[value]

Listings filters

FilterDescriptionExample
expand_listing_date_gteListings after specified dateexpand_listing_date_gte=2024-01-01
expand_listing_date_gtListings strictly after dateexpand_listing_date_gt=2024-06-01
expand_listing_event_eqSpecific listing eventsexpand_listing_event_eq=Price decrease
expand_estimate_list_price_ltListing prices below amountexpand_estimate_list_price_lt=500000

Permits filters

Useful for finding properties with specific permits or renovations.

FilterDescriptionExample
expand_permit_application_date_gtePermits applied for after dateexpand_permit_application_date_gte=2023-01-01
expand_permit_content_regexSearch permit descriptions with regex"expand_permit_content_regex=(?i)\b(secondary|suite)\b"

Common permit search patterns

Search typeRegex pattern
Secondary suites"(?i)\b(secondary|suite)\b"
Renovations"(?i)\b(renovation|remodel)\b"
Kitchen and bathroom upgrades"(?i)\b(kitchen|bathroom)\b"
Outdoor improvements"(?i)\b(deck|patio|fence)\b"
Garage and parking"(?i)\b(garage|carport|parking)\b"

Assessments filters

FilterDescriptionExample
expand_assessment_year_eqAssessments for specific yearexpand_assessment_year_eq=2024
expand_assessment_value_gteAssessment value minimumsexpand_assessment_value_gte=500000
expand_assessment_value_lteAssessment value maximumsexpand_assessment_value_lte=800000

Filter expand match

filter_expand_match controls which properties return based on expanded data availability.

ValueBehaviorUse case
Default (no parameter)All properties, with or without expanded dataGeneral search with optional expansion
anyOnly properties with ANY requested expansion dataListing OR permit data
allOnly properties with ALL requested expansion dataListing AND permit data

If you only need properties that have a data set, and you do not need the expanded records themselves, filter on the matching boolean field instead: has_expand_listings, has_expand_listings_rent, has_expand_permits, or has_expand_assessments. For example, has_expand_listings_eq=true returns only properties with listing history. These are fast indexed filters on the property record itself, so they cost less and run faster than expanding a data set with filter_expand_match=all just to check for its presence.

Example usage

Recent price decreases
Request
Shell session
curl -X GET "http://127.0.0.1:8080/properties?api_key=YOUR_API_KEY&country_abbreviation=ca&expand=listings&expand_listing_date_gt=2024-04-01&expand_listing_event_eq=Price decrease&filter_expand_match=all&page=1&province_abbreviation=ab&results_per_page=3&select=estimate_list_price"
TypeScript code
const houski_properties_data = async (): Promise<PropertiesResponse> => {

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

    const url = new URL('http://127.0.0.1:8080/properties');
    url.searchParams.set('api_key', 'YOUR_API_KEY');
    url.searchParams.set('country_abbreviation', 'ca');
    url.searchParams.set('expand', 'listings');
    url.searchParams.set('expand_listing_date_gt', '2024-04-01');
    url.searchParams.set('expand_listing_event_eq', 'Price decrease');
    url.searchParams.set('filter_expand_match', 'all');
    url.searchParams.set('page', '1');
    url.searchParams.set('province_abbreviation', 'ab');
    url.searchParams.set('results_per_page', '3');
    url.searchParams.set('select', 'estimate_list_price');

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

    return data;
}

(async () => {
let data: PropertiesResponse = await houski_properties_data();

// Log the response
console.log(data);
})();
Response
JSON
{
  "cache_hit": false,
  "cost_cents": 0.6599999666213989,
  "data": [
    {
      "address": "114 10611 117 Street NW",
      "estimate_list_price": 209120,
      "listings": [
        {
          "expand_estimate_list_price": 224900,
          "expand_listing_date": "2026-05-27",
          "expand_listing_event": "Price decrease",
          "property_id": "1001324b751fd15c"
        }
      ],
      "property_id": "1001324b751fd15c"
    },
    {
      "address": "48 Catalina Circle NE",
      "estimate_list_price": 348934,
      "listings": [
        {
          "expand_estimate_list_price": 415000,
          "expand_listing_date": "2024-09-20",
          "expand_listing_event": "Price decrease",
          "property_id": "10019b3ca95ab014"
        }
      ],
      "property_id": "10019b3ca95ab014"
    },
    {
      "address": "452 141 Prince Court",
      "estimate_list_price": 505267,
      "listings": [
        {
          "expand_estimate_list_price": 419900,
          "expand_listing_date": "2026-07-13",
          "expand_listing_event": "Price decrease",
          "property_id": "1001c2dcd908153e"
        }
      ],
      "property_id": "1001c2dcd908153e"
    }
  ],
  "error": "",
  "pagination": {
    "current_page": 1,
    "has_next_page": true,
    "has_previous_page": false,
    "page_total": 32036
  },
  "price_quote": false,
  "result_total": 96107,
  "time_ms": 694,
  "ui_info": {
    "country": "Canada",
    "country_abbreviation": "CA",
    "country_abbreviation_id": "9ace2b6431b7f1be",
    "country_abbreviation_link": "ca",
    "country_slug": "canada",
    "province": "Alberta",
    "province_abbreviation": "AB",
    "province_abbreviation_id": "aae1f05a0f89d2c7",
    "province_abbreviation_link": "ca/ab",
    "province_slug": "alberta"
  }
}
Secondary suite permits
Request
Shell session
curl -X GET "http://127.0.0.1:8080/properties?api_key=YOUR_API_KEY&country_abbreviation=ca&expand=permits&expand_permit_application_date_gte=2023-01-01&expand_permit_content_regex=(?i)\b(secondary|suite)\b&filter_expand_match=all&page=1&province_abbreviation=ab&results_per_page=3&select=estimate_list_price"
TypeScript code
const houski_properties_data = async (): Promise<PropertiesResponse> => {

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

    const url = new URL('http://127.0.0.1:8080/properties');
    url.searchParams.set('api_key', 'YOUR_API_KEY');
    url.searchParams.set('country_abbreviation', 'ca');
    url.searchParams.set('expand', 'permits');
    url.searchParams.set('expand_permit_application_date_gte', '2023-01-01');
    url.searchParams.set('expand_permit_content_regex', '(?i)\b(secondary|suite)\b');
    url.searchParams.set('filter_expand_match', 'all');
    url.searchParams.set('page', '1');
    url.searchParams.set('province_abbreviation', 'ab');
    url.searchParams.set('results_per_page', '3');
    url.searchParams.set('select', 'estimate_list_price');

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

    return data;
}

(async () => {
let data: PropertiesResponse = await houski_properties_data();

// Log the response
console.log(data);
})();
Response
JSON
{
  "cache_hit": true,
  "cost_cents": 0.6599999666213989,
  "data": [
    {
      "address": "39 Rundlelawn Court NE",
      "estimate_list_price": 500105,
      "permits": [
        {
          "expand_permit_application_date": "2023-04-13",
          "expand_permit_content": "Status: Released|Category: Residential - Secondary Suite|Description: NEW: SECONDARY SUITE (BASEMENT) - AVPA|Proposed use code: C2626|Proposed use description: SECONDARY SUITE|Permitted/discretionary: Permitted|Land use district: R-C2|Land use district description: Residential - Contextual One/Two Dwelling|Concurrent LOC: N/A|Decision: Approval|Decision by: Development Authority|Decision date: 2023-05-15|Canceled/refused date: N/A|SDAB Number: N/A|SDAB hearing date: N/A|SDAB Decision: N/A|SDAB decision date: N/A",
          "expand_permit_id": "DP2023-02283",
          "expand_permit_type": "Development",
          "property_id": "100fafb0c113c886"
        }
      ],
      "property_id": "100fafb0c113c886"
    },
    {
      "address": "11230 125 Street NW",
      "estimate_list_price": 850315,
      "permits": [
        {
          "expand_permit_application_date": "2024-07-25",
          "expand_permit_content": "Subtype: Minor Development Permit|Class: Permitted Development|Status: Approved|Description of development: To construct a Residential Use building in the form of a Single Detached House with unenclosed front porch, front balcony,  rear uncovered deck (5.15m x 3.05m), fireplace, and to develop a Secondary Suite in the Basement.|Legal description: Plan 2420805 Blk 8 Lot 6B|Neighbourhood: INGLEWOOD|Neighbourhood classification: Redeveloping|Ward: Anirniq Ward|Zoning: RS|Land parcel count: 4",
          "expand_permit_id": "508699057-002",
          "expand_permit_type": "Development",
          "property_id": "101a63ff355394e8"
        }
      ],
      "property_id": "101a63ff355394e8"
    },
    {
      "address": "221 12 Avenue NE",
      "estimate_list_price": 738954,
      "permits": [
        {
          "expand_permit_application_date": "2026-03-11",
          "expand_permit_content": "Status: Cancelled|Category: Residential - New Single / Semi / Duplex|Description: NEW: SINGLE DETACHED DWELLING, SECONDARY SUITE (BASEMENT), ACCESSORY RESIDENTIAL BUILDING (GARAGE)|Proposed use code: C1020; C2626; C2730|Proposed use description: ACCESSORY RESIDENTIAL BUILDING; SECONDARY SUITE; SINGLE DETACHED DWELLING|Permitted/discretionary: Discretionary|Land use district: R-CG|Land use district description: Residential - Grade-Oriented Infill|Concurrent LOC: N/A|Decision: N/A|Decision by: N/A|Decision date: N/A|Canceled/refused date: 2026-03-23|SDAB Number: N/A|SDAB hearing date: N/A|SDAB Decision: N/A|SDAB decision date: N/A",
          "expand_permit_id": "DP2026-01337",
          "expand_permit_type": "Development",
          "property_id": "101f96b239efbbf6"
        }
      ],
      "property_id": "101f96b239efbbf6"
    }
  ],
  "error": "",
  "pagination": {
    "current_page": 1,
    "has_next_page": true,
    "has_previous_page": false,
    "page_total": 3602
  },
  "price_quote": false,
  "result_total": 10804,
  "time_ms": 885,
  "ui_info": {
    "country": "Canada",
    "country_abbreviation": "CA",
    "country_abbreviation_id": "9ace2b6431b7f1be",
    "country_abbreviation_link": "ca",
    "country_slug": "canada",
    "province": "Alberta",
    "province_abbreviation": "AB",
    "province_abbreviation_id": "aae1f05a0f89d2c7",
    "province_abbreviation_link": "ca/ab",
    "province_slug": "alberta"
  }
}
High assessments in 2024
Request
Shell session
curl -X GET "http://127.0.0.1:8080/properties?api_key=YOUR_API_KEY&country_abbreviation=ca&expand=assessments&expand_assessment_value_gte=750000&expand_assessment_year_eq=2024&filter_expand_match=all&page=1&province_abbreviation=ab&results_per_page=3&select=estimate_list_price"
TypeScript code
const houski_properties_data = async (): Promise<PropertiesResponse> => {

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

    const url = new URL('http://127.0.0.1:8080/properties');
    url.searchParams.set('api_key', 'YOUR_API_KEY');
    url.searchParams.set('country_abbreviation', 'ca');
    url.searchParams.set('expand', 'assessments');
    url.searchParams.set('expand_assessment_value_gte', '750000');
    url.searchParams.set('expand_assessment_year_eq', '2024');
    url.searchParams.set('filter_expand_match', 'all');
    url.searchParams.set('page', '1');
    url.searchParams.set('province_abbreviation', 'ab');
    url.searchParams.set('results_per_page', '3');
    url.searchParams.set('select', 'estimate_list_price');

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

    return data;
}

(async () => {
let data: PropertiesResponse = await houski_properties_data();

// Log the response
console.log(data);
})();
Response
JSON
{
  "cache_hit": true,
  "cost_cents": 0.6599999666213989,
  "data": [
    {
      "address": "239 Dalhurst Way NW",
      "assessments": [
        {
          "expand_assessment_value": 983000,
          "expand_assessment_year": 2024,
          "property_id": "100086f6bc064d3f"
        }
      ],
      "estimate_list_price": 895365,
      "property_id": "100086f6bc064d3f"
    },
    {
      "address": "6619 34 Street SW",
      "assessments": [
        {
          "expand_assessment_value": 760500,
          "expand_assessment_year": 2024,
          "property_id": "10014f3c7e5bfad9"
        }
      ],
      "estimate_list_price": 771488,
      "property_id": "10014f3c7e5bfad9"
    },
    {
      "address": "2306 Frezenberg Avenue NW",
      "assessments": [
        {
          "expand_assessment_value": 850000,
          "expand_assessment_year": 2024,
          "property_id": "1001b44afaf8749e"
        }
      ],
      "estimate_list_price": 925148,
      "property_id": "1001b44afaf8749e"
    }
  ],
  "error": "",
  "pagination": {
    "current_page": 1,
    "has_next_page": true,
    "has_previous_page": false,
    "page_total": 43012
  },
  "price_quote": false,
  "result_total": 129036,
  "time_ms": 1773,
  "ui_info": {
    "country": "Canada",
    "country_abbreviation": "CA",
    "country_abbreviation_id": "9ace2b6431b7f1be",
    "country_abbreviation_link": "ca",
    "country_slug": "canada",
    "province": "Alberta",
    "province_abbreviation": "AB",
    "province_abbreviation_id": "aae1f05a0f89d2c7",
    "province_abbreviation_link": "ca/ab",
    "province_slug": "alberta"
  }
}

Important notes

  • Without filter_expand_match, expand filters only narrow which records appear inside each expanded array. Every property still comes back, just with fewer attached records.
  • filter_expand_match=all keeps a property only when every dataset listed in expand= produces at least one matching record for it. Use this when you want properties that satisfy all conditions at once, like permit data AND listing data.
  • filter_expand_match=any keeps a property when at least one dataset in expand= produces a matching record. Use this for permit data OR listing data.
  • With expand=permits,listings, a property that matches on permits but has no matching listings is kept by any and dropped by all. A property with neither is dropped by both.
  • Prefix a regex with (?i) for case-insensitive matching, for example expand_permit_content_regex=(?i)kitchen matches Kitchen and KITCHEN.
  • Use "\b" word boundaries for whole-word matches, for example "\bsuite\b" matches suite but not suitable.
  • You can combine multiple expand_* filters in one request. Each filter applies to its own dataset, and filter_expand_match decides how the per-dataset hits combine into the final property list.