Search suburbs
suburbs_finder_searchRead-onlyIdempotent
Boolean-AND range filter over suburb metrics, single-column sort,
paginated. Every row carries its rank — position in the ranked result
(1 = top of the sort, out of meta.total). When sorting by a median or a
growth, the actual value is also shown for the first 5 and last 5 rows of
the page; for any other suburb's number, call the per-field endpoint
(market/, forecast/).
Paging: a page is capped at 25 rows. A bigger limit is clamped, not
rejected — so always read meta: total is the full match count,
has_more says whether rows remain, and next_offset is the offset to
pass for the next page. A "top 50" needs two calls, each charged.
Flat 30c.
Price: 30¢ per call.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort field. Prefix '-' for descending (highest first), e.g. `-growth10yrCagr`. Must be one of the field keys (see enum). Works on its own — you do NOT need a filter on the field you sort by; to rank without a threshold, pass `sort` and no filter. Only when `sort` is omitted does it default to the first filter field, desc. Apartment/unit metrics are the `unit`-prefixed keys (unitMedianPrice, unitGrossYield, unitMedianRent, …); the unprefixed market keys are houses. Unit data only exists where a suburb has a real unit market — coverage runs ~13-54% of suburbs depending on the field, so a unit filter implicitly excludes house-only suburbs. | |
| limit | No | Page size. Hard cap 25 — a larger value is clamped, NOT an error, and `meta.requested_limit` says so. For more than 25 results, page with `offset`. | |
| filter | No | Range filter `fieldKey:min..max` (repeatable). Open-ended `min..` / `..max`. Valid fieldKeys: medianHousePrice, grossYield, medianRent, growthForecast4yr, growth10yrCagr, growth3yrCagr, rentGrowth3yr, soldAtLossPct, daysOnMarket, vacancyRate, unitMedianPrice, unitGrossYield, unitMedianRent, unitGrowthForecast4yr, unitGrowth10yrCagr, unitGrowth3yrCagr, unitRentGrowth3yr, unitSoldAtLossPct, unitDaysOnMarket, unitVacancyRate, stockOnMarket, monthsOfInventory, landValuePerSqm, lifestyleScore, safetyScore, hipScore, affluenceScore, renters, distanceCbdKm, publicHousingPct, overseasBornPct, welfareReliancePct, unemploymentPct, singleParentsPct, familyHouseholdsPct, privateSchoolPct, medianIncomeWeekly, communityDepthIndex, premiumRenovationIndex, homeOfficeIndex, tranquilityIndex, innovationEconomyIndex, alternativeLivingIndex, investorConcentration, negativeGearingExposure, mortgageStress. Apartment/unit metrics are the `unit`-prefixed keys (unitMedianPrice, unitGrossYield, unitMedianRent, …); the unprefixed market keys are houses. Unit data only exists where a suburb has a real unit market — coverage runs ~13-54% of suburbs depending on the field, so a unit filter implicitly excludes house-only suburbs. | |
| offset | No | Row offset — page through results more than 25 deep. `meta.next_offset` gives the value for the next page. | |
| states | No | Comma-separated states — abbreviation or full name, e.g. `VIC` or `Victoria`. Anything else is a 422 listing the valid values (a city name is not a state — use `regions`). | |
| regions | No | Comma-separated EXACT SA4 region names — call GET /v1/suburbs/finder/regions for the list. e.g. `Melbourne - Inner`, `Melbourne - West`. A metro name like `Melbourne` alone will NOT match; an unknown value 422s with the closest real names. | |
| property_type | No | Legacy flag: 'unit' re-points the ten unprefixed house-market keys (medianHousePrice, grossYield, ...) at their unit column. It does NOT affect the explicit `unit`-prefixed keys, which are always units. Prefer the `unit` keys — they are visible in /fields and can be mixed with house keys in one query. | house |