Help centre

Help centre

Answers for developers and account owners. Prices, allowances and refunds are on the pricing page and in the Refund and Cancellation Policy. Can’t find it? Email support@wattleaddr.com.au.

Getting started

Sign-up, your first key, your first call, and test or live.

What is WattleAddr?

WattleAddr is an Australian address API. It suggests addresses as people type, checks a free-text address against G-NAF, and returns coordinates. G-NAF is the open Geocoded National Address File published by Geoscape Australia.

More: Why WattleAddr, Quickstart

How do I create an account?

Open the sign-up page of the console. Enter your name, work email and a password of at least 8 characters. The workspace name is optional. Tick the box to accept the Terms, then press Create account. You start on the Free plan with no card.

More: Quickstart, Pricing, Terms

How do I create my first API key?

Open API Keys in the left menu of the console and press Create my first key. You get a secret key in test mode while your test period lasts. The console shows the whole key once, under Copy your key now, with a ready-made command to try. Copy it somewhere safe, because it cannot be shown again.

More: Keys and authentication, Quickstart

How do I make my first call?

Call autocomplete with your key and a session value you choose, for example GET /v1/addresses/autocomplete with q and session in the query string. Send a secret key in an Authorization: Bearer header. Pick a suggestion, then call GET /v1/addresses/{id} with the same session to get the full record. The quickstart has the commands and the same two calls in several languages.

More: Your first request, Interactive API reference

Can I try the API without writing code or using a key?

Yes. The interactive API reference needs no key. Type an address and it shows the request and the JSON that comes back. You can also import the OpenAPI 3.1 spec or the Postman collection into your own tools.

More: Interactive API reference, Quickstart

What is the difference between a test key and a live key?

A test key uses the real address data and is never charged. A live key counts toward your plan and can be billed. Test keys work for a limited time from the day your account is created, and the API Keys page shows the end date. Live keys work on every plan, including Free. The one exception is the suburb and postcode API, which needs a paid plan on a live key.

More: Keys and authentication, Postcode API, Pricing

What do I need to do before I go live?

Create a live key and use it in place of the test key. Put a secret key only on your server. Put a publishable key in the browser and list your website domains under Allowed domains. Load and performance tests must use a live key, which is billed, and need our written agreement to the date and rate first.

More: Your first request, Keys and authentication, Test environments for Enterprise

Which endpoint should I use for a form, and which for data I already hold?

For a form, use autocomplete as the person types, then retrieve for the one they pick. For addresses you already hold, such as a customer list, use verify. Verify needs a secret key and returns a verdict you can act on. Reverse geocoding and bulk verification are separate endpoints for other jobs.

More: Verify an address, Address verification, Interactive API reference

Which addresses does WattleAddr cover?

It covers physical addresses in Australia that appear in G-NAF, in every state and territory. G-NAF is refreshed quarterly, and responses name the G-NAF release that answered. WattleAddr covers Australian addresses only.

More: Why WattleAddr, Status

Does WattleAddr support PO Boxes?

No. PO Boxes are unsupported because G-NAF holds physical addresses only. It has no PO Boxes, GPO Boxes, Locked Bags or Private Bags. A query for one returns a normal response with no suggestions and a postal_address_unsupported notice. That call is not billed. Your form can ask for a street address or take the PO Box in a separate field.

More: PO Boxes and postal addresses, AMAS and PAF compared with G-NAF

Does a verified address mean Australia Post will deliver to it?

No. A verified address exists in G-NAF and WattleAddr knows where it is. That is not a statement about mail delivery. WattleAddr does not provide Australia Post AMAS or PAF certification, DPIDs or barcodes.

More: AMAS and PAF compared with G-NAF, Address verification

Where do I get help if my question is not here?

Email support@wattleaddr.com.au. If something is broken right now, email rather than using Give feedback in the console. The contact page lists the other addresses for sales and billing.

More: Contact, Status

API keys

Secret and publishable keys, Allowed domains and IPs, rotating, revoking and test keys.

What is the difference between a secret key and a publishable key?

A secret key starts waddr_sk_ and is for code only you can read, such as your server. A publishable key starts waddr_pk_ and is for code anyone can read, such as a web page. Rule of thumb: if the key would show up in view source, it must be publishable.

More: Keys and authentication, Quickstart

Which endpoints can each key type call?

A publishable key can call address autocomplete and retrieve, and suburb and postcode autocomplete and retrieve. A secret key is needed for verify, suburb and postcode verify, usage, reverse geocoding and bulk verification. A publishable key used on one of those gets a forbidden_key_type error.

More: Keys and authentication, Error code forbidden_key_type

How do I send my key to the API?

Send a secret key in an Authorization: Bearer header. A publishable key in a browser can go in the key parameter of the URL, which avoids a preflight request on every keystroke. Keep a secret key out of URLs, because URLs end up in logs.

More: Your first request, Keys and authentication

What does Allowed domains do on a publishable key?

It lists the websites that may use the key. A call from any other site gets a forbidden_referrer error. Enter the host only, such as shop.com.au, or *.acme.com.au for a domain and its subdomains. Separate entries with commas. A live key with no domain works on any site, and the console marks it with a warning.

More: Keys and authentication, Error code forbidden_referrer

What should I type in Allowed domains, and what happens to a full address?

Type the site name only, for example shop.com.au. If you paste a full address such as https://shop.com.au/ the console reduces it to the host when you save. An entry that is not a website name is refused with a message. A port is kept only when you type one, for example localhost:8881. Type * for any site.

More: Keys and authentication

Why does a publishable key with Allowed domains fail when I call it from my server?

The API checks the Origin header, or the Referer if there is no Origin. A server call usually sends neither, so a key that lists domains is refused with forbidden_referrer. Use a secret key from your server, and keep the publishable key for browsers.

More: Keys and authentication, Error code forbidden_referrer

What does Allowed IPs / CIDRs do on a secret key?

It limits a secret key to your servers. Enter IPv4 addresses or IPv4 ranges such as 13.54.0.0/16, separated by commas. A call from any other address gets a forbidden_ip error. Leave it blank to allow any address. It applies to secret keys only. Publishable keys are limited by domain instead.

More: Keys and authentication, Error code forbidden_ip

