Documentation

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:


Code
{
  "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

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

Request a child directly

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=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

Last modified on October 29, 2026