Real Estate Search (Bulk)

POST /api/v2/realestate_searches operationId: realestate_searches

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

This is a bulk version of the real estate search endpoint that allows multiple address lookups to be performed in a single request.

This endpoint accepts up to 50 address lookups in the requests array and applies a shared optional date_from filter to each item.

Each item in the requests array 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

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

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

Address resolution

The address object in each result item 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. Each result item contains its own message and address fields indicating the outcome for that particular address lookup:

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.

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
`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. This filter applies to all items in the requests array. Example: `2015-01-01`
`requests`	array of objects [1..50 items] The list of address lookups to perform.
`requests[].check_id`	string Optional client reference returned in the matching result item. Example: `property_001`
`requests[].gnaf_id`	string [max 15 characters] The GNAF address ID. Mutually exclusive with full_address and street_address/suburb/state/postcode. Example: `GAVIC421647320`
`requests[].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`
`requests[].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`
`requests[].suburb`	string [3..60 characters] The suburb name. Used with street_address for structured address mode. Example: `Lilydale`
`requests[].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`
`requests[].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`

Responses

200

Result of bulk real estate search

application/json

Field	Description
`message`	string A message indicating the overall result of the request. Example: `Ok`
`api_reference`	string (uuid) A unique identifier for this request Example: `738d9a89-b6fe-4fc1-96be-1389b2a506a2`
`results`	array of objects Result item for each request in the requests array.
`results[].check_id`	string or null Echoed check_id from the request item. Example: `property_001`
`results[].message`	string A message indicating the result for this item. `Ok` if the address was found, `Address not found` otherwise. Example: `Ok`
`results[].total_records`	integer Number of real estate records in this item's result set. Example: `3`
`results[].address`	object The resolved address details. Empty object if the address could not be found.
`results[].address.address_id`	string The GNAF address ID Example: `GAVIC421647320`
`results[].address.address`	string The combined street address Example: `20 HARDY ST`
`results[].address.suburb`	string The suburb Example: `LILYDALE`
`results[].address.state`	string The state Example: `VIC`
`results[].address.postcode`	string The postcode Example: `3140`
`results[].records`	array of objects Real estate listing records for this address, sorted by date descending (most recent first)
`results[].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`
`results[].records[].property_type`	string The type of property (e.g. house, townhouse, apartment, unit, flat, studio) Example: `townhouse`
`results[].records[].num_bedrooms`	integer Number of bedrooms Example: `3`
`results[].records[].num_bathrooms`	integer Number of bathrooms Example: `3`
`results[].records[].num_car_spaces`	integer Number of car spaces Example: `2`
`results[].records[].date`	string (date) The date of the listing or sale (YYYY-MM-DD) Example: `2018-03-01`
`results[].records[].estate_agent`	string The name of the estate agent Example: `ABC Property`
`results[].records[].price`	string The listed or sold price. For rentals this will include the rental period (e.g. "$550 per week"). Example: `$720,000`
`results[].error`	string Present when an item-level error occurs.

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

Previous Real Estate Search Next Adverse Media Check

Request body application/json

{
    "date_from": "2015-01-01",
    "requests": [
        {
            "check_id": "property_001",
            "gnaf_id": "GAVIC421647320",
            "full_address": "20 Hardy St Lilydale VIC 3140",
            "street_address": "20 Hardy St",
            "suburb": "Lilydale",
            "state": "VIC",
            "postcode": "3140"
        }
    ]
}

Response

200 Result of bulk real estate search

{
    "message": "Ok",
    "api_reference": "738d9a89-b6fe-4fc1-96be-1389b2a506a2",
    "results": [
        {
            "check_id": "property_001",
            "message": "Ok",
            "total_records": 3,
            "address": {
                "address_id": "GAVIC421647320",
                "address": "20 HARDY ST",
                "suburb": "LILYDALE",
                "state": "VIC",
                "postcode": "3140"
            },
            "records": [
                {
                    "listing_type": "sale",
                    "property_type": "townhouse",
                    "num_bedrooms": 3,
                    "num_bathrooms": 3,
                    "num_car_spaces": 2,
                    "date": "2018-03-01",
                    "estate_agent": "ABC Property",
                    "price": "$720,000"
                }
            ],
            "error": "string"
        }
    ]
}

400 Bad or missing input parameter shared error response

{
    "message": "string"
}

401 Unauthorized - The request is not authorized. shared error response

{
    "message": "API Key Inactive"
}

402 Insufficient Credit - Insufficient credit to process this request shared error response

{
    "message": "Insufficient Credit"
}

403 No access - No permission to process this request shared error response

{
    "message": "No access"
}

429 Rate limited - The request rate limit has been reached shared error response

{
    "message": "Rate limited"
}

5XX Internal error - Internal system error shared error response

{
    "message": "Internal error"
}