# Real Estate Search (Bulk)

`POST /realestate_searches`

- Live: `POST https://gdapi.globaldata.net.au/api/v2/realestate_searches`
- Sandbox: `POST 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

| Field | Type | 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` |

**Sample request**

```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"
        }
    ]
}
```

## Responses

### 200 Result of bulk real estate search

Content type: `application/json`

| Field | Type | 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. |

**Sample response**

```json
{
    "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"
        }
    ]
}
```

Standard error responses: 400, 401, 402, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))