Need help with gnaf-loader?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

147 Stars 53 Forks Apache License 2.0 542 Commits 5 Opened issues


A quick way to get started with Geoscape's open GNAF & Admin Boundaries

Services available


Need anything else?

Contributors list

# 300,359
Open Da...
350 commits
# 25,512
11 commits
# 39,036
Amazon ...
1 commit
# 768,731
Open Da...
1 commit
# 768,732
Open Da...
1 commit
# 31,961
1 commit

IMPORTANT: There have been significant changes in the August 2021 release. See the CHANGELOG for details


A quick way to load the complete Geocoded National Address File of Australia (GNAF) and Australian Administrative Boundaries into Postgres, simplified and ready to use as reference data for geocoding, analysis, visualisation and aggregation.

What's GNAF?

Have a look at these intro slides (PDF), as well as the page.

There are 3 options for loading the data

  1. Run the load-gnaf Python script and build the database yourself in a single step
  2. Pull the database from Docker Hub and run it in a container
  3. Download the GNAF and/or Admin Bdys Postgres dump files & restore them in your Postgres 12+ database

Option 1 - Run

Running the Python script takes 30-120 minutes on a Postgres server configured to take advantage of the RAM available.


To get a good load time you'll need to configure your Postgres server for performance. There's a good guide here, noting it's a few years old and some of the memory parameters can be beefed up if you have the RAM.


  • Postgres 10.x and above with PostGIS 2.2+
  • Add the Postgres bin directory to your system PATH
  • Python 3.6+ with Psycopg2 2.6+


  1. Download Geoscape GNAF from
  2. Download Geoscape Administrative Boundaries from (download the ESRI Shapefile GDA94 version)
  3. Unzip GNAF to a directory on your Postgres server
  4. Unzip Admin Bdys to a local directory
  5. Alter security on those directories to grant Postgres read access
  6. Create the target database (if required)
  7. Add PostGIS to the database (if required) by running the following SQL:
  8. Check the available and required arguments by running with the
    argument (see command line examples below)
  9. Run the script, come back in 30-120 minutes and enjoy!

Command Line Options

The behaviour of gnaf-loader can be controlled by specifying various command line options to the script. Supported arguments are:

Required Arguments

  • --gnaf-tables-path
    specifies the path to the extracted source GNAF tables (eg *.psv files). This should match the extracted directory which contains the subfolders
    Authority Code
    . This directory must be accessible by the Postgres server, and the corresponding local path for the server to this directory may need to be set via the
  • --local-server-dir
    specifies the local path on the Postgres server corresponding to
    . If the server is running locally this argument can be omitted.
  • --admin-bdys-path
    specifies the path to the extracted source admin boundary files. This path should contain a subfolder named
    Administrative Boundaries
    . Unlike
    , this path does not necessarily have to be accessible to the remote Postgres server.

Postgres Parameters

  • --pghost
    the host name for the Postgres server. This defaults to the
    environment variable if set, otherwise defaults to
  • --pgport
    the port number for the Postgres server. This defaults to the
    environment variable if set, otherwise
  • --pgdb
    the database name for Postgres server. This defaults to the
    environment variable if set, otherwise
  • --pguser
    the username for accessing the Postgres server. This defaults to the
    environment variable if set, otherwise
  • --pgpassword
    password for accessing the Postgres server. This defaults to the
    environment variable if set, otherwise

Optional Arguments

  • --geoscape-version
    Geoscape version number in YYYYMM format. Defaults to current year and last release month. e.g.
  • --raw-gnaf-schema
    schema name to store raw GNAF tables in. Defaults to
  • --raw-admin-schema
    schema name to store raw admin boundary tables in. Defaults to
  • --gnaf-schema
    destination schema name to store final GNAF tables in. Defaults to
  • --admin-schema
    destination schema name to store final admin boundary tables in. Defaults to
  • --states
    space separated list of states to load, eg
    --states VIC TAS
    . Defaults to loading all states.
  • --prevacuum
    forces the database to be vacuumed after dropping tables. Defaults to off, and specifying this option will slow the import process.
  • --raw-fk
    creates both primary & foreign keys for the raw GNAF tables. Defaults to off, and will slow the import process if specified. Use this option if you intend to utilise the raw GNAF tables as anything more then a temporary import step. Note that the final processed tables will always have appropriate primary and foreign keys set.
  • --raw-unlogged
    creates unlogged raw GNAF tables, speeding up the import. Defaults to off. Only specify this option if you don't care about the raw data tables after the import - they will be lost if the server crashes!
  • --max-processes
    specifies the maximum number of parallel processes to use for the data load. Set this to the number of cores on the Postgres server minus 2, but limit to 12 if 16+ cores - there is minimal benefit beyond 12. Defaults to 4.
  • --no-boundary-tag
    DO NOT tag all addresses with some of the key admin boundary IDs for creating aggregates and choropleth maps.

