gnafr

Fast, fuzzy Australian address matching against the G-NAF

Preface

This is the manual for gnafr — an R package for fast, fuzzy bulk matching of free-text Australian addresses against the Geocoded National Address File (G-NAF), backed by an embedded DuckDB database.

If you have a column of messy, human-typed addresses and want a latitude/longitude, a standardised address, and a confidence score for each one — at the scale of a few rows or a few million — this package (and this manual) is for you.

Who this is for

You should already be comfortable with R and data.table. No DuckDB or SQL experience is assumed — gnafr handles that internally — but Under the hood explains the SQL gnafr generates, for readers who want to understand exactly what’s happening or who need to debug an unexpected result.

How this manual is organised

Getting started

• About gnafr — what G-NAF is, what problem gnafr solves, and how the package is put together.
• Quick guide — install the package and run your first match in a few minutes, using a tiny in-memory database (no G-NAF download required).

Under the hood

• Theory: how matching works — the parsing pipeline, the scoring formula, and the multi-path matching strategy, explained from the actual implementation rather than from the outside.
• Building a good lookup table — a guided walkthrough of build_gnaf_database.R, the reference pipeline for turning a raw G-NAF download into a database that matches well.

Reference

• Function reference — every exported function, grouped by task, with arguments, return values, and examples.
• Other features — the Shiny geocoder app, spatial helpers (sf + leaflet), synthetic test-data generation, and the match cache.
• Alias matching in practice — real examples from a loaded G-NAF database showing when alias matching helps, and how to switch it off.
• Troubleshooting & performance — common failure modes, how to read them, and how to keep large batch jobs fast.

Note

Almost every code chunk in this manual that uses a real database is marked eval: false, because it points at a multi-gigabyte G-NAF file that doesn’t exist in this build environment. Chunks that do run live mostly use a tiny synthetic database created with gnaf_connect(":memory:") — you’ll see their actual output printed inline, generated from the package’s current source at render time. Alias matching in practice is the one exception: it runs live against a real, fully-loaded G-NAF database, so its output reflects an actual production-sized dataset rather than a handful of synthetic rows.