Suburb Data API reference

Quick start

1. 01

   Enable API access

   Sign in to the research platform, go to your profile and select the API tab. Accept the API Terms and complete account enablement.

2. 02

   Generate a key

   Create a key in the API tab. Keys are shown once — store it in your server-side secret manager, never in client code.

3. 03

   Make your first request

   Start in trial mode, which carries no Data Charge, then switch to live once your integration returns what you expect.

curl "https://api.suburbdata.com.au/v1/reference/months" \
  -H "Authorization: Bearer sd_live_xxxxxxxxxxxxxxxx"

Authentication

Every request is authenticated with a bearer key sent in the Authorization header. Keys are issued in the API tab of the research platform and are tied to your account and its prepaid credit.

Authorization: Bearer sd_live_xxxxxxxxxxxxxxxx

Trial & live mode

One key covers both modes, so you can build against trial indefinitely and flip to live when your integration returns what you expect.

Trial mode

Returns the same response shapes and the same fields as live mode, with mock, non-genuine values. No Data Charge, no time limit. Build and test your entire integration here.

Live mode

Returns real data. Every request debits your prepaid credit. Requires a credited account and the Account Enablement Fee.

Switching

One key covers both modes. The mode is selected per request with the X-SD-Mode header (trial or live); responses echo it back in meta.mode so you can assert it in your tests.

curl "https://api.suburbdata.com.au/v1/reference/months" \
  -H "Authorization: Bearer sd_live_xxxxxxxxxxxxxxxx" \
  -H "X-SD-Mode: trial"

Base URL & versioning

https://api.suburbdata.com.au/v1

• •The version is part of the path. A breaking change ships as a new version; v1 keeps working while it is supported.
• •Additive changes — new fields, new endpoints, new metric codes — can appear within a version, so parse responses tolerantly.
• •Data is published monthly, typically around the 6th. Pin a month when you need reproducible results.

Requests & conventions

Protocol

HTTPS only. Plain HTTP requests are rejected.

Format

JSON request and response bodies. Send Accept: application/json.

Months

Data months are strings in YYYY-MM format, for example 2026-07.

Currency

Monetary values are whole Australian dollars, GST inclusive where applicable.

Missing data

You are not charged for missing data.

Timeouts

Allow at least 30 seconds for search and batch requests.

Endpoints

curl "https://api.suburbdata.com.au/v1/markets/0812-leanyer-house/metrics?month=2026-07&metrics=dsr3,yield" \
  -H "Authorization: Bearer sd_live_xxxxxxxxxxxxxxxx"

{
  "market_id": "0812-leanyer-house",
  "month": "2026-07",
  "metrics": [
    { "code": "dsr3", "name": "DSR3", "value": 71 },
    { "code": "yield", "name": "Yield", "value": 6.1 }
  ],
  "meta": { "charged": true, "mode": "live" }
}

curl "https://api.suburbdata.com.au/v1/markets/metrics/history?market_ids=0812-leanyer-house&metric=dsr3&end_month=2026-07&months=12" \
  -H "Authorization: Bearer sd_live_xxxxxxxxxxxxxxxx"

{
  "metric": "dsr3",
  "series": [
    { "market_id": "0812-leanyer-house",
      "points": [
        { "month": "2025-07", "value": 64 },
        { "month": "2025-08", "value": 66 }
      ] }
  ],
  "meta": { "charged": true, "mode": "live" }
}

curl -X POST "https://api.suburbdata.com.au/v1/markets/search" \
  -H "Authorization: Bearer sd_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "month": "2026-07",
    "filters": [{ "metric": "dsr3", "min": 60, "max": 100 }],
    "return_metrics": ["dsr3", "yield"],
    "sort": [{ "metric": "dsr3", "direction": "desc" }],
    "limit": 25
  }'

{
  "month": "2026-07",
  "count": 25,
  "matches": [
    { "market_id": "0812-leanyer-house",
      "suburb": "Leanyer", "state": "NT", "property_type": "House",
      "metrics": { "dsr3": 71, "yield": 6.1 } }
  ],
  "meta": { "charged": true, "mode": "live" }
}

curl -X POST "https://api.suburbdata.com.au/v1/cost" \
  -H "Authorization: Bearer sd_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "endpoint": "/markets/search", "payload": { "limit": 25, "return_metrics": ["dsr3"] } }'

{
  "currency": "AUD",
  "indicative_cost": 4.20,
  "balance_after": 195.80
}

curl "https://api.suburbdata.com.au/v1/reference/months" \
  -H "Authorization: Bearer sd_live_xxxxxxxxxxxxxxxx"

{
  "months": ["2026-07", "2026-06", "2026-05"],
  "latest": "2026-07",
  "meta": { "charged": false }
}

Errors

Errors return a standard JSON body with a stable machine-readable code and a request_id — quote it when you contact support. A failed request carries no Data Charge.

{
  "error": {
    "code": "insufficient_credit",
    "status": 402,
    "message": "Your balance does not cover this Data Charge.",
    "request_id": "req_01J9X2K7QF"
  }
}

Rate limits

• •Requests are subject to frequency and volume limitations. Talk to us before you build if your use case needs higher limits.
• •Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset so you can throttle before you are throttled.
• •A 429 response includes Retry-After in seconds. Retry with exponential backoff and jitter — never in a tight loop.
• •Do not expose the API directly to end users who could trigger unlimited requests. Apply your own limits, since every request you make is a request you pay for.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 41
Retry-After: 41

Usage rules

• •Call the API from your server only. Keys must never be exposed in browsers, mobile apps or public repositories.
• •No bulk export, resale or redistribution of the underlying dataset.
• •Data may not be used to train machine learning or AI models.
• •Display “Source: SuburbData.com.au” wherever API-derived values are shown to your users.
• •Cache reference lookups freely; do not cache charged responses.

This is a summary only. The full commercial and licence terms are set out in the API Terms you accept at enablement.

Support