How do I change a key’s name, domains, IPs or search-log privacy?

Open API Keys, then choose Edit on the key. You can change the name, the Allowed domains or Allowed IPs, and the search-log privacy mode. The key itself does not change and is not shown again. Only an owner or admin can edit keys.

More: Keys and authentication

How do I rotate a key?

Open API Keys and choose Rotate on the key, then confirm. The console issues a new secret for that key and the old one stops working. Anything still using the old key gets 401 errors until you deploy the new one. The new key is shown once.

More: Keys and authentication, Error code invalid_key

How do I revoke a key?

Open API Keys, choose Revoke on the key, type the key name to confirm, then press Revoke permanently. A revoked key cannot be undone and no replacement is issued. Every call that uses it starts failing. If you only want a fresh secret, use Rotate instead.

More: Keys and authentication, Error code invalid_key

I lost my key. Can I see it again?

No. The console shows a key in full once, when you create or rotate it. WattleAddr keeps only a prefix and a hash. If you have lost a key, create a new one, or use Rotate to replace it, then update your code.

More: Keys and authentication

What should I do if a secret key leaks?

Open API Keys and use Rotate or Revoke on that key straight away. Then put the new key in your server. Check Address Searches and the Usage & Quota page for calls you do not recognise. Where your servers have fixed addresses, add Allowed IPs to the replacement key. Email support@wattleaddr.com.au if you want help.

More: Keys and authentication, Security, Contact

Is it safe that anyone can read my publishable key in the page source?

Yes, if you lock it to your domains. A publishable key is meant to be seen, and it can call autocomplete and retrieve only. Allowed domains stops other websites using it. A live key with no domain works on any site, so anyone who copies it can use your lookups.

More: Keys and authentication, Words we use

What are the limits of test keys?

A test key uses the real data and is never billed. It stops working after the test period that starts when your account is created, and the API returns test_mode_expired. Test keys cannot be used for load or performance testing. On Enterprise, test keys can be switched on by written agreement and then do not expire, but they have their own cap and rate.

More: Test and UAT environments, Test environments for Enterprise, Error code test_mode_expired

How do I find out when my test keys stop working?

The API Keys page shows a line saying when test mode ends. It turns into a warning near the end and a banner after it has passed. Create a live key before then. Live keys work on every plan, including Free.

More: Keys and authentication, Error code test_mode_expired

How many API keys can I have?

Your plan decides. The New API key dialog says how many active keys your plan allows, and the API Keys page tells you when you are at the limit. Revoke a key you no longer use to make room, or upgrade under Billing.

More: Pricing, Rate limits and speed

Should I use one key for everything?

Use one key for each system. Each live key has its own requests-per-second limit, and a separate key makes it easy to rotate one without touching the rest. The monthly allowance is shared by every key in a workspace.

More: Rate limits and speed, Pricing

What does the dormant label on a key mean?

The key has not been used for a long time, or was created long ago and never used. It is a prompt to check the key. Nothing is revoked automatically. A forgotten publishable key stays readable by anyone who loaded the page, so revoke any key that nothing depends on.

More: Keys and authentication

Why does the API Keys page say view only?

Only an owner or an admin can create, edit, rotate or revoke keys. Developer, Billing and Viewer roles can see the list. Ask an owner or admin to make the change, or to change your role.

More: Keys and authentication

Can I choose what each key stores in the search log?

Yes. When you create or edit a key, Search-log privacy offers three choices: Store query text, Store a keyed hash of queries, or Don’t store query or matched-address text. The keyed hash is pseudonymisation, not anonymisation, because WattleAddr holds the key. Scrub this key’s existing logs applies the choice to what is already stored.

More: Data and privacy in the docs, Privacy Policy

Sessions and lookups

What counts as a lookup, and how sessions decide it.

What counts as a lookup?

A lookup is the unit your plan counts and bills. With default autocomplete, one lookup is one address a person actually picks, which is the retrieve call. One free-text address that verify matches is one lookup. Keystrokes are fair use and are not billed on their own. The pricing page shows what a plan includes.

More: Your first request, Pricing, Words we use

What is a session, and why do I send one?

A session is any string you choose that ties the keystrokes for one address to the final retrieve. Use the same value for every call about one address. The whole session then counts as one lookup. Make a new value for the next address. The widget and the React component do this for you.

More: Your first request, Words we use

What happens if I leave the session out?

Every retrieve is billed on its own, because the API cannot tell that two calls belong to one search. The same applies to a verify that matches. Always send a session with retrieve and verify.

More: Your first request, Words we use

What can I use as a session value?

Any string you choose, such as a random UUID. Suburb and postcode search, and autocomplete with detail=full, need the session in the URL query string and accept at most 200 characters. Pick a new value for each search box and keep it for the whole search.

More: Suburb, state and postcode, Full detail in one call

Can I keep using one session for a long time?

No. Treat a session as one search for one address. The API recognises a billed session for a limited time. After that, the same session value can bill again. Use a new session for each address.

More: Words we use, Autocomplete with full detail

Are autocomplete keystrokes billed?

Not with default autocomplete. Keystrokes are fair use, and an abandoned address search is not billed. With detail=full the billing is different, because a search is billed once it shows a suggestion. A suburb and postcode search is billed once per session, the first time it returns a suggestion.

More: Your first request, Autocomplete with full detail, Suburb, state and postcode

When is retrieve billed?

Retrieve is the billed call. It is billed the first time it is called in a session. Further retrieves in the same session are not billed again while the session is recognised. A retrieve on a test key is never billed, and the response shows billed: false.

More: Your first request, Words we use

When is verify billed?

Verify is billed when it returns a match. A verify that finds nothing is not billed. A PO Box query is not billed. When the best candidate scores too low and reaching it meant contradicting or discarding part of the input, no record comes back and the call is not billed. Any result that returns a record is billed, including ambiguous and unverified ones, so check the billed field.

More: Verify an address, Address verification

How is autocomplete with detail=full billed?

A full-detail search is billed once, the first time it returns at least one suggestion, whether or not anyone picks one. An abandoned search is billed in this mode. The price per lookup is the same, so the same traffic can cost more. Later calls in the session are usually not billed again, until the session window runs out. The detail page has a worked comparison.

