OzAddress API Documentation

Quick Start

No API key required. No signup. Just make requests.

JavaScript

const response = await fetch('https://ozaddress.cloudasn.com/api/v1/search?q=123+pitt+street');
const data = await response.json();
console.log(data.results[0].full_address);
// "123 PITT STREET, SYDNEY NSW 2000"

Python

import requests

response = requests.get('https://ozaddress.cloudasn.com/api/v1/search', params={'q': '123 pitt street'})
data = response.json()
print(data['results'][0]['full_address'])
# "123 PITT STREET, SYDNEY NSW 2000"

cURL

curl "https://ozaddress.cloudasn.com/api/v1/search?q=123+pitt+street"

Base URL

All API requests should be made to:

https://ozaddress.cloudasn.com/api/v1

Rate Limits

Rate limits are applied per IP address: 60 requests/minute and 5,000 requests/day. Completely free, no signup required. Rate limit information is included in response headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute (60)
`X-Daily-Limit`	Maximum requests per day (5,000)
`X-RateLimit-Remaining`	Requests remaining today
`X-RateLimit-Reset`	Seconds until limit resets

All responses include an X-API-Version header with the current API version.

API Status

GET /api/v1/status

Check the health and status of the API and its services. Use this endpoint to verify connectivity before making requests.

Example Request

curl "https://ozaddress.cloudasn.com/api/v1/status"

Example Response

{
  "status": "operational",
  "version": "1.0.0",
  "timestamp": "2025-02-01T12:00:00.000Z",
  "services": {
    "api": { "status": "operational" },
    "database": { "status": "operational", "latency_ms": 2 }
  },
  "status_url": "https://status.cloudasn.com"
}

Status Values

Status	HTTP Code	Description
`operational`	200	All systems functioning normally
`degraded`	503	One or more services are experiencing issues

Address Search

GET /api/v1/search

Search for addresses matching a query string. Returns up to 10 results by default, sorted by relevance.

Parameters

Name	Type	Description
`q` required	string	Search query (minimum 2 characters)
`limit` optional	integer	Maximum results to return (1-50, default: 10)
`state` optional	string	Filter by state (NSW, VIC, QLD, SA, WA, TAS, NT, ACT)
`postcode` optional	string	Filter by postcode

Example Request

curl "https://ozaddress.cloudasn.com/api/v1/search?q=123+pitt+street"

Example Response

{
  "results": [
    {
      "id": "GANSW713091175",
      "full_address": "123 PITT STREET, SYDNEY NSW 2000",
      "unit": null,
      "street_number": "123",
      "street_name": "PITT",
      "street_type": "STREET",
      "suburb": "SYDNEY",
      "state": "NSW",
      "postcode": "2000",
      "latitude": -33.86664673,
      "longitude": 151.20807784
    }
  ]
}

Get Address by ID

GET /api/v1/address/:id

Retrieve full details for a specific address by its unique ID.

Parameters

Name	Type	Description
`id` required	string	Address ID (path parameter)

Example Request

curl "https://ozaddress.cloudasn.com/api/v1/address/GANSW713091175"

Example Response

{
  "id": "GANSW713091175",
  "full_address": "123 PITT STREET, SYDNEY NSW 2000",
  "unit": null,
  "street_number": "123",
  "street_name": "PITT",
  "street_type": "STREET",
  "suburb": "SYDNEY",
  "state": "NSW",
  "postcode": "2000",
  "latitude": -33.86664673,
  "longitude": 151.20807784
}

Reverse Geocoding

GET /api/v1/geocode

Find the nearest addresses to a given latitude/longitude coordinate.

Parameters

Name	Type	Description
`lat` required	number	Latitude (-45 to -10 for Australia)
`lng` required	number	Longitude (110 to 155 for Australia)
`radius` optional	integer	Search radius in meters (max: 1000, default: 100)
`limit` optional	integer	Maximum results (1-10, default: 5)

Example Request

curl "https://ozaddress.cloudasn.com/api/v1/geocode?lat=-33.8666&lng=151.208"

Example Response

{
  "results": [
    {
      "id": "GANSW713091175",
      "full_address": "123 PITT STREET, SYDNEY NSW 2000",
      "unit": null,
      "street_number": "123",
      "street_name": "PITT",
      "street_type": "STREET",
      "suburb": "SYDNEY",
      "state": "NSW",
      "postcode": "2000",
      "latitude": -33.86664673,
      "longitude": 151.20807784,
      "distance_meters": 12.5
    }
  ]
}

Error Responses

All errors return a JSON object with error, message, and status_url fields:

{
  "error": "Query required",
  "message": "Please provide a search query via ?q= parameter"
}

Status Codes

Code	Description
`200`	Success
`400`	Bad request (invalid parameters)
`404`	Not found
`429`	Rate limit exceeded
`500`	Server error
`503`	Service unavailable (database or API temporarily down)

Data Source

OzAddress provides access to a comprehensive database of over 16 million verified Australian addresses with precise geocoordinates, covering every state and territory.