# 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](https://hub.geoscape.com.au/) 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](mailto:sales@geoscape.com.au) for licensed dataset access. Follow [Authentication](/guides/authentication) to configure your application.

## 1. Set your Consumer Key

```shell
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:

```shell
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:

```shell
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:

```shell
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](https://geoscape.com.au/legal/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.

```shell
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](/guides/datasets/finding-datasets#custom-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](/guides/errors) and [Rate Limiting](/guides/rate-limiting) for body handling and retries.

## Next steps

- [Choose filters and handle downloads](/guides/datasets/finding-datasets)
- [Understand Insight Packs and versions](/guides/datasets/insight-pack-changes)