Multi-criteria suburb screener (Pro+ tier)

Costs 5 credits, the most expensive read on the API: it scans every covered suburb. Returns every suburb that clears ALL of the thresholds you pass. Stack as many as you like in one call: yield, 1/3/5-year price growth, 1/5-year population growth, rent growth, median price, vacancy, inventory, market heat, days on market, distance to the CBD, unemployment, socioeconomic score, owner-occupier share, population and sales volume. **A worked screen, start to finish.** 1. Screen the suburbs. For NSW houses above 5% yield, 25% five-year growth and 1% five-year population growth: `GET /v1/suburbs/screen?state=NSW&min_yield=5&min_growth_5yr=25&min_population_growth_5yr=1` 2. Read `total_matches`. If it is 0, read `hint`: when the confidence bar is what emptied the result, the response tells you how many suburbs would match at `min_confidence=any`, so you know whether to relax the bar or a threshold. 3. Narrow or widen. `location_type=metro` or `regional` is usually the most effective single filter, because a high yield bar on its own tends to surface small rural localities; `min_population` and `max_distance_to_cbd_km` do similar work. Order the result with `sort=` (default `yield`) and page with `limit` and `offset`. 4. Get the properties. Pass each match to `/v1/properties/listings?state=NSW&suburb=<suburb>` for the individual listings, or to `/v1/suburbs/{state}/{suburb}` for the full statistics behind the row. Use `/v1/suburbs/rankings` instead when you want the top N ordered by a single metric. Use this endpoint when you want everything above a set of cutoffs. **Set `min_confidence` deliberately.** It defaults to `medium` and gates the evidence behind the filters you actually used: the median always, yield only when you filter or sort on yield, growth only when you filter or sort on growth. Screening on population growth alone is never narrowed by yield confidence. Drop to `low` or `any` to widen, and read `median_confidence`, `yield_confidence` and `growth_1yr_confidence` on each row to see what you accepted. **Check `postcode_area_figures` before acting on a row.** When true, the median and yield describe the whole postcode rather than that suburb, so several localities sharing that postcode return identical numbers and are not independent matches. These rows appear only at `min_confidence=any`. **Three data facts that should shape your thresholds.** Multi-year growth is single-source: 8,283 suburbs carry two or more independent source families on 1-year growth and none do on the 3, 5 or 10-year windows, so `min_confidence` on a multi-year period tests only that a source reported it (8,589 suburbs, against 820 with none), and `growth_1yr_confidence` is named for the one window that carries a rating. Inventory is populated for 88% of suburbs on houses but 34% on units, so `max_inventory_months` with `property_type=units` excludes most of the table. Heat score is banded rather than continuous, with 60 and 55 alone accounting for 58% of rated suburbs, so move `min_heat_score` in steps of 5. Invalid parameters return 400 naming the parameter at fault rather than falling back to a default, so a typo in a threshold fails loudly instead of returning a screen you did not ask for.

curl "https://api.propradar.com.au/v1/suburbs/screen?state=NSW&min_yield=5&min_growth_5yr=25&min_population_growth_5yr=1" \
  -H "X-API-Key: pr_live_..."

{ "state": "NSW", "property_type": "houses",
  "min_confidence": "medium", "sort": "yield",
  "count": 3, "total_matches": 3,
  "pagination": { "limit": 50, "offset": 0, "next_offset": null },
  "results": [{ "suburb": "BROKEN HILL", "postcode": 2880,
                "median_price": 250000, "yield_pct": 7.5,
                "growth_1yr_pct": 4.2, "growth_5yr_pct": 94.0,
                "population": 17700, "population_growth_5yr_pct": -1.2,
                "vacancy_rate_pct": 1.4, "days_on_market": 62,
                "sales_12mo": 310,
                "rent_growth_1yr_pct": 8.1, "inventory_months": 2.4,
                "heat_score": 60, "location_type": "regional",
                "distance_to_cbd_km": 940.2, "unemployment_rate_pct": 3.1,
                "socioeconomic_score": 25, "owner_occupied_pct": 66.2,
                "median_confidence": "medium", "yield_confidence": "medium",
                "growth_1yr_confidence": "limited",
                "postcode_area_figures": false }] }