Search suburbs
/v1/suburbs/finder/search30¢ per callBoolean-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.
Authorization
Request
The only values you send. Fields under Responses below are what comes back — you never pass those.
Query parameters
filteroptionalrange filters — add one or more; all must matchLeave min or max blank for an open-ended range. Each row is one criterion; all must match.
statesstringoptionalComma-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`).
regionsstringoptionalComma-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_typestringoptionalLegacy 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.
sortoptionalrank the results by a fieldlimitintegeroptionalPage 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`.
offsetintegeroptionalRow offset — page through results more than 25 deep. `meta.next_offset` gives the value for the next page.
Responses
Successful Response
suburbsarray of FinderRowalways returnedMatched suburbs, sorted.
metaobjectalways returnedPagination + total + the value-reveal policy for a search.
/v1/suburbs/finder/searchcurl --request GET \
--url 'https://api.microburbs.com.au/v1/suburbs/finder/search' \
--header 'Authorization: Bearer test'{
"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
}
]
}
}