Address Validation API

The Address API provides real-time search and validation of Australian addresses using the G-NAF (Geocoded National Address File) database via addressr. Use it to autocomplete addresses, validate delivery locations, and ensure accurate shipping data before creating orders.

Overview

Search Addresses: Autocomplete and fuzzy-match Australian addresses
Validate Locations: Confirm addresses exist in the national database

Authentication

The address endpoint requires:

Scope: contacts:read
Auth Method: OAuth 2.0 M2M (Machine-to-Machine)
Format: Bearer token in Authorization header

Search Addresses

Search for Australian addresses by query string. Returns matching addresses ranked by relevance.

Request

GET /e9v3/addresses/search?q=<query>
Authorization: Bearer <jwt-token>

Query Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Address search query (street, suburb, postcode, or partial address)

Response (200 OK)

[
  {
    "sla": "123 COLLINS STREET, MELBOURNE VIC 3000",
    "score": 0.95
  },
  {
    "sla": "125 COLLINS STREET, MELBOURNE VIC 3000",
    "score": 0.87
  },
  {
    "sla": "123 COLLINS AVENUE, EDGE HILL QLD 4870",
    "score": 0.72
  }
]

Response Fields

Field	Type	Description
`sla`	string	Single Line Address in G-NAF format: `STREET, SUBURB STATE POSTCODE`
`score`	number	Relevance/confidence score (0–1, higher is better)

Parsing the SLA

The sla field follows a consistent format that can be parsed:

{street_address}, {suburb} {state} {postcode}

Component	Example	Pattern
Street	`123 COLLINS STREET`	Everything before the last comma
Suburb	`MELBOURNE`	After comma, before state code
State	`VIC`	Australian state: ACT, NSW, NT, QLD, SA, TAS, VIC, WA
Postcode	`3000`	4-digit code at end

Example: Parse SLA in JavaScript

function parseSLA(sla) {
  const commaIdx = sla.lastIndexOf(',');
  const street = sla.substring(0, commaIdx).trim();
  const rest = sla.substring(commaIdx + 1).trim();
  const match = rest.match(/^(.+?)\s+(ACT|NSW|NT|QLD|SA|TAS|VIC|WA)\s+(\d{4})$/);
  if (!match) return null;
  return {
    street,
    suburb: match[1],
    state: match[2],
    postcode: match[3]
  };
}

Common Use Cases

Address autocomplete for order forms

# User types "123 collins st melb"
curl -X GET 'https://api.equos.one/e9v3/addresses/search?q=123+collins+st+melb' \
  -H 'Authorization: Bearer <jwt-token>'

Validate a delivery address before creating an order

# 1. Search for the address
curl -X GET 'https://api.equos.one/e9v3/addresses/search?q=42+wallaby+way+sydney' \
  -H 'Authorization: Bearer <jwt-token>'

# 2. If results are returned with high score, address is valid
# 3. Use the validated address in the order

Suburb/postcode lookup

curl -X GET 'https://api.equos.one/e9v3/addresses/search?q=3000' \
  -H 'Authorization: Bearer <jwt-token>'

Error Handling

Status	Meaning
`200`	Success (may return empty array if no matches)
`400`	Missing `q` parameter
`401`	Invalid or missing Bearer token
`403`	Token lacks `contacts:read` scope
`429`	Rate limit exceeded
`502`	Addressr service unreachable

Coverage

The G-NAF database covers all Australian addresses including:

Residential and commercial properties
Rural and regional addresses
Unit/apartment numbers
All states and territories

Results are returned in uppercase as per the G-NAF standard format.

Next Steps

Working with Customers to create contacts with validated addresses
Create Orders with verified delivery locations
API Tester to try address search interactively

Developer Docs