Documentation

Datasets API Quickstart

Use this guide to find a dataset covered by your agreement, read its metadata, and download its file. It also shows where to find custom datasets supplied to your organisation.

Before you begin

You need:

A Geoscape Hub application with Datasets API access and its Consumer Key
An Enterprise Agreement covering the dataset's product, region, and release if you want to download it
A terminal with curl and jq

Listing and searching are free. Contact +61 2 6260 9000 or sales@geoscape.com.au for licensed dataset access. Follow Authentication to configure your application.

1. Set your Consumer Key

Code
export GEOSCAPE_API_KEY="YOUR_CONSUMER_KEY"

The header name is Authorization. Its value is the Consumer Key directly, without a Bearer prefix. The Consumer Secret is not used in these requests.

The v1.1 reference documents requests at https://api.psma.com.au/v1/datasets. The specification version does not change the request path to /v1.1.

2. Find a licensed dataset

Request the latest G-NAF files available under your agreement:

Code
DATASETS_RESULT=$(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" \
  --data-urlencode "release=latest" \
  --data-urlencode "licenced=true" \
  --data-urlencode "includeChildProducts=false")

printf '%s\n' "$DATASETS_RESULT" | jq '.datasets'

includeChildProducts=false keeps this request focused on the selected product. Omit it to include any matching child products. release=latest selects the latest release for each product, region, format, and datum combination, so the response can contain several files.

Check the metadata before choosing a file:

Field	Use
`id`	Copy the dataset identifier for a download-link request
`product` and `parentProduct`	Identify the product and its product family, when applicable
`region`	Check spatial coverage
`format` and `datum`	Select the file format and coordinate system you need
`release` and `publishDate`	Distinguish the release month from the publication date
`versionString`	Display the dataset version
`size`	Read the download size in bytes, when supplied
`licenced`	Check whether your agreement covers this standard dataset
`links.next`	Retrieve another page of matching files, when present

No matches returns 200 with datasets: [] and a No datasets found message. Broaden the filters or check your agreement before requesting a download.

3. Request a download link

The following command demonstrates selecting the first listed file. In your application, choose the file with the required coverage, format, datum, and release:

Code
DOWNLOAD_RESULT='{}'
DATASET_ID=$(printf '%s\n' "$DATASETS_RESULT" | jq -r '.datasets[0].id // empty')

if [ -n "$DATASET_ID" ]; then
  DOWNLOAD_RESULT=$(curl --fail-with-body \
    "https://api.psma.com.au/v1/datasets/$DATASET_ID" \
    -H "Authorization: $GEOSCAPE_API_KEY" \
    -H "Accept: application/json")
  printf '%s\n' "$DOWNLOAD_RESULT" | jq .
else
  printf '%s\n' "No dataset selected. Review the filters and access before requesting a download."
fi

The response contains a one-item datasets array with a downloadLink. This endpoint returns JSON metadata and a link rather than the file itself. Request one dataset ID at a time.

4. Download the file

Use the complete signed URL returned in downloadLink. Do not add your Consumer Key to the file request:

Code
DOWNLOAD_URL=$(printf '%s\n' "$DOWNLOAD_RESULT" | jq -r '.datasets[0].downloadLink // empty')

if [ -n "$DOWNLOAD_URL" ]; then
  curl --fail --location "$DOWNLOAD_URL" --output dataset.zip
else
  printf '%s\n' "No download link returned. Check the lookup response."
fi

The link expires after 15 minutes. Request a fresh link if it expires. Do not store it as a permanent download URL. When checksums are supplied, compare the downloaded file with checksumSha256 or checksumMd5.

Retain the returned attribution and follow the Geoscape Developer Terms.

Custom datasets

List datasets supplied to your organisation at /v1/datasets/custom, then request a download link at /v1/datasets/custom/{datasetId}. Use IDs from the custom listing with the custom download endpoint.

Code
curl --fail-with-body \
  "https://api.psma.com.au/v1/datasets/custom" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json"

Custom dataset names, formats, release labels, and versions can differ from the standard catalogue. See Finding Datasets.

If a request fails

For 400, correct invalid filters or request parameters
For 401, check the Consumer Key and application access
For a standard download's 403, check whether your agreement covers the product, region, and release
For 404, check the ID and whether it belongs to a standard or custom dataset

See Error Handling and Rate Limiting for body handling and retries.

Next steps

Last modified on October 29, 2026