Automate Suburb Comparison with the HtAG API

Turn a shortlist into a fair comparison

Suburb research becomes hard to trust when every row comes from a different source, period or property segment. A useful comparison starts by making those inputs identical. Resolve each suburb to its HtAG area ID, select one property type and bedroom group, and compare records from the same reporting period.

The example below does that for Richmond, Carlton and Fitzroy in Victoria. Every observation is for houses across all bedroom counts, and every record is from the period ended 31 August 2026.

View the demo screenshot

What the snapshot shows

HtAG’s Typical Price is an adjusted suburb-level price measure designed to reduce distortion from changing sales mix, low volume and outliers; it is different from a simple median and does not value an individual property. The dictionary defines suburb Median Rent as the middle weekly asking rent over a rolling 12 months; this example displays the weekly median rent returned by the market summary. It defines Gross Rental Yield as annual rent divided by Typical Price before costs and vacancy.

Richmond has the highest typical price in this three-market set at $1,666,826. Fitzroy has the highest reported weekly rent at $1,137 and the highest gross yield at 3.82%. Carlton has the lowest typical price at $1,460,205, with a reported weekly rent of $1,025 and gross yield of 3.65%.

Those results do not produce a universal winner. Price, rent and gross yield answer different questions, and gross yield is an annual rent-to-price measure before ownership costs. The right emphasis depends on the investor’s budget, holding period, cash-flow tolerance and risk profile.

A comparison workflow you can automate

1. Write the brief first. Record the budget, intended hold period, equity objective and risk tolerance before choosing weights or filters.
2. Resolve geography. Use the locality reference operation to turn each suburb and state into an unambiguous area_id.
3. Fix the segment. Apply the same geographic level, property type, bedroom selection and reporting period to every market.
4. Fetch one comparable dataset. The market summary operation can return the three areas in one response envelope.
5. Validate the comparison. Use complete records and the same measures for all three suburbs.
6. Compare, then investigate. Use the shortlist view to decide which additional supply, demand, affordability or risk evidence deserves attention.

Request the same market slice

The current REST contract uses a geographic level and resolved area_id values. A request for this example has the following shape:

GET /v1/markets/summary
  ?level=suburb
  &area_id=VIC2167
  &area_id=VIC494
  &area_id=VIC916
  &property_type=house
  &bedrooms=All
  &limit=3

The response contains a results array and total. Relevant fields include period_end, typical_price, rent, gross_yield, transaction volumes and confidence. In this captured cohort, all three summary records carry High confidence.

Use the shortlist to guide the next conversation

These three headline measures describe price point and cash-flow context, but a purchase decision still needs triangulation. Recent growth, stock on market, inventory, days on market, vacancy and affordability, together with risk and confidence measures, add context to the reading.

If you need a ranked result, use the market ranking operation after the brief and shortlist are defined. It applies weighted metric deciles across the supplied cohort and returns diagnostics. Scores only make sense within that exact shortlist and set of weights; they should not be copied between unrelated comparisons.

Keep each comparison on one data release as well as one reporting period. HtAG recalibrates Typical Price for current and historical periods when new data arrives. Refresh the complete shortlist together and preserve the capture used for the customer report, so every row remains comparable. See HtAG’s explanation of Typical Price revisions.

Keep the production workflow reviewable

Cache a dated snapshot by area, property type and bedroom selection. Refresh it when the expected source period changes, retain the original units, and calculate display percentages once. Validate the same complete set of measures across the shortlist before sharing the comparison.

Readers of this article inspect a fixed captured dataset, so the visual makes no HtAG API calls. A production application should keep its API key on the server and expose only the data its interface needs.

Read the market summary API reference, explore market ranking, or sign in to the developer portal to test an authorised request.