More: Autocomplete with full detail, Full detail in one call, Pricing

How do I switch on autocomplete with detail=full?

An owner or admin opens Settings in the console and ticks Allow full-detail autocomplete in the Full-detail autocomplete box, then presses Save. It is off by default. While it is off, a call with detail=full returns full_detail_off and nothing is charged. Shopify plans cannot use it.

More: Full detail in one call, Error code full_detail_off

How are suburb and postcode lookups billed?

One search session is one lookup. It is billed the first time the session returns at least one suggestion, whether or not anything is selected. A search with no suggestions is not billed. Retrieve or verify in a session already billed is not billed again. Verify is billed only when it finds a match. A billed lookup counts the same as an address lookup.

More: Suburb, state and postcode, Postcode API

How is reverse geocoding billed?

Every reverse call that returns at least one address is one lookup. A call that returns no address is not billed. A retrieve in a session that already had a billed reverse call is normally not billed again. A test key is never billed.

More: Reverse geocoding guide, Your first request

How can I tell whether a call was billed?

Look at the billed field in the response. It is true when the call used one lookup, and false on a test key or when nothing was charged. On a plan with a quota, successful responses also carry X-WattleAddr-Quota-Limit and X-WattleAddr-Quota-Remaining headers.

More: All error codes, Your first request

Can I see usage for each of my own customers?

Yes. Send your own customer ID in the X-WattleAddr-Ref header, or the ref query parameter. It may use letters, digits and . _ : - only, and no personal information. The Usage & Quota page shows a By customer reference table, and the usage endpoint returns the same counts with group_by=ref.

More: Usage per customer, Interactive API reference

Billing

How and when you are billed, paying an invoice, plan changes and cancelling.

How does billing work?

Paid plans are billed in advance for the base plan, and any overage is billed in arrears for the period. WattleAddr issues a tax invoice and you pay it. There is no saved card and no automatic payment, so each invoice is paid only by an act of yours. The Billing page lists your invoices.

More: Terms, Pricing

When is overage billed?

Overage is billed in arrears. Lookups past your included allowance are added up for the period and invoiced at the end of it, not as they happen. The rate is on the pricing page. An owner or admin can instead choose Stop at my allowance in Settings, so that lookups past the allowance are refused and not billed. On an annual plan, overage is invoiced monthly in arrears.

More: Pricing, Terms

When does my billing period start and end?

The Overview page shows the date your period resets, and each invoice shows its period. The usage figures start again at the beginning of each period.

More: Terms, Pricing

Where do I find my invoices?

Open Billing in the console. The Billing & Invoices page has a table with each invoice, when it was issued, the amount, the method and the status. Choose View to open one. Invoices are also emailed to you. Each is a tax invoice with the GST itemised.

More: Terms, Pricing

How do I pay an invoice?

Open Billing and choose Make payment on the unpaid invoice. Pay by card, or by bank transfer or PayID using the invoice number as the reference. Card details are handled by the payment processor and are not saved. A bank transfer is marked as paid by hand once it arrives. Owners and admins can pay invoices.

More: Terms, Pricing

Will my card be charged automatically each month?

No. There is no saved card, no direct debit mandate and no automatic payment for renewals. WattleAddr issues an invoice for each period, and you pay it. Shopify plans are different, because Shopify charges and bills those.

More: Terms, WattleAddr for Shopify

What if a payment fails or an invoice goes unpaid?

Each invoice states its due date. WattleAddr emails a reminder before taking any action. If an invoice stays unpaid for long enough, the workspace may be moved to the Free plan. API keys are not revoked for non-payment, and the unpaid invoice stays payable. The Terms set out the detail. If a card payment fails, try again or pay by bank transfer or PayID. On an annual plan, an unpaid overage invoice does not move the workspace to Free. Lookups beyond the pool are refused until it is paid.

More: Terms, Contact

How do I change my plan, and when does the change take effect?

An owner or admin opens Billing and uses the Change plan section. Moving from Free to a paid plan takes effect straight away. A change between paid plans, in either direction, takes effect at the start of your next billing period, and nothing is charged mid-period. If you need more capacity before then, you keep going up to the overage ceiling, and the extra is billed as overage. If you chose Stop at my allowance, lookups past it are refused instead.

More: Terms, Pricing

How do I cancel a paid plan?

An owner or admin opens Billing and chooses Cancel plan. You keep your plan until the end of the current period. For the rest of that period, lookups past your allowance are refused instead of billed as overage. At the end of the period the workspace moves to Free. You are not invoiced again for a plan fee. Overage already invoiced remains payable. An annual plan runs to the end of the paid year.

More: Refund and Cancellation Policy, Terms

What is the difference between cancelling a plan and deleting a workspace?

Cancelling stops the billing and moves the workspace to Free. Your keys keep working on the Free allowance. Deleting a workspace removes it, revokes its API keys and deletes the text of its search logs. Invoices are kept, because they are tax records. If you only want to stop paying, cancel.

More: Refund and Cancellation Policy, Privacy Policy

How do I stop overage from being billed?

An owner or admin opens Settings and, under When you pass your allowance, chooses Stop at my allowance, then presses Save. Lookups that would be billed are then refused with a quota error until your next period, or until you choose Allow overage again. Overage already used in the period is still billed. The choice applies to new lookups shortly after you save.

More: Pricing, Error code quota_exceeded

What is the overage ceiling?

It is a safety limit on overage in each period for paid plans. When usage reaches it, overage pauses and the API returns quota_exceeded until the next period. It exists so a leaked key or a runaway integration cannot run up a bill nobody expected. Email support@wattleaddr.com.au to ask for it to be lifted. A plan change does not lift it.

More: Terms, Pricing, Error code quota_exceeded

Can I set a lower spending limit?

You can choose Stop at my allowance in Settings, which stops overage entirely. If you want a lower limit that still allows some overage, ask support. An operator can set a spending cap for a workspace on request.

More: Contact, Pricing

What happens when I use up my allowance?

It depends on the plan. On Free, billable lookups are refused until the next period or an upgrade. On paid plans, overage is billed unless you chose Stop at my allowance, up to the overage ceiling. Shopify plans stop at their allowance. In every case the refused call returns a 402 quota_exceeded error. The Overview page shows a banner as you get close. A cancelled plan also stops at its allowance for the rest of its period.