Example Command Line Arguments

  • Local Postgres server:
    python --gnaf-tables-path="C:\temp\geoscape_202108\G-NAF" --admin-bdys-path="C:\temp\geoscape_202108\Administrative Boundaries"
    Loads the GNAF tables to a Postgres server running locally. GNAF archives have been extracted to the folder
    , and admin boundaries have been extracted to the
    C:\temp\geoscape_202108\Administrative Boundaries
  • Remote Postgres server:
    python --gnaf-tables-path="\\svr\shared\gnaf" --local-server-dir="f:\shared\gnaf" --admin-bdys-path="c:\temp\unzipped\AdminBounds_ESRI"
    Loads the GNAF tables which have been extracted to the shared folder
    . This shared folder corresponds to the local
    folder on the Postgres server. Admin boundaries have been extracted to the
  • Loading only selected states:
    python --states VIC TAS NT ...
    Loads only the data for Victoria, Tasmania and Northern Territory


You can load the Admin Boundaries without GNAF. To do this: comment out steps 1, 3 and 4 in def main.

Note: you can't load GNAF without the Admin Bdys due to dependencies required to split Melbourne and to fix non-boundary locality_pids on addresses.


When using the resulting data from this process - you will need to adhere to the attribution requirements on the pages for GNAF and the Admin Bdys, as part of the open data licensing requirements.


  • The scripts will DROP ALL TABLES using CASCADE in the GNAF and Admin Bdy schemas and then recreate them; meaning you'll LOSE YOUR VIEWS if you have created any! If you want to keep the existing data - you'll need to change the schema names in the script or use a different database
  • All raw GNAF tables can be created UNLOGGED to speed up the data load. This will make them UNRECOVERABLE if your database is corrupted. You can run these scripts again to recreate them. If you think this sounds ok - set the unlogged_tables flag to True for a slightly faster load
  • Boundary tagging (on by default) will add 15-60 minutes to the process if you have PostGIS 2.2+. If you have PostGIS 2.1 or lower - it can take HOURS as the boundary tables can't be optimised!


  • Whilst you can choose which 4 schemas to load the data into, I haven't QA'd every permutation. Stick with the defaults if you have limited Postgres experience
  • If you're not running the Python script on the Postgres server, you'll need to have access to a network path to the GNAF files on the database server (to create the list of files to process). The alternative is to have a local copy of the raw files
  • The 'create tables' sql script will add the PostGIS extension to the database in the public schema, you don't need to add it to your database
  • There is an option to VACUUM the database at the start after dropping the existing GNAF/Admin Bdy tables - this doesn't really do anything outside of repeated testing. (I was too lazy to take it out of the code as it meant renumbering all the SQL files and I'd like to go to bed now)

Option 2 - Run the database in a docker container

GNAF and the Admin Boundaries are ready to use in Postgres in an image on Docker Hub.


  1. In your docker environment pull the image using
    docker pull minus34/gnafloader:latest
  2. Run using
    docker run --publish=5433:5432 minus34/gnafloader:latest
  3. Access Postgres in the container via port
    . Default login is - user:
    , password:

Note: the compressed Docker image is 6Gb, uncompressed is 16Gb

WARNING: The default postgres superuser password is insecure and should be changed using:


Option 3 - Load PG_DUMP Files

Download Postgres dump files and restore them in your database.

Should take 15-60 minutes.



  1. Download gnaf-202108.dmp (~1.4Gb)
  2. Download admin-bdys-202108.dmp (~3.6Gb)
  3. Edit the restore-gnaf-admin-bdys.bat or .sh script in the supporting-files folder for your database parameters and for the location of pg_restore
  4. Run the script, come back in 15-60 minutes and enjoy!

Data Licenses

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.

Incorporates or developed using Administrative Boundaries © Geoscape Australia licensed by the Commonwealth of Australia under Creative Commons Attribution 4.0 International licence (CC BY 4.0).


GNAF and the Admin Bdys have been customised to remove some of the known, minor limitations with the data. The most notable are: - All addresses link to a gazetted locality that has a boundary. Those small number of addresses that don't in raw GNAF have had their localitypid changed to a gazetted equivalent - Localities have had address and street counts added to them - Suburb-Locality bdys have been flattened into a single continuous layer of localities - South Australian Hundreds have been removed and ACT districts have been added where there are no gazetted localities - The Melbourne, VIC locality has been split into Melbourne, 3000 and Melbourne 3004 localities (the new locality PIDs are `loc9901d119afda1

loc9901d119afda_2`). The split occurs at the Yarra River (based on the postcodes in the Melbourne addresses) - A postcode boundaries layer has been created using the postcodes in the address tables. Whilst this closely emulates the official Geoscape postcode boundaries, there are several hundred addresses that are in the wrong postcode bdy. Do not treat this data as authoritative

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.