Find places by their rental market
findPlacesByMarket
Find which places to look at by their rental market: filter and rank every structured-live place on market facts and signals. Signed-in only; read scope. Pass `country` (CA or US; places rank only within one country) and a `preset` (CA: tight-rental, fast-rent-growth, undersupplied, mli-select-headroom; US: low-rental-vacancy, car-light), `filters` ({ key, min, max }, inclusive), or both; optional `region` (province or state, as a code or name), `sort`, `limit` (default 20, max 50) and `offset`. An unknown key returns the filterable keys. Returns counts { places, matched, inPlan, excluded, unknown }, matched places with their values and `access`, and the unknown places with their missing keys. Report the unknown count: a place missing a filtered value is not a match and not a fail. Places are compared on one survey period. `truncation` says what was left out: `places` pages with `truncation.places.nextOffset` as the next `offset`; `unknown` lists at most 50 places by name, `counts.unknown` is the total. To run a saved filter set, pass `setId` (from listPlaceMarketSets) with `limit` and `offset` only. The result adds `set` and `unavailableFilters`: stored filters whose key Bucky no longer filters on. Those are left out and the rest run; tell the user which filters were skipped. Cite every figure with the `sources` lines (CMHC licence for CA, ACS for US). Market data filters places, not lots: use screenLots for lots inside a place. Every structured-live place is searched, not only the user's. Each matched place has `access`: `in_plan` (the user can screen its lots), `available` (Bucky sells it; the user can upgrade to add it) or `not_sold` (Bucky does not sell it yet; the user can request it). `counts.inPlan` is how many matches are in the user's plan. Say how many matches are in the plan, and offer Upgrade or Request for the others; never offer to screen lots in a place that is not `in_plan`. To find lots in the matched places, this is two steps: this call ranks places by market, then call screenLots once per matched place with `access: in_plan`, passing its `geoDivisionId`, at most 10 places in rank order. Never screen unknown places or places that are not `in_plan`; say how many were left out and why. Tell the user it was two steps, and credit the market `sources` for the first.
Turning a question into filters: pick the country from the place named (Ontario, Texas). Put a province or state in `region`. Map each condition to the closest key below. "Tight" or "low vacancy" is a max on a vacancy key; "growing" or "rising" is a min on a change key; "above" is min, "below" is max. Percent bounds are numbers: 5 means 5%. Money bounds are in the country's own dollars.
A relative question ("top quarter for rent growth", "lowest 10% vacancy in the province") is a percentile filter: `top` keeps the highest-valued share of places, `bottom` the lowest, as a percent (25 = 25%), instead of min and max. It ranks within the request's places, so give a region for "in the province". Each result filter states the cut value it resolved to in `text`.
Never invent a key. If no key below measures what was asked (for example a comparison to a provincial median), say so, name the nearest key, and use a numeric bound you state. Tell the user every filter you used, in plain words with units, before or with the result: each result filter has a `text` field for this.
On an UNKNOWN_KEY or CROSS_SCOPE error, read `errorDetails` and call again in the same turn with a key or region from it.
CA keys:
population_density_per_sq_km: Density (people per km²).
median_age: Median age (years).
median_household_income: Median household income (CAD dollars). Nominal dollars of the income year, not adjusted for inflation.
owner_occupied_pct: Owner-occupied (%).
renter_occupied_pct: Renter-occupied (%).
median_home_value: Median home value (CAD dollars). Nominal dollars of the data year (for the ACS, the 5-year release’s end year), not adjusted for inflation.
median_gross_rent: Median gross rent (CAD dollars).
cmhc_rental_vacancy_rate: Purpose-built rental vacancy (%).
cmhc_rental_availability_rate: Purpose-built rental availability (%).
cmhc_avg_rent_studio: Avg rent, studio (purpose-built) (CAD dollars).
cmhc_avg_rent_1br: Avg rent, 1BR (purpose-built) (CAD dollars).
cmhc_avg_rent_2br: Avg rent, 2BR (purpose-built) (CAD dollars).
cmhc_avg_rent_3br_plus: Avg rent, 3BR+ (purpose-built) (CAD dollars).
cmhc_avg_rent_total: Avg rent, all units (purpose-built) (CAD dollars).
cmhc_median_rent_total: Median rent, all units (purpose-built) (CAD dollars).
cmhc_avg_rent_built_2000_plus: Avg rent, built 2000 or later (purpose-built) (CAD dollars).
cmhc_avg_rent_change_pct: Avg rent change, same units (purpose-built) (%).
signal_rent_cagr_5y_pct: Rent change, annualized over 5 years (%). Annualized change between two published rent levels, in nominal dollars.
signal_rental_vacancy_trend_3y_pp: Purpose-built rental vacancy change over 3 years (percentage points).
signal_new_build_rent_premium_pct: Newer-building rent difference (built 2000 or later vs all units) (%). Compares average rent in buildings constructed in 2000 or later with average rent across all surveyed units.
signal_rental_pipeline_pct: Rental units under construction as a share of purpose-built rental units (%).
signal_rental_starts_momentum_pct: Rental starts, last 12 months vs the 12 months before (%).
signal_mli_affordability_gap_pct: MLI Select rent difference as a share of average rent (%). Average rent minus the MLI Select reference rent ceiling, divided by average rent.
signal_population_cagr_census_5y_pct: Population change per year, Census 2016 to 2021 (%). Annualized change in the Census of Population count between 2016 and 2021.
signal_household_income_cagr_census_5y_pct: Median household income change per year, Census 2016 to 2021 (2015 to 2020 incomes, nominal) (%). Annualized change in median total household income, not adjusted for inflation.
US keys:
population_density_per_sq_km: Density (people per km²).
median_age: Median age (years).
acs_households_no_vehicle_pct: Households with no vehicle (%). Share of occupied households by vehicles available, ACS 5-year estimate.
acs_households_one_vehicle_pct: Households with one vehicle (%).
acs_households_two_plus_vehicles_pct: Households with two or more vehicles (%).
acs_vehicles_per_household: Vehicles per household (vehicles per household). Aggregate vehicles available divided by occupied households, ACS 5-year estimate.
acs_commute_drove_alone_pct: Commute: drove alone (%). Share of workers age 16 and over by means of transportation to work, including those who worked from home; ACS 5-year estimate.
acs_commute_carpool_pct: Commute: carpool (%).
acs_commute_transit_pct: Commute: public transit (%).
acs_commute_walk_pct: Commute: walked (%).
acs_commute_work_from_home_pct: Worked from home (%).
median_household_income: Median household income (USD dollars). Nominal dollars of the income year, not adjusted for inflation.
hud_ami_median_family_income: HUD area median family income (USD dollars).
owner_occupied_pct: Owner-occupied (%).
renter_occupied_pct: Renter-occupied (%).
vacancy_rate: Vacancy rate (%).
median_home_value: Median home value (USD dollars). Nominal dollars of the data year (for the ACS, the 5-year release’s end year), not adjusted for inflation.
median_gross_rent: Median gross rent (USD dollars).
acs_rental_vacancy_rate: ACS rental vacancy rate (all rental units) (%). ACS 5-year rental vacancy rate, including all rental units, not only purpose-built rentals.
acs_median_gross_rent_built_2020_plus: ACS median gross rent, built 2020 or later (all rental units) (USD dollars). ACS 5-year median gross rent for renter-occupied units paying cash rent in structures built 2020 or later; nominal dollars for the release.
hud_fmr_efficiency: HUD FMR — efficiency (USD dollars).
hud_fmr_one_bedroom: HUD FMR — 1BR (USD dollars).
hud_fmr_two_bedroom: HUD FMR — 2BR (USD
Schema valid · SHA-256 98f5ee097088…
View input schema
{
"type": "object",
"properties": {
"country": {
"type": "string",
"enum": [
"CA",
"US"
],
"description": "ISO country code. Places are filtered and ranked only within this country."
},
"region": {
"description": "Province or state, as a code (AB) or a name (Alberta)",
"type": "string",
"minLength": 2,
"maxLength": 60
},
"preset": {
"description": "A preset id for the country; its filters apply first, then `filters` by key",
"type": "string",
"minLength": 1,
"maxLength": 60
},
"filters": {
"default": [],
"maxItems": 8,
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "A filterable fact key, e.g. cmhc_rental_vacancy_rate"
},
"min": {
"description": "Inclusive lower bound, in the key unit",
"type": "number"
},
"max": {
"description": "Inclusive upper bound, in the key unit",
"type": "number"
},
"top": {
"description": "Percentile band (BUC-4011): keep the highest-valued share of places with a current value, as a percent. 25 = the highest 25%. Use instead of min and max.",
"type": "number",
"exclusiveMinimum": 0,
"exclusiveMaximum": 100
},
"bottom": {
"description": "Percentile band (BUC-4011): keep the lowest-valued share of places with a current value, as a percent. 25 = the lowest 25%. Use instead of min and max.",
"type": "number",
"exclusiveMinimum": 0,
"exclusiveMaximum": 100
}
},
"required": [
"key"
],
"additionalProperties": false
}
},
"sort": {
"description": "Defaults to the preset sort, else the first filter key",
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"direction": {
"type": "string",
"enum": [
"asc",
"desc"
]
}
},
"required": [
"key",
"direction"
],
"additionalProperties": false
},
"limit": {
"default": 20,
"type": "integer",
"minimum": 1,
"maximum": 50
},
"offset": {
"default": 0,
"description": "Matched places to skip. Copy truncation.places.nextOffset for the next page.",
"type": "integer",
"minimum": 0,
"maximum": 10000
},
"setId": {
"description": "Run one of your saved filter sets, by id from listPlaceMarketSets. Pass it with limit and offset only.",
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"context": {
"type": "string",
"description": "Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as \"a user\", \"the customer\", or \"an account\". Example: \"Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution.\""
}
},
"required": [
"context"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}