Getting Started with the HtAG API

Your first useful HtAG integration can be small: identify one market, request one dated summary and show the result with enough context for a reader to understand it. This guide uses a verified Richmond VIC 3121 house-market snapshot so you can see the whole path before connecting live data.

See the first-request flow

View the demo screenshot

The interactive concept above lets you move through locality lookup, market request and customer-facing output. It is a product flow built from captured data, not a screenshot of the Developer Portal. Opening it makes no HtAG API request.

What you need

• An HtAG account. Sign in or create an account.
• An API key created in the Developer Portal.
• A server-side HTTP client such as curl, Postman or your application backend.

Keep the API key on your server. Do not place it in browser JavaScript, a public repository or a screenshot.

Step 1: resolve the locality

Start with GET /reference/locality. This avoids confusing places that share a name and gives your later market request a stable identifier. For the example used here, Richmond VIC 3121 resolves to VIC2167.

Store the identifier with the display name and state. Your interface can still say “Richmond VIC 3121”; your backend can use the stable identifier for data requests and cache keys.

Step 2: request the market summary

Use GET /markets/summary with level suburb, area ID VIC2167, property type house and bedrooms All. Pass your API key in the x-api-key header. Check the REST reference for the current base URL and exact parameter syntax before shipping your integration.

curl -H "x-api-key: YOUR_API_KEY" "https://api.htagai.com/v1/markets/summary?level=suburb&area_id=VIC2167&property_type=house&bedrooms=All"

Read the response as a dated market snapshot

The summary fields have specific meanings. Typical Price is HtAG’s adjusted suburb-level price measure, not a simple median or an individual property valuation. 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.

A verified response captured on 10 September 2026 returned one record in results[]. These are the selected fields used by the example:

{
  "results": [
    {
      "area_id": "VIC2167",
      "period_end": "2026-08-31T00:00:00+00:00",
      "property_type": "house",
      "bedrooms": "All",
      "typical_price": 1666826.0,
      "rent": 1054.0,
      "gross_yield": 0.0329
    }
  ],
  "total": 1
}

In a customer-facing view, that becomes a typical price of $1,666,826, rent of $1,054 per week and gross yield of 3.29%. The yield arrives as a decimal fraction, so format 0.0329 as 3.29%. Keep the period, property type and bedroom selection beside the figures.

typical_price is a market-level figure for the selected suburb segment. It is not a valuation of an individual property.

Make the result useful to a customer

• Show the locality, property type and bedroom selection in the heading.
• Show “period ended 31 August 2026” rather than calling the figures real time.
• Format money and percentages without changing the underlying values.
• Publish the card only after validating the identity, segment, period and three displayed measures together.
• Cache the response by area, property type, bedrooms and period so several readers can reuse it.

A page built from this captured example makes zero HtAG calls when a reader opens it. A production application can refresh the cached record when a newer period appears.

Where to go next

Use the REST reference to confirm request details, then test the two-operation flow in your authorised environment. If you want an AI assistant to call HtAG tools, continue with the MCP documentation.