Documentation

Finding Datasets

Use this guide to narrow dataset searches, choose releases and file variants, follow pagination links, and handle licensed downloads and custom datasets.

Combine filters

Use GET /v1/datasets to search the published catalogue. Filters combine to narrow the result. Multiple values within a filter match any of those values.

Omit region, format, or release to apply no filter for that field
Send product, region, format, and datum as single comma-separated query values
Standard filter values are case-insensitive. Preserve spaces inside names such as ALL STATES
URL-encode query values. With curl, use --get and --data-urlencode
Use query for free-text search alongside the exact filters
Set licenced=true to list files covered by your agreement. The default false applies no licence filter

Code
curl --fail-with-body --get \
  "https://api.psma.com.au/v1/datasets" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "product=G-NAF,G-NAF CORE" \
  --data-urlencode "region=NSW,QLD" \
  --data-urlencode "format=PSV,SHP" \
  --data-urlencode "datum=GDA2020" \
  --data-urlencode "release=latest"

Filter values

These are the supported values in the v1.1 reference. A supported value does not guarantee a file is currently available for every region, format, datum, or release.

Products

ABS BOUNDARIES
ABS-ASGS-2026-MAIN-STRUCTURE
ADMINISTRATIVE BOUNDARIES
ELECTORAL BOUNDARIES
G-NAF CORE
G-NAF
GEOSCAPE AIRPORTS
GEOSCAPE BUILDINGS
GEOSCAPE CADASTRE
GEOSCAPE GREENSPACE
GEOSCAPE HYDROLOGY
GEOSCAPE LOCAL GOVERNMENT AREAS
GEOSCAPE LOCALITIES
GEOSCAPE PLANNING
GEOSCAPE PROPERTY
GEOSCAPE RAIL
GEOSCAPE ROADS
GEOSCAPE SOLAR
GEOSCAPE SURFACE COVER
GEOSCAPE TREES
GEOSCAPE WARDS
POSTCODE BOUNDARIES
STATE BOUNDARIES
TOWN POINTS
BUILDINGS
BUILDING-HEIGHT
BUILDING-ROOF
BUILDING-SOLAR
ADDRESS-POOL

includeChildProducts defaults to true. See Products and Versions for product families and the Buildings compatibility mapping.

Regions

Value	Coverage
`AUSTRALIA`, `ALL STATES`	Catalogue coverage labels. Choose the label returned for the file you need
`ACTNSW`	Combined ACT and NSW coverage
`ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA`, `OT`	State or territory coverage

A filter for ACT or NSW also includes ACTNSW files. The file's region remains ACTNSW in the response.

Formats

Value	File format
`GDB`	File geodatabase
`GEOJSON`	GeoJSON
`SHP`	Shapefile
`TAB`	MapInfo TAB
`LYNX`	LYNX
`PUMP`	Oracle Data Pump
`GEOTIFF`	GeoTIFF raster
`PSV`	Pipe-separated values

Datums

Value	Meaning
`GDA94`	Geocentric Datum of Australia 1994
`GDA2020`	Geocentric Datum of Australia 2020
`NO DATUM`	No datum assigned to the file

The datum filter selects existing files. It does not transform their coordinates. See CRS & GDA2020 for background.

Choose releases

Input	Selection
`release=2025-03`	Files from that release month
`release=2024-09,2025-03`	Files within the inclusive release range
`release=latest`	The latest visible release for each product, region, format, and datum combination

Use lowercase latest. It selects the latest file for each variant rather than a single newest file across the catalogue. With licenced=true, latest selection applies to files covered by your agreement.

release is the dataset release month. publishDate is the date the file was published. They can differ.

For current Buildings files, filter product=BUILDINGS. A latest search without an explicit legacy Buildings product filter excludes legacy Buildings products. See the product-family guide for compatibility behaviour.

Paginate results

Both standard and custom listings use limit and offset:

limit defaults to 100 and accepts 1 to 1,000
offset defaults to 0 and skips matching files
links.numberMatched reports the matching file count
links.numberReturned reports files on the current page
links.self identifies the current page
Follow links.next while present, sending the same Authorization header

A listing with no matches returns 200, datasets: [], and messages: ["No datasets found"]. An empty page after matching results can also return 200. Check the page links and count before treating it as an empty search.

Download files

Choose a dataset from the listing using its coverage, format, datum, release, and version
Request /v1/datasets/{datasetId} to retrieve metadata and a signed link
Download the complete datasets[0].downloadLink URL without adding your Consumer Key
Request a fresh link if the 15-minute validity period has passed

Request one dataset ID per lookup. Each lookup returns its own file link. The API does not combine files into one download.

size is the file size in bytes, when supplied. Checksum fields, when supplied, describe the file for integrity checks. Reference examples use synthetic metadata, readable example IDs, and URLs under example.com. They contain no dataset contents, checksum values, or signing credentials and cannot be used to download data.

Licensing and errors

Searching the catalogue is free. Download access requires an Enterprise Agreement covering the file's product, region, and release. The licenced listing field reports that coverage for the caller. A visible dataset is not necessarily downloadable by that caller.

Response	Action
`400`	Correct invalid parameters. A download can also report that the original file is inaccessible and direct you to support
`401`	Resolve credentials or application access
Standard download `403`	Check agreement coverage or contact support
Download `404`	Check the ID, endpoint, and availability to your organisation
Custom download `409`	The file is not yet available for download
`429` or transient `500`	Follow shared retry guidance

Service errors use a messages array. Gateway authentication errors can use a fault object. File-download errors come from the signed URL's storage service, so their response body can differ from the API's JSON errors.

See Error Handling, Rate Limiting, and Attribution.

Custom datasets

Use /v1/datasets/custom for published, unexpired custom datasets available to your organisation:

product matches the custom product names supplied to you. Preserve casing and send multiple names as one comma-separated value
release accepts a supplied release label, a start and end range, or lowercase latest
query provides free-text search
Custom coverage, datum, format, and version values are supplied labels rather than the standard catalogue enums
Optional metadata can be omitted. Check for a value before displaying it

Request /v1/datasets/custom/{datasetId} to download a selected custom file. An ID unavailable to your organisation returns 404.

Next steps

Last modified on October 29, 2026