More: Error code quota_exceeded, Pricing

Do prices include GST?

Yes. Plan prices are in Australian dollars and include GST, and the GST is shown as a separate line on every tax invoice. The pricing page also shows each plan’s price before GST.

More: Pricing, Terms

Can I pay by purchase order?

Enterprise and Government accounts can pay against a purchase order where agreed. Email billing@wattleaddr.com.au to set that up. Other accounts pay each invoice by card, bank transfer or PayID.

More: Government and regulated industries, Terms, Contact

I use the Shopify app. Where is my invoice?

Shopify charges and bills Shopify app plans. WattleAddr does not invoice those workspaces. Choose or change the plan on Shopify’s own plan page for the app. The charge appears on your regular Shopify invoice.

More: WattleAddr for Shopify, Terms

How do I question a charge or ask about a refund?

Email billing@wattleaddr.com.au. The Refund and Cancellation Policy and the Terms set out how refunds and disputed charges are handled.

More: Refund and Cancellation Policy, Terms, Contact

API errors

Every error code the API returns, what it means and what to do.

What does an API error look like?

Errors from the API's endpoints are JSON in the form { "error": { "code", "message", "docs" } }. Switch on the code, because the message can change. The docs field links to the matching row of the error reference. A body that is not valid JSON, a path that does not exist, and an unexpected server error use a different shape. Some errors say Nothing was charged at the start of the message.

More: All error codes, Common errors

What does bad_request (400) mean?

The input was missing, too short, too long or out of range. Autocomplete needs at least 3 characters in q, suburb and postcode search needs at least 2, and verify needs an address of at least 3 characters. Over-length input is refused too. Suburb and postcode search and detail=full also need a session in the URL query string. Fix the input and send it again. The response is JSON with error.code, error.message and error.docs. Switch on the code, because the message can change.

More: Error code bad_request, All error codes

What does invalid_ref (400) mean?

The customer reference is longer than 64 characters or has a character other than letters, digits and . _ : -. Spaces and @ are not allowed. Nothing was charged. Send your own customer ID, not a name or an email address, or leave the reference out. It is optional.

More: Error code invalid_ref, Usage per customer

What does unauthorized (401) mean?

No API key was sent. Add an Authorization: Bearer YOUR_KEY header, or the key parameter for a publishable key in the browser. The response is JSON with error.code, error.message and error.docs. Switch on the code, because the message can change.

More: Error code unauthorized, Your first request

What does invalid_key (401) mean?

The key is wrong, has been revoked, or has a typo. Copy it again from the console, or create a new key. A revoked key never comes back. A key that was rotated stops working too, so use the new one. A key that cannot be checked because our database is unavailable returns service_unavailable instead, never this error.

More: Error code invalid_key, Error code service_unavailable

What does forbidden_referrer (403) mean?

A publishable key was used from a website that is not on its Allowed domains list, or from a call that sent no Origin or Referer header while the key lists domains. Edit the key under API Keys and add the host the page is served from, such as shop.com.au. From a server, use a secret key.

More: Error code forbidden_referrer, Keys and authentication

What does forbidden_ip (403) mean?

A secret key was used from an IP address that is not on its Allowed IPs / CIDRs list. Edit the key under API Keys and add the address, or clear the list to allow any address. Only IPv4 addresses and ranges can be listed.

More: Error code forbidden_ip, Keys and authentication

What does forbidden_key_type (403) mean?

A publishable key called an endpoint that needs a secret key. Those are verify, suburb and postcode verify, the usage endpoint, reverse geocoding and bulk verification. Call them from your server with a secret key. If a person is typing the address, use autocomplete and retrieve with the publishable key.

More: Error code forbidden_key_type, Keys and authentication

What does full_detail_off (403) mean?

A call with detail=full was sent while full-detail autocomplete is switched off for the workspace. Nothing was charged. An owner or admin opens Settings and ticks Allow full-detail autocomplete. Or leave detail=full out. Autocomplete without it still works.

More: Error code full_detail_off, Full detail in one call

What does full_detail_unavailable (403) mean?

A call with detail=full was sent from a Shopify plan, and those plans cannot use it. Nothing was charged. Leave detail=full out and use autocomplete and retrieve.

More: Error code full_detail_unavailable, WattleAddr for Shopify

What does quota_exceeded (402) mean?

The workspace’s allowance is used up and the plan does not run over, or a paid plan has reached the overage ceiling, or the owner chose Stop at my allowance in Settings. The message says which. Wait for the period to roll over, upgrade under Billing, allow overage in Settings, or email support to lift the ceiling.

More: Error code quota_exceeded, Pricing, Terms

What does test_mode_expired (402) mean?

A test key was used after the test period that starts when the account is created. Create a live key in the console and use it instead. Live keys work on every plan, including Free. On Enterprise, test keys covered by your agreement do not expire.

More: Error code test_mode_expired, Test and UAT environments

What does test_cap_reached (402) mean?

Nothing was charged. An Enterprise workspace with test keys has used all its test lookups for this billing period, so a test key is refused until the next period starts. Lookups on a live key are billed. Ask us if you need a different cap.

More: Error code test_cap_reached, Test and UAT environments

What does feature_unavailable (402) mean?

The endpoint is not included in the workspace’s plan. The usual case is a live key on the Free plan calling suburb and postcode search. Nothing was charged. Upgrade under Billing, fall back to a free-text suburb field, or use a test key while your account’s test period lasts.

More: Error code feature_unavailable, Postcode API

What does not_found (404) mean?

No address or suburb and postcode pair has that id, and no bulk job does. Use an id exactly as it came back from a suggestion. Ids can change between G-NAF releases, so search again instead of replaying an old one. A request to a path that does not exist gets a plain 404 in a different shape.

More: Error code not_found, Your first request

What does rate_limited (429) mean?

One key sent too many requests in a short time. The response has a Retry-After header saying how many seconds to wait. Nothing is queued, and a refused call does not use your allowance and is not charged. Wait that long and retry, and debounce keystrokes in the browser. The limit depends on the plan.

