Build notification lists from your own software, or ask an AI assistant to do it for you. The API and the MCP server use the same lists, limits and downloads as the website.
The API and the MCP server come with the Business and Agency plans. A key works for as long as the plan is active. If the plan lapses, its keys stop working until it is renewed.
On a free account, Pro or a job pass, the API keys section of your account page shows a link to upgrade instead. Compare plans.
nrk_ and is shown once only. We keep a fingerprint of the key, not the key itself, so we cannot show it to you again.You can hold up to five keys. Revoke one you no longer use, or one you think has leaked, and make a new one. A revoked key stops working straight away.
Treat a key like a password. Anyone who has it can build lists on your plan.
Send your key in the Authorization header on every request. Requests and replies are JSON.
curl https://noticeradius.com.au/wp-json/noticeradius/api/v1/me \
-H "Authorization: Bearer nrk_your_key_here"That returns your plan, its limits and how many exports you have used this month. To build a list, send an address, or lat and lon, plus a radius in metres.
curl -X POST https://noticeradius.com.au/wp-json/noticeradius/api/v1/lists \
-H "Authorization: Bearer nrk_your_key_here" \
-H "Content-Type: application/json" \
-d '{"address": "10 Gore Avenue, Kirrawee NSW", "radius": 250, "label": "Job 1042"}'The reply has the list id, the number of addresses, every address with its distance from the site, and two download links: the CSV and the print ready labels PDF. Shortened, it looks like this.
{
"id": 118,
"label": "Job 1042",
"address": "10 GORE AVENUE, KIRRAWEE NSW 2232",
"radius_m": 250,
"address_count": 188,
"charged_as": "plan",
"downloads": {
"csv": "https://noticeradius.com.au/wp-json/noticeradius/api/v1/file?t=csv&id=118&e=...&s=...",
"labels_pdf": "https://noticeradius.com.au/wp-json/noticeradius/api/v1/file?t=labels&id=118&e=...&s=...",
"expires_at": "2026-10-10T03:30:02Z"
},
"addresses": [
{
"address": "5 FAUNA PLACE, KIRRAWEE NSW 2232",
"street": "5 FAUNA PLACE",
"suburb": "KIRRAWEE",
"state": "NSW",
"postcode": "2232",
"lat": -34.0342267,
"lon": 151.0702823,
"distance_m": 96.1,
"is_unit": false,
"gnaf_pid": "GANSW705108364"
}
]
}You can also send include_units (default true), primary_only (default false), exclude_vacant_land (default true), addressee (the first line on each label, default THE RESIDENT) and include_addresses (set it to false to get only the count and the links).
A list built through the API counts exactly like one built on the website. It uses one export from your plan, and the same radius and address limits apply. Building the same list again within seven days is free. If a list is bigger than your plan allows, the request is refused and nothing is used.
The download links work without a key, so you can pass them to whoever is doing the letterbox drop. They expire after an hour. Ask for the list again with GET /lists/{id} to get fresh links. Reading a list never uses an export. Its addresses and links stay available for seven days after the list was paid for.
Every path starts with https://noticeradius.com.au/wp-json/noticeradius/api/v1.
| Method | Path | What it does |
|---|---|---|
| GET | /me | Your plan, its limits and the exports used this month. |
| GET | /addresses/search?q= | Look up an address. Returns matches with coordinates. |
| POST | /areas | Build an area of addresses from a polygon, street ranges, a pasted or uploaded address list, or GeoJSON or KML. Does not use an export. |
| POST | /lists | Build a list from an address, or lat and lon, plus a radius in metres. Or send an area_id from /areas instead. |
| GET | /lists | Your recent lists built through the API. |
| GET | /lists/{id} | One of your lists again, with fresh download links. Add include_addresses=true for the addresses. |
| GET | /works | Planning applications (DAs and CDCs). Filters: state, cat, stage, q, days, lat, lon, km, limit (up to 500) and offset. |
| GET | /fireworks?state= | Upcoming registered fireworks displays. Add lat, lon and km to search near a point. |
| POST | /reports | Create a notification report for one of your lists. |
| GET | /alerts | Your job alerts, how many your plan includes and whether webhooks are on. |
| POST | /alerts | Save a job alert. See Job alerts below. |
| DELETE | /alerts/{id} | Delete one of your job alerts. |
For shutdowns and outages, where the affected area is not a circle, build an area first. Send kind as polygon (coords, a list of [lon, lat] corners), streets (a list of street, suburb, from, to and side), import (text, a CSV or one address per line) or file (text, GeoJSON or KML). Add critical_text for critical customer addresses. You get back an id, the address count, and any rows that did not match. Send that id as area_id to POST /lists to download the list. The area is held for 400 days.
To create a report, send list_id with the authority, work and notification details, the same fields as the report form on your account page. Agency accounts also send work.brand_id to choose the brand. You get back the report number, the public verify link and a PDF download link. Neighbour notices are still made on your account page.
Job alerts email you each morning, at about 7am Sydney time, with new planning applications in the areas you choose, and new fireworks displays if you want them. If nothing is new, there is no email. Pro includes 1 alert, Business 5 and Agency 20. Manage them on your account page, or through the API and MCP on Business and Agency.
Send either an address (or lat and lon) with radius_m from 500 to 20000, or areas, a list of up to 20 suburbs or postcodes. Optional: name, state, categories, stages, min_cost and fireworks. The values for categories and stages are the same as for /works.
curl -X POST https://noticeradius.com.au/wp-json/noticeradius/api/v1/alerts \
-H "Authorization: Bearer nrk_your_key_here" \
-H "Content-Type: application/json" \
-d '{"name":"Shire pools","areas":["Kirrawee","2232"],"categories":["pool"],"fireworks":true}'Add webhook_url (https only) and each morning we also POST the new items there as JSON. The reply to your request includes webhook_secret once, so store it somewhere safe. Every delivery carries X-NoticeRadius-Timestamp and X-NoticeRadius-Signature. The signature is sha256= followed by the HMAC-SHA256 of the timestamp, a full stop and the raw body, keyed with your secret.
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);
if (!hash_equals($expected, $signature)) { http_response_code(401); exit; }Reply with any 2xx within 10 seconds. If a delivery fails we try three more times over the day. After three days in a row of failed deliveries the webhook pauses, and your account page says why. Save the alert to turn it back on.
Each key can make 60 requests a minute, and each account 120 a minute across all its keys. Every reply carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. Go over the limit and you get a 429 with a Retry-After header that says how many seconds to wait.
Errors come back as JSON with a code and a plain message.
{"error": {"code": "nr_api_bad_key", "message": "That API key is not valid, or it has been revoked.", "status": 401}}| Status | What it means |
|---|---|
| 400 | The request was malformed, for example broken JSON or a bad download link. |
| 401 | No key, a wrong key or a revoked key. |
| 402 | This month’s exports are used up. The reply lists your upgrade options. |
| 403 | Your plan does not include the API, or the list is bigger than your plan allows. |
| 404 | There is no list with that id on your account. |
| 410 | A download link has expired. |
| 422 | Something in the request is missing or out of range. The reply says which field. |
| 429 | Too many requests. Wait and try again. |
| 502 | The address engine did not answer. Try again in a minute. |
NoticeRadius also runs an MCP server. Connect it to Claude or another AI assistant and it can find addresses, build lists, look up planning applications and fireworks displays, and create notification reports for you. It uses the same keys, limits and usage as the API.
Server URL: https://noticeradius.com.au/mcp
authorization with the value Bearer, a space, then your key.If your Claude account does not show a Request headers section yet, connect through Claude Code or one of the other clients below for now.
claude mcp add --transport http noticeradius https://noticeradius.com.au/mcp \
--header "Authorization: Bearer nrk_your_key_here"Any client that supports remote servers over Streamable HTTP will work. Point it at the server URL and send your key in the Authorization header. Most take a config like this.
{
"mcpServers": {
"noticeradius": {
"type": "http",
"url": "https://noticeradius.com.au/mcp",
"headers": {
"Authorization": "Bearer nrk_your_key_here"
}
}
}
}If a client only runs local servers, the mcp-remote bridge can carry the header for it.
{
"mcpServers": {
"noticeradius": {
"command": "npx",
"args": [
"mcp-remote",
"https://noticeradius.com.au/mcp",
"--header",
"Authorization:${NR_AUTH}"
],
"env": {
"NR_AUTH": "Bearer nrk_your_key_here"
}
}
}
}| Tool | What it does |
|---|---|
account_status | Your plan, its limits and this month’s usage. |
find_address | Look up an address and its coordinates. |
create_area | Build an area of addresses from a polygon, street ranges, an address list or a GeoJSON or KML file, for shutdown and outage notices. |
build_notification_list | Build a list and get the CSV and labels links. Give it an area_id to use an area. |
get_list | Fetch one of your lists again with fresh links. |
search_planning_applications | DAs and CDCs by state, type of work, stage or distance from a point. |
search_fireworks_displays | Upcoming registered fireworks displays, near a point if you like. |
create_notification_report | Make a notification report for one of your lists. |
list_alerts | Your job alerts and when each last emailed you. |
create_alert | Save a job alert for an address and radius, or for suburbs and postcodes. |
delete_alert | Delete one of your job alerts. |
A list built by an assistant uses an export, the same as anywhere else. The assistant cannot change your plan or spend money.
Stuck, or need something the API does not do yet? Get in touch.
Make a key on your account page and you can build your first list in a minute.