Suburb Lookup - prontiq

GET

https://api.prontiq.dev

address

lookup

suburb

Look up postcodes by suburb

curl --request GET \
  --url https://api.prontiq.dev/v1/address/lookup/suburb \
  --header 'X-Api-Key: <api-key>'

const url = 'https://api.prontiq.dev/v1/address/lookup/suburb';
const options = {method: 'GET', headers: {'X-Api-Key': '<api-key>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://api.prontiq.dev/v1/address/lookup/suburb"

headers = {"X-Api-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

HttpResponse<String> response = Unirest.get("https://api.prontiq.dev/v1/address/lookup/suburb")
  .header("X-Api-Key", "<api-key>")
  .asString();

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prontiq.dev/v1/address/lookup/suburb"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Api-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.prontiq.dev/v1/address/lookup/suburb")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Api-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "suburb": "SYDNEY",
  "state": "NSW",
  "postcodes": [
    "2000"
  ],
  "bounds": {
    "top_left": {
      "lat": -33.8568,
      "lon": 151.2001
    },
    "bottom_right": {
      "lat": -33.8812,
      "lon": 151.2204
    }
  },
  "address_count": 12345
}

{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Invalid query parameters",
    "status": 400,
    "request_id": "req_01HZX7A8J5K9P4R2QW3E6T7Y8Z",
    "details": {
      "q": [
        "Required"
      ]
    }
  }
}

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Missing X-Api-Key header",
    "status": 401,
    "request_id": "req_01HZX7A8J5K9P4R2QW3E6T7Y8Z"
  }
}

{
  "error": {
    "code": "PRODUCT_NOT_ALLOWED",
    "message": "Product not included in your plan",
    "status": 403,
    "request_id": "req_01HZX7A8J5K9P4R2QW3E6T7Y8Z"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "status": 429,
    "request_id": "req_01HZX7A8J5K9P4R2QW3E6T7Y8Z"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error",
    "status": 500,
    "request_id": "req_01HZX7A8J5K9P4R2QW3E6T7Y8Z"
  }
}

Use Suburb Lookup when your input is a suburb or locality name and you need matching postcodes, aggregate address count, and optional bounds. For examples and no-state aggregation guidance, see the Suburb lookup guide.

Authorizations

X-Api-Key

string

header

required

Query Parameters

suburb

string

required

Suburb/locality name.

Required string length: 1 - 100

Example:

"sydney"

state

string

Australian state or territory filter. Allowed values are NSW, VIC, QLD, SA, WA, TAS, NT, and ACT. Input is case-insensitive and responses normalize state codes to uppercase.

Example:

"NSW"

limit

integer

default:10

Maximum number of postcodes to return.

Required range: 1 <= x <= 20

Example:

3

debug

enum<string>

Optional diagnostic flag. Send exactly true or false. Invalid values are rejected; debug diagnostics are for support only and must not be used for business decisions.

Available options:

true,

false

Example:

"false"

Response

Postcodes, optional bounds, and address count for the requested suburb or locality.

Postcodes, bounds, and address count for a suburb or locality.

suburb

string

required

Normalized suburb or locality name returned in uppercase.

Example:

"SYDNEY"

postcodes

string[]

required

Postcodes associated with this suburb or locality.

Four-digit Australian postcode. Store postcodes as strings; integer coercion can remove leading zeroes used by some Australian postcodes.

Pattern: ^\d{4}$

Example:

["2000"]

address_count

integer

required

Total address records in this suburb or locality. This is dataset cardinality, not credit usage.

Required range: x >= 0

Example:

12345

state

enum<string> | null

Australian state or territory used to disambiguate the locality when available. The value is uppercase in responses.

Available options:

NSW,

VIC,

QLD,

SA,

WA,

TAS,

NT,

ACT

Example:

"NSW"

bounds

object

Approximate bounding box for the suburb or locality when available.

Show child attributes

Example:

{
  "top_left": { "lat": -33.8568, "lon": 151.2001 },
  "bottom_right": { "lat": -33.8812, "lon": 151.2204 }
}

debug

object

Optional diagnostic metadata returned only when debug=true is supplied. Debug values are for support and troubleshooting, not production decision-making.

Show child attributes

Example:

{
  "scoringVersion": "address-match-v1",
  "queryMode": "autocomplete",
  "searchScore": 42.1
}

Postcode Lookup

Look up postcodes by suburb

curl --request GET \
  --url https://api.prontiq.dev/v1/address/lookup/suburb \
  --header 'X-Api-Key: <api-key>'

const url = 'https://api.prontiq.dev/v1/address/lookup/suburb';
const options = {method: 'GET', headers: {'X-Api-Key': '<api-key>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://api.prontiq.dev/v1/address/lookup/suburb"

headers = {"X-Api-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

HttpResponse<String> response = Unirest.get("https://api.prontiq.dev/v1/address/lookup/suburb")
  .header("X-Api-Key", "<api-key>")
  .asString();

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prontiq.dev/v1/address/lookup/suburb"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Api-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.prontiq.dev/v1/address/lookup/suburb")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Api-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "suburb": "SYDNEY",
  "state": "NSW",
  "postcodes": [
    "2000"
  ],
  "bounds": {
    "top_left": {
      "lat": -33.8568,
      "lon": 151.2001
    },
    "bottom_right": {
      "lat": -33.8812,
      "lon": 151.2204
    }
  },
  "address_count": 12345
}

{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Invalid query parameters",
    "status": 400,
    "request_id": "req_01HZX7A8J5K9P4R2QW3E6T7Y8Z",
    "details": {
      "q": [
        "Required"
      ]
    }
  }
}

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Missing X-Api-Key header",
    "status": 401,
    "request_id": "req_01HZX7A8J5K9P4R2QW3E6T7Y8Z"
  }
}

{
  "error": {
    "code": "PRODUCT_NOT_ALLOWED",
    "message": "Product not included in your plan",
    "status": 403,
    "request_id": "req_01HZX7A8J5K9P4R2QW3E6T7Y8Z"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "status": 429,
    "request_id": "req_01HZX7A8J5K9P4R2QW3E6T7Y8Z"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error",
    "status": 500,
    "request_id": "req_01HZX7A8J5K9P4R2QW3E6T7Y8Z"
  }
}