More: Error code rate_limited, Rate limits and speed

What does service_unavailable (503) mean?

WattleAddr cannot reach its own database, so it cannot check your key or usage right now. Nothing was charged for a call that stops here. It is never a 401, so the key may be fine. The Retry-After header says how long to wait. Do not create a new key.

More: Error code service_unavailable, Status

What does engine_unavailable (503) mean?

The address data could not be read for this call, or the suburb and postcode data is not loaded on the server. Nothing was charged. Wait a few seconds and try again, using Retry-After if it is sent. If it keeps happening, check the status page.

More: Error code engine_unavailable, Status

Why does a bad JSON body or a wrong URL return a different error shape?

A body that is not valid JSON, and a path that does not exist, are answered before the API reads your key. Those two responses use a plain shape with statusCode, error and message instead of error.code. Check the URL and the Content-Type header, and send valid JSON. An unexpected server error (500) uses the same plain shape.

More: All error codes, Interactive API reference

What is a notice, and is it an error?

A notice is a note on a successful 200 response that explains an empty or changed result. It is not an error. The codes are postal_address_unsupported for a PO Box query, street_number_not_found, unit_not_found and locality_nearby. Show the message and the list instead of taking the first suggestion.

More: All error codes, PO Boxes and postal addresses

What does batch_too_large (400) mean?

Nothing was charged. A batch sent with a test key had more addresses than the workspace’s test batch size. Send smaller batches, use a bulk job, or use a live key. Lookups on a live key are billed.

More: Error code batch_too_large, Bulk verification guide

What do columns_required and too_many_rows (400) mean?

columns_required means the file has no clear address column. Say which column holds the address with address_column, or use columns for an address split across columns. too_many_rows means the job has more rows than one job can hold. Split the file.

More: Bulk verification guide, All error codes

What does file_too_large (413) mean?

The file is bigger than one bulk job accepts. Split it into smaller files and create a job for each.

More: Bulk verification guide, All error codes

What does too_many_jobs (429) mean?

The workspace already has the most unfinished bulk jobs it can have at one time. Wait for one to finish, or delete one, then create the new job.

More: Bulk verification guide, All error codes

What does busy (429) mean on a bulk call?

Other files are being uploaded, or a batch is already running for the workspace. The response carries Retry-After. Wait that long and try again.

More: Bulk verification guide, All error codes

What does test_limit (429) mean?

Test mode bulk jobs are limited in rows each day for each workspace. They are not billed, but they use the same address engine. Wait until the limit resets, or use a live key. Lookups on a live key are billed.

More: Bulk verification guide, Test and UAT environments

What does not_available_on_shopify (403) mean?

Bulk verification is not available to workspaces billed through Shopify. Use a workspace on a directly billed plan.

More: Bulk verification guide, WattleAddr for Shopify

What does bulk_unavailable (503) mean?

Bulk verification cannot take new files right now. Try again later.

More: Bulk verification guide, Status

What does results_not_available (409) mean?

There are no results to download. Either the job has none yet, the files were deleted after the job finished, or the results are stored on our other server and this one cannot reach it. The message says which. Try again later if the server was unreachable.

More: Bulk verification guide, All error codes

What does engine_error mean on a row of a batch result?

That address could not be checked, and it was not billed. It comes back inside results with an error object. Retry only the rows that were not returned and the rows that came back with engine_error.

More: Bulk verification guide, Error code service_unavailable

Endpoints

What each endpoint takes and returns.

What is the base URL, and what format does the API use?

The base URL is https://api.wattleaddr.com.au/v1. The API speaks JSON only and covers Australian addresses only. An OpenAPI 3.1 description is at /v1/openapi.json and a Postman collection is at /v1/postman.json.

More: Interactive API reference, Quickstart

What does the autocomplete endpoint take?

GET /v1/addresses/autocomplete takes q, the text typed so far, with at least 3 characters. It also takes session, an optional limit, an optional state to limit suggestions to one state or territory, and detail=full for the whole record. It returns suggestions as the person types.

More: Interactive API reference, Your first request

What does autocomplete return?

It returns session, query and a suggestions list. Each suggestion has an id, a formatted address and a score. The score only ranks suggestions within that one response, so you can ignore it. A response may also carry a notice. By default it does not return the full record. Call retrieve for that.

More: Your first request, Interactive API reference

How many suggestions can autocomplete return?

Use the limit parameter. The default is 8 and the most is 20. With detail=full the most is 5, and a larger value is treated as 5.

More: Interactive API reference, Full detail in one call

What does retrieve return?

GET /v1/addresses/{id} returns the full record for the suggestion a person picked. It has the id, the formatted address, the components, the coordinates in geo, confidence, source, the gnaf_release that answered and billed. Store the formatted address and the components, not just the id, because ids can change between G-NAF releases.

More: Your first request, Interactive API reference

What are the address components?

components splits the address into flat_number, flat_type, level_number, level_type, street_number, street_name, street_type, street_suffix, locality, state, postcode, lot_number and building_name. All are strings and any can be null. locality is the suburb or town. Keep postcode as a string, because Darwin is 0800.

More: Your first request, Interactive API reference

What are geo and confidence in a response?

geo holds the latitude and longitude, or null if the record has no coordinates. confidence is G-NAF’s own confidence in the record. It is not a match score. On a verify response the top-level confidence field is deprecated, so branch on verdict instead.

More: Your first request, Verify an address

What does the verify endpoint take?

POST /v1/addresses/verify takes a JSON body with address, at least 3 characters, an optional session and an optional extended_corrections true or false. It needs a secret key. Send a session so the call is not billed twice for the same address.

More: Verify an address, Address verification

What does verify return?

It returns matched, match, verdict, match_score, match_level, elements, changed_elements, alternatives, source, gnaf_release and billed. match has the same shape as a retrieve record. dropped_tokens and unmatched_tokens say what was left out. A notice appears for a PO Box query, and test appears on a test key.

More: Verify an address, Address verification, Interactive API reference

What do the verify verdicts mean?

verified means every element you gave agrees and no other candidate fits, so accept it. corrected means it agrees as far as it goes and you abbreviated or left something out. ambiguous means an element was contradicted, input was discarded, or another candidate fits equally well, so review it. unverified means nothing matched, or the match scored too low to rely on.

