Reverse geocoding API for Australia

Send a latitude and longitude, and WattleAddr returns the nearest street address. The addresses are G-NAF, the national address file, and the API is hosted in Australia. This page is for someone who has never used an API.

What you need

• A WattleAddr account and a secret key. Sign up on the sign-up page (console.wattleaddr.com.au/signup). It is free and needs no card. In the console, open API Keys in the left menu and press Create my first key. Copy the key when it appears. The console shows it once. A test key starts waddr_sk_test_ while test mode lasts. It uses the real address data and is never charged. Test mode works for the first 15 days of your account.
• A server. This can be your own computer while you try it out.

Why the key stays on a server. Anyone who can open a web page or an app can read what is inside it. Anyone with your secret key can spend your lookups. Reverse geocoding only works with a secret key. A publishable key gets 403 forbidden_key_type. The step by step version of getting a key is in Step 1 of the quickstart.

Latitude and longitude in 30 seconds

Latitude and longitude are two numbers that name a spot on Earth. Latitude says how far north or south you are. Longitude says how far east or west. Australia is south of the equator, so Australian latitudes are negative. Australian longitudes are positive.

Example: -33.99168126, 150.80123469 is a point in Leppington, New South Wales. Latitude comes first.

Positions come from:

• a phone’s GPS;
• the browser, with navigator.geolocation.getCurrentPosition, after the person allows it;
• a click on a map;
• a vehicle tracker.

Your first call in 5 minutes

You need a terminal. These commands are for macOS, Linux, or Windows with WSL.

1. Save your key in an environment variable called WATTLEADDR_KEY. Replace the example with your own key.

   export WATTLEADDR_KEY=waddr_sk_test_your_key_here

2. Copy and paste this call.

   curl -s -H "Authorization: Bearer $WATTLEADDR_KEY" \
     "https://api.wattleaddr.com.au/v1/addresses/reverse?lat=-33.99168126&lng=150.80123469&radius=100&limit=3"

3. You get the nearest addresses back as JSON, nearest first.

   {
     "addresses": [
       {
         "id": "GANSW720007107",
         "formatted": "35 Bergin Cct, Leppington NSW 2179",
         "components": {
           "flat_number": null, "level_number": null,
           "street_number": "35", "street_name": "Bergin", "street_type": "Circuit", "street_suffix": null,
           "locality": "Leppington", "state": "NSW", "postcode": "2179"
         },
         "geo": { "lat": -33.99168126, "lng": 150.80123469 },
         "confidence": "high",
         "distance_m": 0
       },
       {
         "id": "GANSW720006300",
         "formatted": "37 Bergin Cct, Leppington NSW 2179",
         "components": { … },
         "geo": { "lat": -33.99155496, "lng": 150.80129962 },
         "confidence": "high",
         "distance_m": 15.3
       },
       {
         "id": "GANSW720684251",
         "formatted": "33a Bergin Cct, Leppington NSW 2179",
         "components": { … },
         "geo": { "lat": -33.99188327, "lng": 150.80122153 },
         "confidence": "high",
         "distance_m": 22.5
       }
     ],
     "source": "gnaf",
     "gnaf_release": "2026-08",
     "billed": false,
     "test": true
   }

What each field means:

The two shortened components objects have the same fields as the first.

From a phone or web page to an address

The phone or web page knows where the person is. Only your server may hold the secret key. So the page sends the position to your server, and your server calls WattleAddr.

1. The browser or phone sends its latitude and longitude to your server.
2. Your server asks WattleAddr for the nearest address, using the secret key.
3. WattleAddr sends the nearest addresses back to your server.
4. Your server returns the nearest address to the browser or phone.

A working example in Node.js (Express)

This is a web page with one button, and a server that answers it. It was run in Docker on Node.js 22 against a recorded response. It handles a person who blocks location, a position with no address nearby, and errors. You need Node.js 22 or newer.

This page collects a person’s location. Ask for it only when they press the button, as this example does. Tell them why you need it and what you keep. Under our Terms, your Privacy Act obligations to your own users stay with you.

1. Make a new folder called where-am-i and open a terminal in it. Run every command below in this folder. First run npm init -y and then npm install express@5.
2. Save this as index.html in the folder.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Where am I?</title>
</head>
<body>
  <button id="go">Show my address</button>
  <p id="result" role="status"></p>

  <script>
    const button = document.getElementById("go");
    const result = document.getElementById("result");

    button.addEventListener("click", () => {
      if (!navigator.geolocation) {
        result.textContent = "This browser cannot share your location.";
        return;
      }
      result.textContent = "Finding your position...";

      navigator.geolocation.getCurrentPosition(
        async (position) => {
          try {
            // Send the position to your own server. The secret key stays there.
            const res = await fetch("/where-am-i", {
              method: "POST",
              headers: { "Content-Type": "application/json" },
              body: JSON.stringify({ lat: position.coords.latitude, lng: position.coords.longitude }),
            });
            const data = await res.json();
            result.textContent = res.ok ? "You are near " + data.address : data.message;
          } catch (e) {
            result.textContent = "Could not reach the server. Try again.";
          }
        },
        (error) => {
          result.textContent = error.code === error.PERMISSION_DENIED
            ? "Location is blocked. Allow it for this site in your browser, then press the button again."
            : "Could not get your position. Try again.";
        },
        { enableHighAccuracy: true, timeout: 15000 }
      );
    });
  </script>
