Suburb - Finder

Search suburbs

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.

get/v1/suburbs/finder/search

Request

  • Base URL: https://api.microburbs.com.au
  • URL: https://api.microburbs.com.au/v1/suburbs/finder/search
  • Auth: HTTP bearer

Query parameters

filterstring[]

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.

statesstring nullable

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).

Example:VIC
regionsstring nullable

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_typestring

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.

sort'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' | '-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' nullable

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.

limitinteger

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.

offsetinteger

Row offset — page through results more than 25 deep. meta.next_offset gives the value for the next page.

Response

Successful Response

availableboolean nullable

false on no-data responses. Omitted on success — branch on data !== null if you want a single discriminator.

reasonstring nullable

Machine-readable slug naming the no-data condition (e.g. no_avm_for_GANSW704074813). Stable per endpoint. Omitted on success.

messagestring nullable

Human-readable explanation. Omitted on success.

Example response

{
  "data": {
    "meta": {
      "limit": 25,
      "offset": 0,
      "returned": 25,
      "total": 126
    },
    "suburbs": [
      {
        "lga": "Lake Macquarie",
        "rank": 3,
        "sa4": "Newcastle and Lake Macquarie",
        "state": "NSW",
        "suburb": "Windale",
        "value": 0.163
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.