More: Verify an address, Address verification

How do I tell which part of an address was wrong?

Read elements. Each part of the address has its own status of verified, changed or missing. A checkout can then ask again for the one part that disagrees instead of the whole address. changed_elements lists the parts that were corrected, and the corrected values are in match.components. missing means not supplied, not required.

More: Verify an address, Typos, misspellings and units

Is there a match score I should accept or reject on?

match_score and match_level describe how precisely the match was made, and they suit logging and review queues. WattleAddr publishes no accept or reject threshold, because the right line depends on what a wrong address costs you. Branch on verdict.

More: Verify an address, Address verification

What does extended_corrections do on verify?

With extended_corrections true, verify can also fix one wrong part when every other part points to a single record, such as a neighbouring suburb with the same postcode. The fixed part is named in changed_elements and the verdict is corrected. From 1 February 2027 a request that does not say gets true, and false is always honoured.

More: Verify an address, Typos, misspellings and units

Does the API cope with typos and misspelt suburbs?

Matching tolerates a wrong, missing or extra character in the street name and the suburb. It is not phonetic, and the last word typed gets no tolerance. Verify tells you what it corrected and a corrected street name is never verified, so review it. The docs set out the exact rules, including units and dropped words.

More: Typos, misspellings and units, Address verification

What do the suburb and postcode endpoints do?

GET /v1/localities/autocomplete suggests suburbs and postcodes as someone types, with q of at least 2 characters and a required session. A query of digits only searches postcodes. GET /v1/localities/{id} returns one suburb, state and postcode pair. POST /v1/localities/verify checks that a suburb, state and postcode belong together.

More: Suburb, state and postcode, Postcode API

What does suburb and postcode verify return?

It takes at least two of suburb, state and postcode. It returns matched, billed, verdict, match, elements and alternatives. A suburb on its own that fits several places is ambiguous with match null, and alternatives lists them. It needs a secret key and a paid plan on a live key.

More: Suburb, state and postcode, Postcode API

Where does the suburb and postcode data come from?

G-NAF has no postcode list, so WattleAddr builds each suburb, state and postcode pair from current G-NAF addresses. It is not Australia Post’s postcode list. A postcode used only for PO Boxes, Locked Bags or large mail receivers is not included, because G-NAF holds physical addresses only. A verified pair does not show that mail can be delivered.

More: Suburb, state and postcode, Postcode API, G-NAF attribution

What does the usage endpoint return?

GET /v1/usage returns your usage by day, or by customer reference with group_by=ref. It takes from and to as YYYY-MM-DD dates and needs a secret key. The range can be up to 92 days. Calls to it are not charged. Dates are UTC days. The Usage & Quota page in the console shows the same kind of figures.

More: Usage per customer, Interactive API reference

Is there an endpoint to check the service is up?

Yes. GET /v1/status needs no key. It returns the service status, the address engine and database checks, the G-NAF release being served and the number of address records. The status page shows the same, with a daily history.

More: Status, Interactive API reference

How current is the data?

The data is G-NAF from Geoscape Australia, refreshed quarterly. Responses carry gnaf_release, which names the release that answered. The status page shows the release being served. A verified address exists in G-NAF, and that is not proof that it is current.

More: Status, Why WattleAddr

What does reverse geocoding take and return?

GET /v1/addresses/reverse takes lat and lng, an optional radius in metres and an optional limit. It returns the nearest addresses, nearest first, each with distance_m. It needs a secret key, so call it from your server. A value outside its range returns bad_request and is not adjusted.

More: Reverse geocoding guide, Interactive API reference

What does a reverse geocoding result tell me?

It returns the nearest G-NAF address point, 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. Coordinates and the address found are not kept in usage records or search logs.

More: Reverse geocoding guide, Privacy Policy

How do I verify a short list of addresses in one call?

POST /v1/addresses/verify/batch takes up to 100 addresses and answers in the same call. Each address is a string, or an object with your own id and an address. It needs a secret key. The response has a result for each address and a summary of how many were sent, matched, billed and not processed.

More: Bulk verification guide, Bulk address verification

How do I verify a whole file of addresses?

In the console, choose Bulk verify, then choose your CSV file under New job. Check the columns, press Start verifying, and download the results when the job is complete. Through the API, POST /v1/batch-jobs creates a job, GET /v1/batch-jobs/{id} shows its status and GET /v1/batch-jobs/{id}/results downloads the results as CSV or JSON.

More: Bulk verification guide, Bulk address verification

How is bulk verification billed?

Each address that matches is one lookup, the same as a single verify call. Rows that do not match are not billed, and a PO Box row is not billed. A job pauses when your workspace reaches its limit instead of running up a bill, and carries on by itself when lookups are available again. Test keys run jobs that bill nothing.

More: Bulk verification guide, Pricing

What happens to a file I verify in bulk?

The file you upload and the results file are deleted some days after the job finishes, or at once when you choose Delete now in the console or call DELETE on the job. The rows are not written to your search log. The files are stored in Australia, on the server that runs the job, and are used for nothing else. The Privacy Policy covers the detail.

More: Bulk verification guide, Privacy Policy

SDKs, widget and plugins

The npm packages, the browser widget and the Shopify app.

How do I add the browser widget?

Add an input and the widget script from https://api.wattleaddr.com.au/v1/widget.js. Then create it with your publishable key and attach it to the input, with an onSelect function that receives the chosen address. The widget handles the session for you. The quickstart has the full snippet.

More: Browser widget, Keys and authentication

How do I make the widget fill my own form fields?

Pass fill when you attach the widget. It maps address parts such as address_line1, suburb, state and postcode to the ids, names or CSS selectors of your fields. A part name it does not know throws an error when you call attach. A field it cannot find is skipped, with one console warning. The Add to your form page in the console writes the snippet for you.

More: Browser widget, Your own field names, Keep your field names

What options does the widget have?

fill, onSelect, onError, theme, limit and state. theme is light, dark, or auto to follow the visitor’s system setting. state restricts suggestions to one state or territory. onError lets you handle failures yourself instead of a console warning.

More: Browser widget

Which npm packages are there?

