Real Estate Search

POST /api/v2/realestate_search operationId: realestate_search

Live: https://gdapi.globaldata.net.au/api/v2/realestate_search · Sandbox: https://sandbox-gdapi.globaldata.net.au/api/v2/realestate_search

The real estate search query returns Australian real estate listing history (sale, sold, and rental events) for a given property address, sourced from the Global Data Australian property universe.

The query accepts an address in one of three formats:

A GNAF ID (the unique GNAF address identifier)
A full address as a single string
A structured address with street_address, suburb, state, and postcode as separate fields

Results are returned in reverse chronological order (most recent first).

An optional date_from parameter can be provided to filter results to only include records on or after the specified date.

Address resolution

The address object in the response represents the resolved address that was used to search the real estate universe:

When a GNAF ID is provided, the returned address is the exact address referenced by that GNAF ID.
When a text-based address is provided (full address or structured address), the system will resolve the input to the best matching address in the GNAF database. The returned address may include minor corrections or standardisations compared to the original input (e.g. corrected spelling, expanded abbreviations, standardised formatting) if these were needed to match a valid address.

Response behaviour

The endpoint always returns HTTP 200. The message and address fields indicate the outcome:

Scenario	`message`	`address`	`records`
Address found, records exist	`Ok`	Populated with the resolved address	Array of real estate records
Address found, no records	`Ok`	Populated with the resolved address	Empty array
Address not found	`Address not found`	Empty object	Empty array

An address may not be found if the GNAF ID does not exist, or if the text-based address could not be resolved to a valid address in the GNAF database.

Address input modes

Only one address input mode can be used per request. The modes are mutually exclusive:

Mode	Parameters	Description
GNAF ID	`gnaf_id`	Direct lookup by GNAF address ID. This is the most efficient lookup.
Full address	`full_address`	A complete address as a single string (e.g. "20 Hardy St Lilydale VIC 3140"). The system will parse and resolve the address.
Structured address	`street_address`, `suburb`, `state`, `postcode`	Address components provided separately. At minimum, `street_address` is required.

Sandbox environment

When simulating queries in the sandbox environment the system will use a reduced sample dataset. The following GNAF IDs will return real estate records:

GNAF ID	Address	Suburb	State	Postcode	Records
GAVIC421647320	20 HARDY ST	LILYDALE	VIC	3140	3
GANSW716615055	35 YARALLA ST	CONCORD WEST	NSW	2138	2
GANSW712900961	22 BRABYN ST	WINDSOR	NSW	2756	1

The following GNAF IDs exist in the sample dataset but have no real estate records:

GNAF ID	Address	Suburb	State	Postcode
GAVIC419608268	8 WALTHAM ST	RICHMOND	VIC	3121
GANSW705730292	6 WATERVIEW CL	PORT MACQUARIE	NSW	2444

Request body

Content type application/json.

Field	Description
`gnaf_id`	string [max 15 characters] The GNAF address ID. Mutually exclusive with full_address and street_address/suburb/state/postcode. Example: `GAVIC421647320`
`full_address`	string [4..255 characters] A complete Australian address as a single string. The system will parse and resolve this to a GNAF address. Mutually exclusive with gnaf_id and street_address/suburb/state/postcode. Example: `20 Hardy St Lilydale VIC 3140`
`street_address`	string [4..100 characters] The street address component (e.g. "20 Hardy St"). Required when using structured address mode. Mutually exclusive with gnaf_id and full_address. Example: `20 Hardy St`
`suburb`	string [3..60 characters] The suburb name. Used with street_address for structured address mode. Example: `Lilydale`
`state`	string The Australian state or territory abbreviation. Used with street_address for structured address mode. Enum: `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA` Example: `VIC`
`postcode`	string [3..4 characters] The 3 or 4 digit Australian postcode. Used with street_address for structured address mode. Pattern: `^\d{3,4}$` Example: `3140`
`date_from`	string (date) Optional date filter in YYYY-MM-DD format. When provided, only real estate records with a date on or after this value will be returned. Example: `2015-01-01`

Responses

200

Result of real estate search

application/json

Field	Description
`message`	string A message indicating the result of the request. This will be `Ok` if the request was successful. Example: `Ok`
`api_reference`	string (uuid) A unique identifier for this request Example: `738d9a89-b6fe-4fc1-96be-1389b2a506a2`
`total_records`	integer Number of real estate records in the result set Example: `3`
`address`	object The resolved address details. Empty object if the address could not be found.
`address.address_id`	string The GNAF address ID Example: `GAVIC421647320`
`address.address`	string The combined street address Example: `20 HARDY ST`
`address.suburb`	string The suburb Example: `LILYDALE`
`address.state`	string The state Example: `VIC`
`address.postcode`	string The postcode Example: `3140`
`records`	array of objects Real estate listing records for this address, sorted by date descending (most recent first)
`records[].listing_type`	string The type of real estate listing: `sale` - Property listed for sale `sold` - Property has been sold `rent` - Property listed for rent Enum: `sale`, `sold`, `rent` Example: `sale`
`records[].property_type`	string The type of property (e.g. house, townhouse, apartment, unit, flat, studio) Example: `townhouse`
`records[].num_bedrooms`	integer Number of bedrooms Example: `3`
`records[].num_bathrooms`	integer Number of bathrooms Example: `3`
`records[].num_car_spaces`	integer Number of car spaces Example: `2`
`records[].date`	string (date) The date of the listing or sale (YYYY-MM-DD) Example: `2018-03-01`
`records[].estate_agent`	string The name of the estate agent Example: `ABC Property`
`records[].price`	string The listed or sold price. For rentals this will include the rental period (e.g. "$550 per week"). Example: `$720,000`

Standard error responses: 400 401 402 403 429 5XX See common error responses

Previous Property Detail Next Real Estate Search (Bulk)