HtAG core concepts: places, address keys and data context

A useful property-data workflow starts by identifying the right place, keeping the right context and understanding how records fit together. Once those foundations are clear, it becomes much easier to connect HtAG data to a report, CRM record, research screen or AI-assisted workflow.

This guide explains the core concepts shared by HtAG’s API and MCP tools. For connection instructions, use the MCP setup guide or API setup guide. For individual metric meanings, use the HtAG Data Dictionary.

1. Start with a reference lookup

A place name is a useful label, but it is not enough to identify a market. Different states can have localities with the same name, and one postcode can contain several localities.

Before requesting area data, look up the locality or local government area you mean. Check the returned name, state and postcode where applicable, then keep the matching identifier with its display label.

• Locality identifier: loc_pid identifies a suburb or locality.
• LGA identifier: lga_pid identifies a local government area.

Your interface can display a familiar name such as “Richmond VIC 3121”, while the workflow uses the returned identifier to keep subsequent requests attached to the same place. Do not assume the first search match is the intended one.

The reference endpoints to start with

• GET /v1/reference/locality — find a suburb or locality and retain its returned loc_pid.
• GET /v1/reference/lga — find a local government area and retain its returned lga_pid.

For example, a tightly filtered locality lookup can use:

GET /v1/reference/locality?name=Richmond&state_name=VIC&postcode=3121&limit=5&offset=0

Richmond VIC 3121 is identified as VIC2167 in the published HtAG examples. Inspect your returned record before retaining that identifier. For a council-level lookup, an example is:

GET /v1/reference/lga?name=Sydney&state_name=NSW&limit=5&offset=0

Use the returned lga_pid; do not substitute the locality identifier or a postcode. Endpoint paths here are relative to https://api.htagai.com.

2. Understand what an address key does

At property level, HtAG uses an address key to connect records for the same address. It is derived from the standardised address, rather than from the way someone happened to type it into a form.

The general format expands standard address abbreviations, removes spaces and other special characters, and uses upper case. A unit or flat prefix retains a forward slash. These formatting rules explain why differently typed versions of an address can lead to a common key.

For a production workflow, retain the canonical key returned by an accepted address match. Keep it alongside the human-readable address and the original entered text so a team member can review how the identity was established. Treat the returned key as an identifier to reuse, rather than repeatedly rebuilding it from display text.

What address keys look like

Address	Address key
10 Mary Street, Richmond VIC 3121	10MARYSTREETRICHMONDVIC3121
12 Smith Street, Richmond VIC 3121	12SMITHSTREETRICHMONDVIC3121
Unit 4, 123 George Street, Sydney NSW 2000	4/123GEORGESTREETSYDNEYNSW2000

The two Richmond keys come from the published HtAG property examples. The unit address is an illustrative formatting example, not a verified property record. Notice the expanded street type, uppercase letters, omitted spaces and punctuation, and the retained slash after the unit number.

A unit-level key and the building’s address key identify different address records. Keep the unit information when matching an apartment. In production, use the key returned by the accepted match rather than treating an illustrative string as a verified identity.

3. Separate formatting from matching

Standardisation cleans up address text and separates its components. Matching resolves that text against address records and supplies the identity and location details you need to inspect.

A neatly formatted address or generated key does not, by itself, prove that an address exists or that it is the property the person intended.

When you need a matched property, resolve the entered address, review the candidate’s unit, street number, street, locality, state and postcode, and accept the correct match before enrichment. If the result is ambiguous, ask for clarification. Preserve a customer’s confirmed details separately from source suggestions.

Which operation does which job?

POST /v1/address/standardise accepts up to 50 Australian address strings and returns standardised components and generated address keys. Use it for a format-only job, such as tidying imported address text. Pair each result with its input using the returned input_index.

GET /v1/address/geocode resolves free-text address input to candidate address records, returning canonical address keys, GNAF identifiers, coordinates, geography codes and standardised elements. Use it when your workflow needs a matched property identity.