@wattleaddr/js is a typed client with no dependencies, plus the drop-in widget. It runs in the browser and in Node 18 or later. @wattleaddr/react adds a useAddressAutocomplete hook and an AddressAutocomplete component. Both are MIT licensed. The client has autocomplete, retrieve and verify, and there is no helper for suburbs and postcodes.

More: npm packages, Suburb, state and postcode

How do I use @wattleaddr/js on my server with a secret key?

Create the client with your secret key and set keyTransport to 'header'. The key is then sent as an Authorization: Bearer header and not in the URL. The default sends the key in the URL, which suits a publishable key in the browser. Create a session with createSession() and pass it to each call.

More: npm packages, Your first request

How do I use the React component?

Install @wattleaddr/react and render AddressAutocomplete with your publishable key as apiKey and an onSelect function. It follows the ARIA combobox pattern and works from the keyboard. The useAddressAutocomplete hook gives you the logic if you want your own markup. Both manage the session for you.

More: npm packages, Keys and authentication

How do errors appear in the JavaScript client?

The client throws WattleAddrError for any response that is not successful. It has code, status, an optional docs link and retryAfter on a 429. Switch on code, for example quota_exceeded or rate_limited.

More: npm packages, All error codes

Can I use WattleAddr from Python, PHP or another language?

Yes. The REST API works from any language that can make an HTTPS request. The docs have tested guides for Python, Node.js and PHP, and examples in other languages. You can also generate a client from the OpenAPI 3.1 spec.

More: Python guide, Node.js guide, PHP guide, Interactive API reference

How do I set up the Shopify app?

Install the app from the Shopify App Store. On first open it creates your WattleAddr workspace and a publishable key locked to your store. Then, in your Shopify admin, open Online Store, then Themes, then Customize, then App embeds. Turn on WattleAddr address autocomplete, paste the key, and save.

More: WattleAddr for Shopify

Does the Shopify app work at checkout?

The app enhances address fields that your theme renders. Shopify’s checkout and its newer hosted customer account pages are rendered outside the theme, so they keep Shopify’s own autocomplete and the app does not affect them. Checkout address autocomplete needs a Shopify Plus checkout extension and is not part of this app today.

More: WattleAddr for Shopify

How does billing work for the Shopify app?

Through Shopify. The app is free to install, and larger plans are chosen on Shopify’s own plan page for the app and charged on your regular Shopify invoice. WattleAddr does not bill Shopify merchants directly. Shopify plans are a fixed price with a fixed allowance, and lookups pause when the allowance is used up.

More: WattleAddr for Shopify, Pricing

Does the Shopify app store what my shoppers type?

Keys issued to Shopify stores are set up so that the text a shopper types and the address they pick are not written to the search log. Lookups are counted for your plan allowance. The Privacy Policy has the detail.

More: WattleAddr for Shopify, Privacy Policy

The console

Workspaces, team, Settings, usage, address searches and feedback.

What is a workspace?

A workspace has its own API keys, usage and billing. Most people want one per product or per client, not one per environment, because keys already carry a live or test mode. Create one from the workspace menu at the top left with + New workspace. A new workspace starts on Free, and your plan limits how many you can have.

More: Pricing, Quickstart

What is on each page of the console?

Overview shows your lookups and plan. API Keys manages keys. Add to your form maps your field names. Address Searches is the search log. Usage & Quota shows lookups by day. Billing has invoices and plan changes. Team, History and Settings are under Workspace. Account is for your own sign-in and settings.

More: Quickstart

What does the Overview page show?

It shows billable lookups this period, autocomplete requests that are fair use and not billed, active keys, and a match rate for recent sessions with a pick. It also shows your plan and quota, the G-NAF release being served, and where the service is hosted. A banner appears as you near your allowance.

More: Pricing, Status

What does the Usage & Quota page show?

It shows billable lookups by day for the last 30 days, with tiles for Used, Remaining, Projected and Est. overage. Autocomplete keystrokes are fair use and do not count toward your quota. A By customer reference table lists your busiest references for the period, and plans with CSV export can download a month.

More: Usage per customer, Pricing

What is the Address Searches page?

It is the log of the searches the workspace made. The table shows the time in AEST, type, query, matched address, results, key and whether the call was billed. You can filter by query, matched address, key, dates and billing. Change how long searches are kept in Settings. What is stored is set per key, under API Keys.

More: Data and privacy in the docs, Privacy Policy

Can I export my address searches?

Yes, on plans that include CSV export. Choose Export CSV on the Address Searches page. When filters are applied it says Export filtered CSV. On a plan without CSV export the button is disabled.

More: Pricing

Why can I not search hashed queries by text?

In the keyed-hash mode each query is stored as a salted hash and the matched address text is not kept, so there is no text to search. That is pseudonymisation, not anonymisation, because WattleAddr holds the key. Use the key, date and billing filters, or set the key to store query text if you need to read queries.

More: Data and privacy in the docs, Privacy Policy

What are the search-log privacy modes?

Each key has one of three modes. Full stores the query and matched-address text until the retention period ends. Hashed stores each query as a salted keyed hash and drops the matched-address text. None stores no query or matched-address text, only counts, timing and billing. Hashed is pseudonymisation, not anonymisation.

More: Data and privacy in the docs, Privacy Policy, Data Processing Agreement

How do I change how long search logs are kept?

An owner or admin opens Settings, chooses a value under Search-log retention, and presses Save changes. Older search logs are then deleted automatically. Your plan decides the longest retention you can pick, and options above it are marked as needing a higher plan.

More: Pricing, Privacy Policy

How do I invite a teammate?

An owner or admin opens Team, enters the email, chooses a role and presses Send invite. A person who already has a WattleAddr account is added straight away and shows as Active. A person without an account shows as Invited. Creating an account with a password does not add them, so ask them to sign up first and then invite them. While single sign-on is allowed, people cannot sign up with a password at a domain it has verified, so they join by signing in through your provider. On Enterprise, an invited person joins when they first sign in through your single sign-on. WattleAddr does not send them an email, so tell them yourself. Your plan decides how many members a workspace can have.

More: Pricing, Single sign-on setup

What can each team role do?

