# 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

```shell
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](/guides/datasets/insight-pack-changes) 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](/guides/gda-2020) 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

1. Choose a dataset from the listing using its coverage, format, datum, release, and version
2. Request `/v1/datasets/{datasetId}` to retrieve metadata and a signed link
3. Download the complete `datasets[0].downloadLink` URL without adding your Consumer Key
4. 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](/guides/errors), [Rate Limiting](/guides/rate-limiting), and [Attribution](/guides/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

- [Make your first dataset download](/guides/datasets/quickstart)
- [Understand product families](/guides/datasets/insight-pack-changes)