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 for field definitions.
Set GEOSCAPE_API_KEY to your application's Consumer Key before running this example. See Authentication for setup.
Code
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, andsolarare 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 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.
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,solaruses 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, orsolarobject adds no charge for that object - Legacy objects, including empty ones, can still contribute a charge. Prefer the current models where available
- Returning
heightsAndRoofstogether withheightorroofcharges the combined height-and-roof amount once - Returning both
solarandsolarIndicatorcharges 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.