The roles are Owner, Admin, Developer, Billing and Viewer. Owners and admins can manage keys, billing, the team and settings. Developer, Billing and Viewer members can sign in and see the workspace, and the console shows view only where they cannot change something. A Viewer cannot see Property reports. Only owners and admins can pay plan and overage invoices.

More: Single sign-on setup

What is on the Settings page?

Workspace name, Search-log retention, Data residency, When you pass your allowance, Full-detail autocomplete, Single sign-on, Change password and, for the owner, a Danger zone to delete the workspace. Some of these show only on plans or roles where they apply.

More: Single sign-on setup, Data Residency Attestation

What is the Add to your form page?

You type your form’s field names, and after you save, the calls you tick return each address under those names. The page also writes a snippet that fills them when someone picks an address. Only an owner or admin can change the names. A Shopify-billed workspace is told the page is for other sites.

More: Keep your field names, Your own field names

What is the History page?

Account activity lists plan changes, payment methods, invoices, refunds and key actions across every workspace you own or administer, not just the one that is open. Only owners and admins can read it.

More: Privacy Policy

How do I send feedback from the console?

Choose Give feedback in the left menu, pick Something is wrong, Something is missing or This worked well, describe it and press Send. It goes to the people who build WattleAddr and is not published. It carries your email, the screen you were on, your workspace and your plan, and nothing from your address searches. If something is broken right now, email support@wattleaddr.com.au instead.

More: Contact, Privacy Policy

Can my team sign in with single sign-on?

Yes, on Enterprise plans. The workspace owner connects an identity provider over OpenID Connect in Settings under Single sign-on, verifies each email domain by DNS, and can require SSO. This covers console sign-in. Your application still uses API keys.

More: Single sign-on setup, Government and regulated industries

What role do people get when they sign in through SSO?

The owner picks Role for new members when saving the connection. The identity provider cannot change an existing member’s role and cannot create owners. SSO is checked against the plan at every sign-in, so a workspace that leaves Enterprise stops signing people in through it.

More: Single sign-on setup

Account and security

Sign-in, password reset, two-step verification and deleting things.

How do I sign in to the console?

Open the console sign-in page, enter your email and password, and press Sign in. If your organisation uses single sign-on, the page offers Continue with single sign-on once your email domain is recognised. If you turned on two-step verification, you will also be asked for a code.

More: Single sign-on setup, Quickstart

I forgot my password. How do I get back in?

Choose Forgot your password? on the sign-in page and an email with a link goes to the address on your account. The link works once and expires. Asking for a new one cancels the last, so use the newest email. Setting a new password signs out every device and does not change your API keys. If you cannot receive email at that address, contact support.

More: Contact, Keys and authentication

How do I change my password while signed in?

Open Settings, go to Change password, enter your current password and a new one of at least 8 characters, confirm it and press Update password. If you signed in through your organisation’s identity provider, your password is managed there and the console does not show this form.

More: Single sign-on setup

Does the console support two-step verification?

Yes, on every plan. Open Account and find Two-step verification. It asks for a 6-digit code from an authenticator app as well as your password, so a stolen password is not enough to reach your API keys. When you turn it on, the console shows recovery codes once. Save them somewhere other than the phone that holds the app.

More: Security, Keys and authentication

I lost my authenticator app. What do I do?

Sign in with one of your recovery codes instead of the 6-digit code. Each recovery code works once. They are stored hashed, so they cannot be shown again or re-issued. If you have none left, email support@wattleaddr.com.au.

More: Contact, Security

How do I stop marketing email?

Open Account and use the News and offers box to opt out. Service notices and invoices are separate and still arrive.

More: Privacy Policy

How do I delete a workspace?

The owner opens Settings and uses the Danger zone, then Delete this workspace. Deleting revokes the workspace’s API keys and deletes the text of its search logs, so anything still calling with those keys stops working. Invoices are kept. It cannot be undone. To stop being billed without breaking anything, cancel the plan under Billing instead.

More: Privacy Policy, Refund and Cancellation Policy

How do I delete my account or ask for my data to be erased?

You can delete every workspace you own from Account, using Delete all workspaces. To delete your account or ask for erasure, contact us. Requests are handled under the Privacy Policy, subject to any legal retention requirements.

More: Privacy Policy, Contact

How are API keys protected?

A key is shown in full once, and only a prefix and a hash are kept. Data is encrypted in transit. The Security page and the Data Processing Agreement describe the controls.

More: Security, Data Processing Agreement

Data and privacy

Short pointers to the page that governs each point.

Where is my data hosted?

In Australia. The Data Residency Attestation states what runs where and what the exceptions are. Read it if you are relying on it for procurement.

More: Data Residency Attestation, Security

Does WattleAddr send my users’ typing to a third party?

The Privacy Policy and the Data Residency Attestation answer this exactly, including the exceptions. Do not rely on a summary. Read those two pages.

More: Privacy Policy, Data Residency Attestation

What does WattleAddr store about the addresses my users type?

You choose, per key. The three search-log modes are full, hashed and none. Hashed is pseudonymisation, not anonymisation. The Privacy Policy and the Data Processing Agreement govern what is stored and for how long.

More: Privacy Policy, Data Processing Agreement, Data and privacy in the docs

Is there a Data Processing Agreement?

Yes. It is published on the website. The Terms say it applies to your workspace from the moment it is created. Enterprise and Government customers may sign a negotiated version instead.

More: Data Processing Agreement, Terms

Is WattleAddr IRAP assessed or ISO 27001 certified?

No. WattleAddr is architected for IRAP-aligned workloads, and we hold no certification. The Government page answers the procurement checklist row by row, including what we do not hold.

More: Government and regulated industries, Data Residency Attestation, Security

Do I need to credit G-NAF in my product?

Yes. The G-NAF licence requires attribution to Geoscape Australia where your users can see it. The docs give the exact wording. The Terms set out your G-NAF obligations.

More: G-NAF attribution, Terms

Is there an SLA, and where is the live status?

The Service Level Agreement page says which plans and contracts it covers. The status page shows live availability and the G-NAF release being served.

More: Service Level Agreement, Status

Is the WattleAddr console and website accessible?

The Accessibility page is the statement. It says what has been tested and what is partly done.

More: Accessibility