# Field Migration

Use this guide to migrate legacy building fields and additional-property requests to the current API.

The current Buildings API uses the National Buildings 4.0 data model.

Dataset fields and API response fields are not identical. The API can omit optional values and does not expose every field in the underlying relationship tables. Use the [current reference](/reference/buildings-v2-1-building) as the response contract.

## Use current base attributes

| Purpose | Current fields |
| --- | --- |
| Capture history | `dateFirstCaptured`, `dateLastCaptured` |
| Capture detail | `captureResolution` in centimetres and `captureMethod` |
| Location | `localityPid`, `localityName`, `lgaPid`, `lgaName`, `meshBlockCode`, `sa1Code` |
| Building classification | `buildingUse`, `buildingUseSource`, `primaryBuildingFlag` |
| Footprint and floor area | `buildingArea`, `totalFloorArea`, both in square metres |
| Geometry detail | `numberVertices` |
| Ground elevation detail | `groundElevation`, `groundElevationResolution` |

`totalFloorArea` estimates floor area across building parts and levels. It is different from `buildingArea`, which measures the footprint. `buildingUse` can derive from planning or other source information, so it is not a direct replacement for a planning-zone record.

## Migrate legacy fields

The current response still supplies several compatibility fields when their source values are available. Prefer the named current fields:

| Legacy field | Use instead | Current response behaviour |
| --- | --- | --- |
| `area` | `buildingArea` | Same footprint area in square metres |
| `numberOfVertices` | `numberVertices` | Same geometry vertex count |
| `dateCaptured` | `dateLastCaptured` | Both are populated from the latest capture date. Use `dateFirstCaptured` for the first capture date |
| `dateBuildingReviewed` | `dateLastCaptured` | Same latest capture date |
| `buildingSource` | `captureResolution` and `captureMethod` | Legacy field combines the two values in lowercase |
| `groundElevationSource` | `groundElevationResolution` | Legacy field receives the elevation-model resolution |
| `qualityClass` | `captureResolution` and `captureMethod` | Use the current fields to assess capture detail. They are not aliases of the legacy classification |

Older documentation also listed `planningZone`, `volume`, `geometryQuality`, `estimatedLevels`, and top-level `treeOverhang`. The current API response model does not emit these fields. Use the relevant current attributes where available:

- `buildingUse` for building-use classification
- `height.buildingVolume` for volume in cubic metres
- `height.estimatedFloors` for estimated floor count
- `roof.treeOverhang` for the current tree-overhang flag

Check for fields before reading them. An optional field can be omitted rather than returned as `null`. Do not assume that a deprecation notice guarantees every historical field remains populated.

## Choose current additional-property models

| Legacy request | Preferred request | Migration notes |
| --- | --- | --- |
| `additionalProperties=heightsAndRoofs` | `additionalProperties=height,roof` | Separate models include their own record dates and state |
| `additionalProperties=solarIndicator` | `additionalProperties=solar` | Adds capture information, `solarFlag`, panel area, and estimated daily energy |
| `additionalProperties=poolIndicator` | Keep the existing value if needed | No `pool` replacement value is currently accepted |

The legacy values remain accepted. Availability and charges differ between current and legacy models, so see [Additional Properties](/guides/buildings/additional-properties) before changing requests.

## Understand relationship records

The current building-address, building-cadastre, and building-property endpoints return identifiers, record dates, and relationship confidence where available. Building-address records can also contain `addressDetailPid` and the address string.

The historical `isResidential` field is not returned. For a building-level primary flag, inspect `properties.primaryBuildingFlag` in a building feature.

Retrieve the full related feature from the Addresses or Land Parcels API using the returned identifier.

## Further reading

- [Buildings Technical Description](https://docs.geoscape.com.au/projects/buildings_guide/en/stable/#document-2_technical_description)
- [Buildings Product Guide](https://docs.geoscape.com.au/projects/buildings_guide/en/stable/#document-1_overview)
- [Legacy Attributes for v1](/guides/buildings/include#dataset-31-enhancements)

Contact [Geoscape support](mailto:support@geoscape.com.au) for dataset or migration questions.

## Next steps

- [Try the Buildings Quickstart](/guides/buildings/quickstart)
- [Choose additional properties](/guides/buildings/additional-properties)
- [Browse the current reference](/reference/buildings-v2-1-building)