For example, this bounded lookup asks for candidate matches to one address:

GET /v1/address/geocode?address=10%20Mary%20Street%2C%20Richmond%20VIC%203121&limit=5

Inspect the returned candidates and accept the correct address before retaining its address_key for property enrichment. A standardisation-generated key alone is not evidence of a database match.

The practical pattern is entered address → geocode → review and accept the match → retain the returned address key → enrich the property record. Standardisation is a separate option when formatting is the task; it is not a mandatory first step before geocoding.

4. Keep geographic levels distinct

For a detailed explanation of cell IDs, resolutions 5–9 and the supported administrative-geography crosswalks, read our H3 format, endpoints and geography-mapping guide.

A property, suburb, LGA, postcode, ABS statistical area and H3 cell describe different things. A figure for one geographic level should remain labelled at that level.

A postcode is not a suburb, and an H3 cell is not an official suburb boundary. Cells and administrative areas can overlap. Geographic crosswalks, also called concordances, help relate identifiers across these systems, but the relationship may be one-to-many.

Keep the geography and any relevant map resolution with the record. When combining datasets, inspect the mapping and its documented weighting rather than assuming each area has a single equivalent. Do not average area medians to manufacture a statistic for a larger region.

5. Compare the same selection

Two records can share a place name and still represent different groups of properties. Keep property type, bedroom selection and other applicable filters alongside the data.

Start with a consistent baseline, such as one locality and one property type. Add a narrower selection when it serves the question and the data supports it. When comparing two areas or two periods, confirm that the selections are equivalent.

This context also limits the claim you can make: an area-level observation describes the selected market, rather than predicting an individual property’s outcome.

6. Distinguish the dates

The date you retrieved a record is not necessarily the period the data describes.

• Reporting period: the month, quarter or other window represented by the observation.
• Source update date: when the underlying record was refreshed, where supplied.
• Capture time: when your workflow retrieved and saved it.

Retain the available dates and use clear labels in the output. A freshly retrieved response may describe an earlier reporting period. Historical series may also be revised in later releases, so calculate comparisons from a coherent set of records rather than mixing old downloads with newly revised values.

7. Keep missing values separate from zero

A missing or null value can mean that no suitable record exists or that a value is unavailable. It is not a numeric zero. A documented zero can be a valid observation.

Preserve this distinction in storage, calculations and presentation. Show “unavailable” when a necessary value is missing, or omit an optional field. Do not fill a gap with zero or invent a replacement. Check the relevant documentation when a missing value affects whether the workflow can continue.

8. Reuse a dated snapshot deliberately

Several contacts or screens may need the same area context. Store a reviewed snapshot and reuse it when the location, selection and data version are the same.

A useful cache key includes the identifier, geographic level, property selection and relevant period or capture version. Keep the original request context with the response so another person can reproduce the view.

Set refresh rules around the data’s update cycle and your workflow’s needs. Check whether historical values are revised before choosing an append-only refresh. Changing a display filter or reopening a saved report should reuse the stored data when a new retrieval is unnecessary.

9. Plan the workload before retrieving data

A workflow’s number of steps, requests and returned records are different measures. A single request can return many rows, and pagination can add further requests.

Begin with one small geography or property set. Define the filters, row limits and whether another page is needed, then check current pricing. When using an AI assistant, ask it to show the proposed workload before execution and keep retries or broader searches deliberate.

A simple working pattern

1. Identify: look up the intended place, or inspect and accept the correct address match.
2. Scope: choose the geographic level and property selection.
3. Retrieve: run a bounded, planned request.
4. Review: check identity, dates, completeness and the context attached to the result.
5. Reuse: save the snapshot with a deliberate refresh rule.

Those foundations apply whether you are building software or asking an AI assistant to help with research.

Continue with the Data Dictionary when you need to understand what a market metric means and how to interpret it. Use the API reference when you need the exact request and response contract.