</body>
</html>

3. Save this as server.mjs in the same folder.

// server.mjs. Tested on Node.js 22 with Express 4 and 5 (npm install express@5).
// Run: WATTLEADDR_KEY=your_secret_key node server.mjs
import express from "express";

const API = "https://api.wattleaddr.com.au";
const app = express();
app.use(express.json());

// Show the page.
app.get("/", (req, res) => {
  res.sendFile("index.html", { root: import.meta.dirname });
});

// The page posts the browser's position here.
app.post("/where-am-i", async (req, res) => {
  const lat = Number(req.body?.lat);
  const lng = Number(req.body?.lng);
  if (!Number.isFinite(lat) || !Number.isFinite(lng) || Math.abs(lat) > 90 || Math.abs(lng) > 180) {
    return res.status(400).json({ message: "We did not get a usable position. Try again." });
  }

  const key = process.env.WATTLEADDR_KEY;
  if (!key) {
    console.error("Set WATTLEADDR_KEY to your secret key.");
    return res.status(500).json({ message: "This server is not set up yet." });
  }

  try {
    // 100 metres suits a phone's GPS. limit 1 asks for the single nearest address.
    const query = new URLSearchParams({ lat, lng, radius: 100, limit: 1 });
    const api = await fetch(API + "/v1/addresses/reverse?" + query, {
      headers: { Authorization: "Bearer " + key },
      signal: AbortSignal.timeout(10000),
    });
    const data = await api.json().catch(() => ({}));

    if (!api.ok) {
      // Log the status and code. Do not log the position, and do not send the API's message to the browser.
      console.error("WattleAddr:", api.status, data.error?.code);
      return res.status(502).json({ message: "We could not look up your address. Try again in a moment." });
    }
    if (data.addresses.length === 0) {
      // Nothing within 100 metres. This is not an error, and it is not charged.
      return res.status(404).json({ message: "No address found within 100 metres of you." });
    }
    res.json({ address: data.addresses[0].formatted, distance_m: data.addresses[0].distance_m });
  } catch (e) {
    console.error("WattleAddr:", e.name);
    res.status(502).json({ message: "We could not look up your address. Try again in a moment." });
  }
});

app.listen(3000, () => console.log("Open http://localhost:3000"));

4. Set your key as in the first call, then run node server.mjs. In Windows PowerShell, set the key with $env:WATTLEADDR_KEY="waddr_sk_test_your_key_here" and then run node server.mjs. If port 3000 is busy, change 3000 in server.mjs and in the address you open.
5. Open http://localhost:3000 and press the button. Your browser asks to share your location. The browser only offers this on https pages or on localhost, so plain http://localhost:3000 works for a first try.

A computer without GPS can be less exact than a phone, so the address may not be the one you expect. For the same call in Python or PHP, see the Python and PHP guides. The Node.js guide has the same call as a small module.

Choosing radius and limit

radius is how far to look, in metres, from 1 to 2000. limit is how many addresses to return, from 1 to 10.

A value outside its range returns 400 bad_request. We do not adjust it for you.

What it costs

Every call that returns at least one address is one lookup, from the same monthly allowance as the other endpoints. A call that returns no address is never billed. A session does not stop a repeat reverse call from being billed. A retrieve in the same session within an hour of a billed reverse call is normally not billed again. Test keys are never billed. If you retry after your own timeout, the retry can be billed as another lookup.

Reverse geocoding is on every plan, including Free. The prices and allowances are on the pricing page.

Good to know

• Nearest is the nearest address point. It means the nearest G-NAF address point. A neighbour’s point can be nearer than the property someone is standing on, so the result is not proof of where a person is. Addresses that G-NAF places only at the middle of their street or suburb are left out, because G-NAF has no point for the property itself.
• The data is a release. Results come from the G-NAF release we serve. An address that G-NAF has since retired can still appear.
• The coordinate is the G-NAF geocode. It is usually the property centroid. It is not a promise that mail can be delivered, or that it is the building’s door.

Privacy

We do not keep the coordinates, or the address we find, in usage records or search logs. The usage record keeps the type of call, the time, the key and session, how many addresses came back, how long it took, the status code, the G-NAF release and whether it was billed. If a request fails at our web server, the request line, including the coordinates, can appear in that server’s error log. We keep that log for no longer than 16 days. See the Privacy Policy.

Common problems

If the address data cannot be reached, you get 503 engine_unavailable and nothing is charged.

Next steps

• The reverse geocoding reference and the API reference.
• The full list of errors.
• The language guides: Node.js, Python and PHP.
• Does the person type the address? Use autocomplete instead.