AgencyHub

Appearance

Suburbs API Reference ​

List Suburbs ​

GET /api/v1/suburbs

Retrieve a list of suburbs based on various filter criteria.

Query Parameters ​

ParameterTypeDescription
pageNumberPage number (default: 1)
limitNumberNumber of items per page (default: 20, max: 100)
nameStringSuburb name(s), can be comma-separated for multiple names (case-insensitive, partial match)
slugStringSuburb slug (case-insensitive, partial match)
suburbStringSuburb name (case-insensitive, starts with match)
stateStringState name (case-insensitive, exact match)
postcodeStringPostcode (case-insensitive, starts with match)
regionStringRegion Names(s), can be comma-separated
areanameStringArea Names(s), can be comma-separated
excludeStringComma-separated list of suburb IDs to exclude from the results

Example Request ​

javascript
const headers = {
  "x-access-key": "your_access_key_here",
  "x-secret-key": "your_secret_key_here",
};

fetch("https://agencyhubapi.stepps.net/api/v1/suburbs?name=New,Spring&state=QLD", { headers })
  .then((response) => response.json())
  .then((data) => console.log(data));

Example Response ​

json
{
  "total": 3673,
  "hasNext": true,
  "totalPage": 184,
  "data": [
    {
      "_id": "65c43a3dbbe36eeaec8bacf4",
      "name": "Abbotsford NSW 2046",
      "slug": "abbotsford-nsw-2046",
      "suburb": "Abbotsford",
      "state": "NSW",
      "postcode": "2046",
      "areaName": "Inner West",
      "regionName": "Sydney Region",
      "surroundingSuburbs": null
    },
    {
      "_id": "65c5b464e952cbc0f2629a9e",
      "postcode": "3067",
      "suburb": "Abbotsford",
      "state": "VIC",
      "areaName": "Yarra City Council - Greater Area",
      "regionName": "Melbourne Region",
      "name": "Abbotsford Vic 3067",
      "slug": "abbotsford-vic-3067",
      "surroundingSuburbs": [
        {
          "name": "East Melbourne VIC 3002",
          "slug": "east-melbourne-vic-3002"
        },
        {
          "name": "Collingwood North VIC 3066",
          "slug": "collingwood-north-vic-3066"
        },
        {
          "name": "Collingwood VIC 3066",
          "slug": "collingwood-vic-3066"
        },
        {
          "name": "Clifton Hill VIC 3068",
          "slug": "clifton-hill-vic-3068"
        },
        {
          "name": "Richmond VIC 3121",
          "slug": "richmond-vic-3121"
        },
        {
          "name": "Fairfield VIC 3078",
          "slug": "fairfield-vic-3078"
        },
        {
          "name": "Hawthorn VIC 3122",
          "slug": "hawthorn-vic-3122"
        },
        {
          "name": "Kew VIC 3101",
          "slug": "kew-vic-3101"
        }
      ]
    },
    {
      "_id": "65c5af56e952cbc0f25f373f",
      "state": "SA",
      "suburb": "Aberfoyle Park",
      "postcode": "5159",
      "areaName": "South & South East Suburbs",
      "regionName": "Adelaide Region",
      "name": "Aberfoyle Park SA 5159",
      "slug": "aberfoyle-park-sa-5159",
      "surroundingSuburbs": null
    }
    // ... more suburbs
  ]
}

List Postcodes ​

GET /api/v1/suburbs/postcodes

Retrieve a list of postcodes based on various filter criteria.

Query Parameters ​

ParameterTypeDescription
pageNumberPage number (default: 1)
limitNumberNumber of items per page (default: 20, max: 100)
suburbStringSuburb name (case-insensitive, starts with match)
stateStringState name (case-insensitive, exact match)
postcodeStringPostcode (case-insensitive, starts with match)
regionStringRegion Names(s), can be comma-separated
areanameStringArea Names(s), can be comma-separated

Example Request ​

javascript
const headers = {
  "x-access-key": "your_access_key_here",
  "x-secret-key": "your_secret_key_here",
};

