# Products and Versions

Use this guide to understand how Insight Packs relate to parent products, control which products a listing includes, and read version labels introduced in Datasets v1.1.

## Parent and child products

An Insight Pack is a child product associated with a parent product. Its dataset object has its own `product` code and a `parentProduct` code identifying the family.

This synthetic excerpt illustrates a Height Insight Pack:

```json
{
  "name": "Buildings - Height",
  "product": "BUILDING-HEIGHT",
  "parentProduct": "BUILDINGS",
  "versionString": "004-000-001"
}
```

This excerpt illustrates the relationship rather than a complete dataset response. `parentProduct` is omitted when the dataset has no parent. It identifies a product family, not another dataset ID.

## Include child products

`includeChildProducts` is a boolean query parameter on the standard dataset listing. It defaults to `true`.

| Product filter | includeChildProducts | Result selection |
| --- | --- | --- |
| `BUILDINGS` | `true` or omitted | Directly matching Buildings datasets and child datasets with `parentProduct=BUILDINGS` |
| `BUILDINGS` | `false` | Directly matching Buildings datasets |
| `BUILDING-ROOF` | `false` | Directly matching Roof Insight Pack datasets. A child is not excluded when explicitly selected |
| No product filter | `true` or omitted | All matching products, including children |
| No product filter | `false` | Matching datasets without a parent product |

Other filters, licensing restrictions, and publication availability still apply. `includeChildProducts=true` does not remove those restrictions or grant download access.

### Request a product family

```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=BUILDINGS" \
  --data-urlencode "release=latest"
```

### Request a child directly

```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=BUILDING-ROOF" \
  --data-urlencode "includeChildProducts=false" \
  --data-urlencode "release=latest"
```

## Buildings compatibility

`BUILDINGS` is the product code for National Buildings 4.0. The existing `GEOSCAPE BUILDINGS` filter also includes `BUILDINGS` to support integrations using the older product code.

- With child inclusion enabled, the filter also includes matching children of those product codes
- With `includeChildProducts=false`, it still selects the directly matching legacy and current Buildings products
- Filter `product=BUILDINGS` when you want current Buildings files without that compatibility expansion

The selected release and your other filters determine which files are returned. A query does not guarantee files from both product generations.

## Read version labels

`versionString` provides the displayed version. Newer versions can use three zero-padded groups, such as `004-000-001`. For older records without a supplied `versionString`, the API renders the legacy numeric `version` as text.

- Treat `versionString` as text so leading zeros and separators are preserved
- Do not assume every record uses the three-group format
- Keep `release`, `publishDate`, and version separate in your application
- Accept optional `parentProduct` and other additional response fields

The v1.1 reference describes the existing `/v1/datasets` request paths. There is no `/v1.1/datasets` path or separate version-switch parameter to add to a request.

## Next steps

- [Find and filter datasets](/guides/datasets/finding-datasets)
- [Download a licensed dataset](/guides/datasets/quickstart)