Documentation

Test and UAT environments

How to give each non-production environment its own test key, what the limits are, and what to do when you reach the cap. The overview is on the test environments page.

Enterprise only. On every other plan, test mode lasts for the first 15 days of the account. On Enterprise, we can switch on test keys that do not expire for a workspace, by written agreement. They use the real engine and the real G-NAF data, are never billed, and never count toward your monthly lookups.The limits below are the defaults. We can set different limits for your workspace.

What the Terms say

These points are from the Plans, usage and metering section of the Terms of Service.

We switch this on for your workspace by written agreement. An email exchange with the account owner is enough.
Test keys are for development, testing and training only. They are never for production or for serving your users.
Performance and load tests use a live key and are billed. They need our written agreement to the date and rate first.
Test keys can stop when your workspace’s billable lookups are refused.
Test keys are not covered by the SLA.
We can change the limits or switch the option off on 30 days’ notice by email to the account owner. If that lowers the limits or switches the option off, you may cancel as the Terms describe.
We can suspend test keys straight away if we reasonably believe they are being misused. If we do, we tell the account owner why and restore them once the breach stops.

The limits

Limit	By default	What happens at the limit
Test lookups	10% of your contracted monthly lookups for each billing period. We can set a fixed number instead.	`402 test_cap_reached`. Nothing is charged.
Requests per second	5, shared by all the workspace’s test keys. We can set a different rate for your workspace.	`429 rate_limited` with a `Retry-After` header.
Addresses per batch call	5. Each address in a test batch uses one request from the rate, so it is never more than the per-second rate.	`400 batch_too_large`. Nothing is charged.
Bulk job rows	5,000 rows a day for each workspace, for jobs started on a test key. This limit is the same for every workspace.	`429 test_limit`. The job is not started.

A test lookup is counted the way a live lookup is billed. One address search session is one lookup. Address autocomplete keystrokes never count. A suburb and postcode search session counts once. Counting follows your billing period, not the calendar month.

Performance and load tests must use a live key. Those lookups are billed, and the test needs our written agreement to its date and rate first.

One key per environment

In the console, open API Keys and press + New API key.
Set Mode to Test. The key list then shows it as Test · no expiry.
Name the key for the environment and the system that uses it, for example sit-checkout, uat-claims or training-intake. Use a secret key for a server and a publishable key for a browser.
Lock the key. List the environment’s own domains on a publishable key and its own IP addresses on a secret key. A key with no lock works from anywhere, and it would spend your test cap and your shared test rate. The console warns when a browser test key has no domains.
Set the search-log privacy mode, as described below, before you load any data copied from production.

The test lookups for the whole workspace are shown in the console as Test lookups this period, next to the cap.

Telling test from live

Retrieve, verify, reverse geocoding and suburb and postcode retrieve and verify return "test": true and "billed": false on a test key. Autocomplete responses do not carry the flag. A check in your own test suite can fail the run if a response from a production-facing path says test, or if a test environment gets a response without it.

When the cap is reached

The API returns a 402. Nothing was charged.

HTTP/1.1 402 Payment Required { "error": { "code": "test_cap_reached", "message": "Nothing was charged. This workspace has used its 10,000 test lookups for this billing period. They start again at the start of the next billing period. Lookups on a live key are billed." } }

Test lookups start again at the start of the next billing period. Nothing needs to be reset.
A bulk job on a test key pauses with pause_reason test_cap_reached and carries on when the next period starts. You can download the partial results while it is paused.
In a batch call, the rows not processed before the cap come back with the error code test_cap_reached and are not charged.
Live keys are not affected by the test cap, and a live lookup is billed as usual.

A batch on a test key with more addresses than its batch size returns 400 batch_too_large. Send smaller batches, or use a bulk job. The full list of codes is in the error reference.

If the option ends

Test keys do not expire only while we have switched the option on for the workspace. The option ends when the workspace leaves Enterprise or has neither a contracted volume nor an agreed test cap. If we switch it off, or have not switched it on, the 15-day rule applies. Test keys then return 402 test_mode_expired from 15 days after the account was created. Create a live key to carry on.

Search-log privacy for copied production data

Test searches go into the workspace’s search log, like live searches, under the privacy mode of the key. Test data is often copied from production, so it can contain real customers’ addresses.

Keyed hash stores each query as a salted keyed hash and drops the matched-address text. This is pseudonymisation, not anonymisation, because we hold the key.
No-store keeps no query or matched-address text. Only counts, timing and billing are kept.

Choose one of them on each test key, and set the retention you need. You can also apply a mode to logs already stored. The modes are described in the privacy section of the docs and in the privacy policy.

Want test keys on your Enterprise agreement? Talk to sales. Already a customer? support@wattleaddr.com.au