fetch("https://agencyhubapi.stepps.net/api/v1/suburbs/postcodes?suburb=Abbotsford", { headers })
  .then((response) => response.json())
  .then((data) => console.log(data));

Example Response ​

json
{
  "success": true,
  "data": [
    {
      "postcode": "2046",
      "state": "NSW"
    },
    {
      "postcode": "3067",
      "state": "VIC"
    }
    // ... more postcodes
  ]
}

List Regions ​

GET /api/v1/suburbs/regions

Retrieve a list of regions based on various filter criteria.

Query Parameters ​

ParameterTypeDescription
pageNumberPage number (default: 1)
limitNumberNumber of items per page (default: 20, max: 100)
suburbStringSuburb name (case-insensitive, starts with match)
stateStringState name (case-insensitive, exact match)
postcodeStringPostcode (case-insensitive, starts with match)
regionStringRegion Names(s), can be comma-separated
areanameStringArea Names(s), can be comma-separated

Example Request ​

javascript
const headers = {
  "x-access-key": "your_access_key_here",
  "x-secret-key": "your_secret_key_here",
};

fetch("https://agencyhubapi.stepps.net/api/v1/suburbs/regions?suburb=Abbotsford", { headers })
  .then((response) => response.json())
  .then((data) => console.log(data));

Example Response ​

json
{
  "success": true,
  "data": [
    "Adelaide Region",
    "Canberra",
    "Central & Midlands Region",
    "Central Queensland Greater Region",
    "Central West Region",
    "City & North",
    "Clare Valley & Mid North Region",
    "Coastal",
    "Darling Downs & South West Greater Region",
    "Darwin Region",
    "Devonport & Central Coast Region",
    "East Coast Region",
    "Eastern Suburbs",
    "Far North Queensland Greater Region",
    "Far North Region",
    "Gascoyne",
    "Gippsland Greater Region",
    "Gold Coast",
    "Gold Coast Greater Region",
    "Goldfields-Esperance"
  ]
}

List Area Names ​

GET /api/v1/suburbs/areanames

Retrieve a list of Area Names based on various filter criteria.

Query Parameters ​

ParameterTypeDescription
pageNumberPage number (default: 1)
limitNumberNumber of items per page (default: 20, max: 100)
suburbStringSuburb name (case-insensitive, starts with match)
stateStringState name (case-insensitive, exact match)
postcodeStringPostcode (case-insensitive, starts with match)
regionStringRegion Names(s), can be comma-separated
areanameStringArea Names(s), can be comma-separated

Example Request ​

javascript
const headers = {
  "x-access-key": "your_access_key_here",
  "x-secret-key": "your_secret_key_here",
};

fetch("https://agencyhubapi.stepps.net/api/v1/suburbs/areanames?suburb=Abbotsford", { headers })
  .then((response) => response.json())
  .then((data) => console.log(data));

Example Response ​

json
{
  "success": true,
  "data": [
    "Adelaide",
    "Adelaide Hills",
    "Ararat - Greater Area",
    "Armadale & Surrounds",
    "Armidale - Greater Region",
    "Augusta-Margaret River & Surrounds",
    "Aveley & Surrounds",
    "Bainsdale - Greater Area",
    "Ballarat - Greater Area",
    "Ballina - Greater Area",
    "Banyule Council - Greater Area",
    "Barossa Valley",
    "Bassendean & Surrounds",
    "Bayside - Greater Area",
    "Bayswater & Surrounds",
    "Belconnen",
    "Bellingen - Greater Area",
    "Belmont & Surrounds",
    "Bendigo - Greater Area",
    "Beverley & Surrounds"
  ]
}

Error Handling ​

The API uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with our servers.

CodeDescription
200OK - The request was successful
400Bad Request - The request was invalid or cannot be served
401Unauthorized - The request requires authentication
403Forbidden - The server understood the request but refuses to authorize it
404Not Found - The requested resource could not be found
500Internal Server Error - The server encountered an unexpected condition

For more information on using these endpoints, please refer to our Authentication Guide and Quick Start Guide.