# Australian Address Matcher (G-NAF) (`madrasco/australian-address-matcher`) Actor Matches messy Australian addresses to the official G-NAF address file: returns the clean address, its G-NAF persistent identifier (PID), a confidence score and a match status for every input line. Paste addresses or give a CSV URL. - **URL**: https://apify.com/madrasco/australian-address-matcher.md - **Developed by:** [Jack Valmadre](https://apify.com/madrasco) (community) - **Categories:** Business, Developer tools, Real estate - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ## Australian Address Matcher (G-NAF) Paste messy Australian street addresses (or link a CSV) and get back, for each line, the matching record in **G-NAF**, the national address file published by Geoscape Australia for the Commonwealth: a clean single-line address, the G-NAF persistent identifier (PID), a confidence score and a match status. Coverage: all states and territories in G-NAF (ACT, NSW, NT, QLD, SA, TAS, VIC, WA and Other Territories: Christmas Island, Cocos (Keeling) Islands, Jervis Bay, Norfolk Island), about 17.0 million address records in the August 2026 release. ### What you get per address | field | meaning | |---|---| | `rowNumber` | position of the line in your input (1, 2, 3 …) | | `input` | your line, unchanged | | `status` | `matched` · `building` (your line names a building with several units but no unit number; we return the building's own address) · `unit_not_found` (your line names a unit or level number that G-NAF does not list at that address; we return the building's own address, never a different unit) · `ambiguous` (several G-NAF records fit equally well; the best guess and up to 3 alternatives are returned) · `no_match` · `invalid_input` · `skipped` (not processed because your spending limit was reached) | | `matchedAddress` | e.g. `Unit 5, 12 Leeper Place, Isaacs ACT 2607` | | `gnafPid` | G-NAF address PID, e.g. `GAACT715700923` | | `confidence` | 1.00 exact text match · 0.99/0.98 match after normalising abbreviations, unit formats and noise · 0.90–0.99 fuzzy (spelling) match similarity · 0.97 building-level match · 0.95 when the unit was found under a level or building name your line left out · 0.80–0.89 for `unit_not_found` (building only) | | `matchMethod`, `matchLevel` | how it matched (exact / normalized / fuzzy) and at which level (address / building) | | `candidateCount` | how many G-NAF records fitted equally well (1 = a single clear record) | | `components` | unit, level, building/site name, number, street, locality, state, postcode | | `alternatives` | other candidates when the match is ambiguous | | `attribution` | the G-NAF attribution and licence link, required by the data licence; keep it with the data if you pass it on | **Numbers are kept as typed, with two exceptions that are always flagged** (both concern street-number ranges; see known weak spots below): a range G-NAF does not hold comes back as its first number at confidence 0.85, and in rare buildings a single number comes back as its range with status `unit_not_found`. Otherwise, spelling mistakes in street and suburb names are corrected, but unit, level and street numbers must match G-NAF exactly, including letters before or after the number: "3B Suttor St" is never returned as 3 or 3C, "Unit 510" is never returned as Unit 510B, and "6 Cypress Rd" is never returned as B6 Cypress Rd (nor "G2 Pugh Pl" as 2 Pugh Pl). If your line says "Unit 88, 43 Torrens Street, Braddon" and G-NAF has no Unit 88 there, you get `43 Torrens Street, Braddon ACT 2612` with status `unit_not_found`, not a nearby unit; if G-NAF has no record at all with your street number, you get `no_match` (similar records are listed under `alternatives`). Street-number ranges are kept too: G-NAF often files "19" and "19-21" (or "3" and "3-5") as one building, so for "Unit 312, 19-21 Balmoral Ave, Dandenong" with no Unit 312 in G-NAF you get `19-21 Balmoral Avenue`, not 19, and for "Unit 1381, 3 St Kilda Rd" you get 3, not 3-5; a building with a different street number is never returned, apart from the two range cases listed under known weak spots below. A typed range is always read as street numbers, never as a unit: "1-5 Mort St, City ACT" is numbers 1 to 5, not Unit 1 at 5 Mort St; if G-NAF holds neither the range nor its first number, you get `no_match` with the unit reading listed under `alternatives`. A line with a unit and a range ("Unit 1, 8-25 Blakey Close, Monash") keeps the range too: the answer is that unit at 8-25, or the 8-25 building with `unit_not_found`; if G-NAF holds neither, you get `no_match`, with records at another street number (such as Unit 1, 25 Blakey Close) listed only under `alternatives`. If the unit exists but your line leaves out a level or building name ("4/3 Loban Ct, Ngunnawal" for "Unit 4, Armatree Court, 3 Loban Court"), it is matched. When your line gives no unit type and G-NAF has, say, both Unit 6 and Shop 6 at the address, the result is `ambiguous` with both; "Unit 6" or "Shop 6" picks the one you named. A line with no street number ("Segenhoe St, Aberdeen NSW 2336") names a whole street, and usually comes back `no_match` (118 of 132 such lines in our 400-line real-address test did). It is answered only when G-NAF holds records without a street number on that street in the suburb you typed; when there are several, the result is `ambiguous` ("York Rd, Kellyville NSW 2155" gives 13). If the suburb on such a line is misspelt, you get `no_match`. A line that starts with a level ("Level 2, 1-7 Langhorne Street") is never answered with a unit of the same number: if G-NAF has no Level 2 there, you get the building with `unit_not_found`. **Building names are optional.** G-NAF names many buildings and sites ("Optus Centre, 10 Moore Street, City"). A line without the name ("10 Moore St, Canberra ACT 2601") still finds that record, and the clean address gives the name back. When G-NAF also holds the same number and street without a name, that record is preferred. ### How well it works (measured, not guaranteed) These figures come from a test set we also used while developing the matcher, so they are likely better than what you will see on new data. The set: 200 ACT lines (150 real G-NAF addresses we corrupted mechanically — abbreviations, typos, missing postcode/state, unit formats — plus 50 hand-written real-world-style lines, 11 of them deliberately unmatchable), run on 2026-09-25 against the August 2026 G-NAF release (ACT index): - the returned PID was exactly the right record for **82.0%** of lines; - the right record was among the equally good candidates for **90.0%**; - the right address at the level the line specifies (e.g. right building when the unit was left out) for **95.5%**; - a confident but wrong answer for **0 of 200** lines. Building names left out: 300 ACT addresses that G-NAF records with a building or site name, sampled at random and written without the name (" ACT "), returned the exact record for **299 of 300**; the other one went to a second G-NAF record with the same number and street and no name. Letters on numbers: 840 lines from 7 states built from G-NAF records whose unit or street number has a letter (Unit 24B, B6, 3A), typed with the letter, without it where G-NAF also has the plain number, and without it where it does not: **0** answers with a changed number; with the letter, 280 of 280 exact; without it where the plain number exists, 279 of 280 exact. Units G-NAF lacks: 210 lines from 7 states naming a unit number that does not exist at a real address returned that building with the typed street number (`unit_not_found`) for **207**, `no_match` for 3, and another building for **0**. Street-number ranges: 786 lines from ACT and Victoria typed as a range ("a-b Street"): 100 ranges G-NAF holds all returned that range; of 450 ranges G-NAF lacks, 440 returned the range's first number at 0.85 and 10 `no_match`; of 236 ranges where G-NAF has only "Unit a, b Street", 110 returned the first number at 0.85 and 126 `no_match`. A unit or level record was returned for **0** of the 786. A unit with a range, 400 more lines from the same states built from real units ("Unit 1, 8-25 Blakey Close" where G-NAF has Unit 1 at 25): of 300 where G-NAF has no record at the typed range, 300 returned `no_match` and **0** a record at another street number; of 100 where G-NAF has the unit at that range, 99 returned it and 1 `unit_not_found` with the typed range. A second check, 36 addresses sampled from G-NAF across all 9 states and territories and mechanically messed up (abbreviations, case, missing state or postcode, unit formats), returned the exact record for 36 of 36. These are small test sets we built ourselves; your data will differ. Always review `ambiguous`, `unit_not_found` and low-confidence rows. Known weak spots: when the address itself is missing from G-NAF, a fuzzy match can land on a similarly spelled street with the same number (e.g. a "10 Moore St" that G-NAF lacks could come back as 10 Mort St at about 0.92 confidence) — treat fuzzy matches below 0.95 as needing review; G-NAF sometimes holds the same address twice (with and without a building name, or a unit under two different levels), and we return one of them, marked `ambiguous` where we can tell; unit types are only told apart as shop, office or dwelling (Unit, Flat, Apartment, Villa ... are treated alike); a line that drops a letter G-NAF has (e.g. "Unit 3" for G-NAF's "Unit G3") gets `unit_not_found`, not the lettered unit; a single street number that G-NAF holds only as a range ("100 Hambidge Cres, Chisholm" for 100-106) gives `no_match`, except in the rare building where G-NAF files units under the plain number and the building itself only as the range: a unit it lacks there returns the range with `unit_not_found`; a street-number range that G-NAF does not hold ("8-14 Epsom Rd" when G-NAF has 8-12) returns the range's first number at 0.85 confidence, or `no_match`; building or site names in unusual positions, abbreviated levels ("L 2") that may still be read as "Unit 2" when G-NAF has no Level 2, corner descriptions, PO boxes (not in G-NAF — reported as `no_match`), lot/section references. ### Input - `addresses`: one address per line; the actor stops after 10,000 lines per run. Long lists need a longer run timeout: in our 2026-09-26 run of 400 real addresses (NSW and Victorian school lists and the charity register), loading the index for 8 states took about 106 s and matching then ran at about 3 lines a second, so a 15-minute timeout fits roughly 2,000 lines. For longer lists raise the run timeout (Run options) or split the list. - `csvUrl` + optional `csvColumn`: a public CSV link (max 20 MB). - `minConfidence` (default 0.90): raise it for fewer wrong matches, lower it (not below 0.80) for more matches. Each address needs a suburb, state or postcode so the actor knows which state's index to load; only the states your list needs are loaded, so a single-state list runs faster and cheaper than a nationwide one. A list covering every state loads about 7.1 GB of index: keep the default 4 GB memory (runs get disk space of twice the memory). ### Cost Runs use your own Apify platform usage (compute and data transfer), mostly for loading the index at the start of the run. Measured 2026-09-25 on our own runs at 4 GB memory: ACT-only list ~US$0.003, NSW-only ~US$0.05, all states about US$0.10–0.15 per run. Matching adds compute time as the list grows (about 3 lines a second in our 400-line test run, which cost US$0.124 including loading 8 states). These figures were measured with the earlier gzip index; the current, smaller index may cost a little less. Your costs may differ with list size, memory and Apify's prices. ### Data, licence and permitted use - Uses G-NAF (August 2026 release), which is updated quarterly — addresses created since the release are not in it. - Incorporates or developed using G-NAF © Geoscape Australia licensed by the Commonwealth of Australia under the Open Geo-coded National Address File (G-NAF) End User Licence Agreement (https://data.gov.au/data/dataset/19432f89-dc3a-4ef3-b943-5326ef1dbecc). We modified the data: G-NAF tables are converted into a search index (normalised address keys and display strings); addresses are not altered. - G-NAF is provided by the licensor as-is, without warranties; see the licence's disclaimer (section 5). - **The G-NAF licence does not allow using G-NAF to compile address lists for sending mail unless each address is verified against a second source.** Do not use this actor's output as a mailing list without that verification. - The G-NAF licence page also requires that end users use the data only in ways consistent with the Australian Privacy Principles under the Privacy Act 1988 (Cth). - Not an address-validation or deliverability guarantee; not affiliated with or endorsed by Geoscape Australia or Australia Post. ### Privacy Addresses you submit are processed only to produce your results and are stored only in your own Apify run storage. We don't keep or reuse them. ### Support Use the Issues tab on this page. Built and maintained by Madrasco with AI assistance; a human owner can be reached on request. # Actor input Schema ## `addresses` (type: `array`): One Australian street address per line, in any format (e.g. '5/12 Leeper Pl Isaacs'). At most 10,000 per run together with the CSV; lists over about 2,000 lines need a longer run timeout (about 3 lines a second after the index loads). ## `csvUrl` (type: `string`): A public http(s) link to a CSV file (max 20 MB). Addresses are read from the column named below, else the first column whose header contains 'address', else the first column. ## `csvColumn` (type: `string`): Header of the column holding the full address (case-insensitive). ## `minConfidence` (type: `string`): Similarity needed for a fuzzy match, from 0.80 to 1.00. Higher = fewer wrong matches, more 'no\_match' rows. Default 0.90. ## Actor input object example ```json { "addresses": [ "132/148 Bunda St City ACT", "u5/12 leeper pl, isaacs ACT", "43 Torrens Street, Braddon 2612" ], "minConfidence": "0.90" } ``` # Actor output Schema ## `results` (type: `string`): One dataset row per input address: matched G-NAF address, persistent identifier (PID), confidence and match status. ## `summary` (type: `string`): Counts of addresses given and by match status. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "addresses": [ "132/148 Bunda St City ACT", "u5/12 leeper pl, isaacs ACT", "43 Torrens Street, Braddon 2612" ] }; // Run the Actor and wait for it to finish const run = await client.actor("madrasco/australian-address-matcher").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "addresses": [ "132/148 Bunda St City ACT", "u5/12 leeper pl, isaacs ACT", "43 Torrens Street, Braddon 2612", ] } # Run the Actor and wait for it to finish run = client.actor("madrasco/australian-address-matcher").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "addresses": [ "132/148 Bunda St City ACT", "u5/12 leeper pl, isaacs ACT", "43 Torrens Street, Braddon 2612" ] }' | apify call madrasco/australian-address-matcher --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,madrasco/australian-address-matcher" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/Sq7tdjPnBghEjaaES/builds/tMHgq3D8tevep4Kfk/openapi.json