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 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:
buildingUsefor building-use classificationheight.buildingVolumefor volume in cubic metresheight.estimatedFloorsfor estimated floor countroof.treeOverhangfor 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 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
Contact Geoscape support for dataset or migration questions.