API Reference

Authentication

All endpoints (except /v1/health) require a Bearer token in the Authorization header.

# Include on every request
Authorization: Bearer YOUR_API_KEY

API keys are prefixed with the first 8 characters for identification (e.g. ab12cd34...). Keep your key secret - it carries your usage quota.

Errors

All errors return JSON with an error field describing the problem.

{
  "error": "rate limit exceeded"
}

Rate limits

Paid plan limits are per API key, per calendar day (UTC). Exceeding the limit returns 429 until midnight UTC. Free trial limits are cumulative within the 30-day trial window.

GET /v1/autocomplete Free+

Returns up to limit address suggestions matching the query. Supports partial input, typos, and street-type abbreviations.

GET /v1/autocomplete?q=1+george+st+sydney&limit=3

{
  "suggestions": [
    {
      "gnaf_pid":     "GANSW705988020",
      "full_address": "1 GEORGE ST SYDNEY NSW 2000",
      "suburb":       "SYDNEY",
      "state":        "NSW",
      "postcode":     "2000",
      "latitude":     -33.865012,
      "longitude":    151.209400
    }
  ]
}

Growth+ tier responses additionally include: mesh_block, sa1_code, lga_name, federal_elec.

GET /v1/validate Free+

Validates a full address string against the GNAF dataset. Returns a confidence score and the canonical address if found. A score ≥ 0.80 is considered valid.

Validates against GNAF — Australia's official government address file covering 15.8 million street addresses across every state and territory. Ideal for checkout forms, CRM data cleansing, and any app collecting street addresses. Note: PO Boxes and Locked Bags are not part of GNAF and should be handled separately.

{
  "valid":        true,
  "confidence":   0.97,
  "gnaf_pid":     "GANSW705988020",
  "full_address": "1 MARTIN PL SYDNEY NSW 2000"
}

GET /v1/parse Growth+

Parses a free-text address string into structured components. Requires Growth tier or above.

{
  "gnaf_pid":      "GAVIC412702472",
  "unit_number":   "UNIT 4",
  "level_number":  "LEVEL 2",
  "street_number": "123",
  "street_name":   "COLLINS",
  "street_type":   "STREET",
  "suburb":        "MELBOURNE",
  "state":         "VIC",
  "postcode":      "3000"
}

GET /v1/reverse Growth+

Returns all addresses within radius metres of the given coordinates, sorted by distance.

{
  "lat":     -33.8688,
  "lon":     151.2093,
  "radius":  100.0,
  "count":   12,
  "results": [
    { "gnaf_pid": "GANSW706001234", "latitude": -33.8689, "longitude": 151.2092 }
  ]
}

POST /v1/batch Pro+

Validate up to 100 addresses in a single request. Returns results in the same order as the input array.

{
  "addresses": [
    "1 George St Sydney NSW 2000",
    "123 Collins St Melbourne VIC 3000"
  ]
}

{
  "results": [
    { "valid": true,  "confidence": 0.97, "gnaf_pid": "GANSW...", "full_address": "..." },
    { "valid": true,  "confidence": 0.99, "gnaf_pid": "GAVIC...", "full_address": "..." }
  ]
}

GET /v1/health No auth

Returns API status and address count. No authentication required. Use for uptime monitoring.

{
  "status":            "ok",
  "version":           "0.1.0",
  "address_count":     15860127,
  "last_pipeline_run": "2026-04-13 08:32:45"
}

Address object

All address objects returned by the API share this structure. Enrichment fields are only populated on Growth+ tier.

Tier comparison