# Additional Properties

Use this guide to choose additional building properties, request multiple values, and understand their availability, units, and credit costs.

Use `additionalProperties` on a building lookup or search to request related data. The objects appear inside `features[].properties` when available. These values apply to the current `/v2/buildings` endpoints.

## Choose properties

Send one comma-separated value, for example `additionalProperties=height,roof`. Names are case-sensitive. Omit the parameter for base building attributes only.

| Value | Response object | Main fields | Use |
| --- | --- | --- | --- |
| `height` | `properties.height` | `roofHeight`, `eaveHeight`, `buildingVolume`, `estimatedFloors` | Current height model |
| `roof` | `properties.roof` | `roofColour`, `roofShape`, `primaryRoofMaterial`, `roofSlope`, `treeOverhang` | Current roof model |
| `solar` | `properties.solar` | `solarFlag`, `solarPanel`, `solarArea`, `dailyEstimatedPower`, capture information | Current solar model |
| `heightsAndRoofs` | `properties.heightsAndRoofs` | Legacy height and roof fields, including `roofType` | Supported for compatibility. Prefer `height,roof` |
| `poolIndicator` | `properties.poolIndicator` | `swimmingPoolAdjacent`, `dateSwimmingPoolReviewed` | Legacy pool model. There is currently no accepted `pool` replacement value |
| `solarIndicator` | `properties.solarIndicator` | `solarPanel`, `dateSolarPanelReviewed` | Supported for compatibility. Prefer `solar` |

The current models also include record dates and state. See the [Buildings schemas](/reference/~schemas#buildingsv21-height) for field definitions.

Set `GEOSCAPE_API_KEY` to your application's Consumer Key before running this example. See [Authentication](/guides/authentication) for setup.

```shell
curl --fail-with-body --get \
  "https://api.psma.com.au/v2/buildings/bldzu0Cc8T2V33A" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "additionalProperties=height,roof,solar"
```

In the interactive tester, select each value you need from the `additionalProperties` control. The request sends them together in one comma-separated parameter.

## Handle unavailable data

- `height`, `roof`, and `solar` are omitted when their related record is unavailable
- Optional fields inside a returned object are omitted when they have no value
- Legacy objects can be empty when no related values are available. An empty object is not a positive indicator
- An omitted solar object does not mean that no solar panels were identified
- Requesting an additional property does not guarantee coverage for that building
- An unrecognised value fails the request with `400`. It is not silently ignored

For example, `additionalProperties=pool` is invalid. Use `poolIndicator` for the supported legacy pool object.

## Read measurements and flags

| Attribute | Unit or interpretation |
| --- | --- |
| `height.roofHeight` | Tallest point of the roof, in metres |
| `height.eaveHeight` | Average eave height, in metres |
| `height.buildingVolume` | Cubic metres |
| `height.estimatedFloors` | Estimated floor count, returned as an integer. It is not a surveyed count |
| `roof.roofSlope` | Roof slope in degrees |
| `roof.roofColour` | RGB colour in hexadecimal `#rrggbb` format |
| `roof.treeOverhang` | `Yes` or `No` string |
| `solar.captureResolution` | Centimetres, returned as a string |
| `solar.solarFlag` | `Yes` or `No` indicates whether a visible photovoltaic panel is identified |
| `solar.solarPanel` | Boolean form of the flag. `Yes` becomes `true`, `No` becomes `false`, and other values are omitted |
| `solar.solarArea` | Square metres |
| `solar.dailyEstimatedPower` | Estimated energy generated on an average day, in kilowatt hours (kWh) |

Legacy height and roof measurements use the same units. Use [Field Migration](/guides/buildings/national-buildings-4-0) for compatibility mappings.

## Roof shape and complexity

`roof.roofShape` describes the roof's shape:

| Shape | Meaning |
| --- | --- |
| Flat | A single horizontal plane |
| Hipped | Multiple sloping planes meeting at a ridge, with sloped ends |
| Gabled | Two sloping planes meeting along a ridge |
| Shed | A single sloping plane |
| Mansard | Multiple planes with sloping sections and a flatter upper section |
| Mixed | A combination of hipped and gabled shapes |
| Other | A shape outside those categories |

These definitions help interpret values. They are not request options or an enforced response enum.

The legacy `heightsAndRoofs.roofType` groups pitch and complexity as `Flat`, `Moderate pitch or complexity`, or `Steep pitch or high complexity`. It is not another name for `roofShape`, and it can be omitted when roof data is unavailable. Use `roof.roofShape` and `roof.roofSlope` when you need separate shape and slope values.

<span id="transaction-units"></span>

## Credit usage

Buildings API access requires an application with access to the product and a subscription that permits premium data. Returning extra attributes can increase credit usage.

| Returned data | Credits per building |
| --- | --- |
| Base building | 8 |
| `height` | +2 |
| `roof` | +2 |
| `heightsAndRoofs` | +4 |
| `solar` or `solarIndicator` | +4 |
| `poolIndicator` | +4 |

- A building with `height,roof,solar` uses 16 credits: 8 base, 2 height, 2 roof, and 4 solar
- Current additional objects contribute a charge when they are returned. Requesting an unavailable `height`, `roof`, or `solar` object adds no charge for that object
- Legacy objects, including empty ones, can still contribute a charge. Prefer the current models where available
- Returning `heightsAndRoofs` together with `height` or `roof` charges the combined height-and-roof amount once
- Returning both `solar` and `solarIndicator` charges the solar amount once
- Feature charges add across all buildings returned in the request. The relationship-record endpoints do not apply these feature charges

Request-rate limits are separate from credit usage. See [Rate Limiting](/guides/rate-limiting).

## Next steps

- [Try the Buildings Quickstart](/guides/buildings/quickstart)
- [Migrate legacy building fields](/guides/buildings/national-buildings-4-0)
- [Browse building schemas](/reference/~schemas#buildingsv21-feature)