Metadata (Descriptors)

This page describes the descriptor objects returned in the API response

What are Descriptors?

Each geometry feature (building, surface, barrier, or infrastructure instance) in the API response includes a descriptor object that contains metadata about that object. The descriptor provides detailed information that you can use to:

Identify and categorize features: Determine what type of building, surface, or infrastructure element you're working with
Apply appropriate styling: Use material types, colors, and other visual properties to render features correctly
Filter and query: Select specific feature types (e.g., only residential buildings, only roads, only trees) based on descriptor properties
Enhance visualization: Use roof types, facade materials, and other architectural details for realistic rendering
Handle special cases: Identify features that intersect boundaries, have specific data sources, or require special processing

All metadata is available in the descriptor property of each mesh (for buildings, surfaces, and barriers) or node (for infrastructure instances).

Descriptor Reference

Building Descriptors

Building descriptors are found in geometry[].meshes[].descriptor when type === "buildings".

Building Type Properties

Property

Type

Description

type

string

🏢 Building type identifier.

id

number | string?

🆔 Unique building identifier

buildingName

string?

🏷️ Building name from source data

buildingType

string | null?

🏘️ Building category from source data. Can be any string value from OSM building tags, or other data sources. Common values include "residential", "commercial", "industrial", "retail", "office", "school", "hospital", etc.

datasetName

string?

📊 Source dataset name (e.g., "OSM", "Governmental", "Microsoft ML Buildings")

heightSource

string?

📏 Source of height data (e.g., "LIDAR", "OSM", etc)

Building Dimensions

Property

Type

Description

buildingLevels

number?

Number of above-ground floors

buildingHeight

number?

Total height in meters

buildingMinHeight

number?

Height of base/bottom in meters

buildingRoofHeight

number?

Height of roof section in meters

originalHeight

number?

Original height from data source before calculations

Building Roof Properties

Property

Type

Description

Values

buildingRoofType

string?

Roof shape/style

'flat', 'hipped', 'gabled', 'gambrel', 'pyramidal', 'onion', 'dome', 'round', 'skillion', 'mansard', 'quadrupleSaltbox', 'saltbox'

buildingRoofOrientation

string?

Roof ridge orientation

'along' (ridge along building length), 'across' (ridge across building width)

buildingRoofDirection

number?

Direction/bearing of roof ridge in radians

0-2π

buildingRoofAngle

number?

Angle/slope of roof in radians

0-π/2

buildingRoofMaterial

string?

Roof material

'default', 'tiles', 'metal', 'concrete', 'thatch', 'eternit', 'grass', 'glass', 'tar'

buildingRoofColor

number?

Roof color (numeric color value)

RGB/hex encoded

Building Facade Properties

Property

Type

Description

Values

buildingFacadeMaterial

string?

Facade material

'plaster', 'brick', 'wood', 'glass', 'cementBlock'

buildingFacadeColor

number?

Facade color (numeric color value)

RGB/hex encoded

buildingWindows

boolean?

Whether building has windows

true/false

buildingFoundation

boolean?

Whether building has visible foundation

true/false

Building Additional Properties

Property

Type

Description

zIndex

number?

Rendering order (added by API)

Surface Descriptors

Surface descriptors are found in geometry[].meshes[].descriptor when type === "surface".

Surface Types

Type

Description

Additional Properties

'asphalt'

🛣️ Asphalt surface

'roadwayIntersection'

🚦 Road intersection

intersectionMaterial

'pavement'

🚶 Sidewalk/pedestrian pavement

'water'

💧 Water body

'farmland'

🌾 Agricultural land

'grass'

🌱 Grass area

'sand'

🏖️ Sand area

'rock'

🪨 Rock area

'pitch'

⚽ Sports field

pitchType

'manicuredGrass'

⛳ Manicured/well-maintained grass

'helipad'

🚁 Helicopter landing pad

'forest'

🌲 Forest area

treeType

'garden'

🌳 Garden area

'construction'

🏗️ Construction site

'shrubbery'

🌿 Shrubbery/bushes

'roadwayArea'

🛣️ Roadway surface area

'path'

🛣️ Path/road

pathType, pathMaterial, lanesForward, lanesBackward, isRoadwayMarked, side

'waterway'

💧 Waterway/canal

Surface Properties

Property

Type

Description

Used With

Values

type

string

Surface type (see table above)

All surfaces

See Surface Types table above

label

string?

Surface label/name

All surfaces

Any string

intersectionMaterial

string?

Surface material for intersections

'roadwayIntersection'

'asphalt', 'concrete', 'cobblestone'

pitchType

string?

Type of sports field

'pitch'

'generic', 'football', 'basketball', 'tennis'

treeType

string?

Tree species/type

'forest'

'genericBroadleaved', 'genericNeedleleaved', 'beech', 'fir', 'linden', 'oak'

pathType

string?

Type of path

'path'

'roadway', 'footway', 'cycleway', 'railway', 'tramway', 'runway'

pathMaterial

string?

Surface material for paths

'path'

'asphalt', 'concrete', 'dirt', 'sand', 'gravel', 'cobblestone', 'wood'

isRoadwayMarked

boolean?

Whether roadway has lane markings

'path' with pathType === 'roadway'

true, false

lanesForward

number?

Number of lanes in forward direction

'path' with pathType === 'roadway'

Positive number

lanesBackward

number?

Number of lanes in backward direction

'path' with pathType === 'roadway'

Positive number

side

string?

Which side of path the feature is on

'path'

'both', 'left', 'right'

width

number?

Width in meters

'path', 'waterway'

Positive number (meters)

height

number?

Height in meters

'waterway'

Positive number (meters)

minHeight

number?

Minimum/base height in meters

'path', 'waterway'

Number (meters)

zIndex

number?

Rendering order (added by API)

All surfaces

Number

intersectsBoundary

boolean?

Whether surface intersects polygon boundary

All surfaces

true, false

Barrier Descriptors

Barrier descriptors are found in geometry[].meshes[].descriptor when type === "barriers".

Note: Barriers (walls, fences) are linear features (polylines) that have been converted to meshes. Paths and waterways are included in the surface geometry type.

Barrier Types

Type

Description

Additional Properties

'fence'

🚧 Fence

fenceMaterial

'wall'

🧱 Wall

wallType

Wall Properties (when type === 'wall')

Property

Type

Description

Values

wallType

string?

Wall material type

'stone', 'concrete', 'hedge'

Fence Properties (when type === 'fence')

Property

Type

Description

Values

fenceMaterial

string?

Fence material

'wood', 'chainLink', 'metal', 'concrete'

Infrastructure Descriptors (Instances)

Infrastructure descriptors are found in geometry[].nodes[].descriptor when type === "instances".

Infrastructure features are point instances (nodes) that represent discrete objects at specific coordinates.

Infrastructure Types

Type

Description

Additional Properties

'tree'

🌲 Individual tree

treeType, height, minHeight

'rock'

🪨 Rock formation

height, minHeight

'hydrant'

🚒 Fire hydrant

height, minHeight

'transmissionTower'

⚡ Electrical transmission tower

height, minHeight

'utilityPole'

📡 Utility/power pole

height, minHeight

'artwork'

🎨 Art installation

height, minHeight, direction

'adColumn'

📢 Advertisement column

height, minHeight

'windTurbine'

💨 Wind turbine

height, minHeight

'bench'

🪑 Bench/seating

height, minHeight

'picnicTable'

🧺 Picnic table

height, minHeight

'busStop'

🚏 Bus stop

height, minHeight

'memorial'

🗿 Memorial monument

height, minHeight, direction

'statue'

🗽 Statue

height, minHeight, direction

'sculpture'

🎭 Sculpture

height, minHeight, direction

Infrastructure Properties

Property

Type

Description

Used With

Values

type

string?

Infrastructure type (see table above)

All instances

See Infrastructure Types table

treeType

string?

Tree species/type

'tree'

'genericBroadleaved', 'genericNeedleleaved', 'beech', 'fir', 'linden', 'oak'

height

number?

Height in meters

All instances

Positive number (meters)

minHeight

number?

Minimum/base height in meters

All instances

Number (meters)

direction

number?

Orientation/direction in radians

'memorial', 'statue', 'sculpture', 'artwork'

0-2π (radians)

Instance Node Structure

Each infrastructure instance in the nodes array has the following structure:

{
  "x": 123.45,
  "y": 67.89,
  "z": 10.0,
  "instanceType": "tree",
  "scale": 1.0,
  "rotation": 0.0,
  "descriptor": {
    "type": "tree",
    "treeType": "oak",
    "height": 15.0,
    "minHeight": 0.0
  }
}

Type Correlations Summary

Certain descriptor properties are only relevant for specific types:

treeType → Used with type: 'tree' (infrastructure) and type: 'forest' (surface)
wallType → Used with type: 'wall' (barriers)
fenceMaterial → Used with type: 'fence' (barriers)
pathType → Used with type: 'path' (surface)
pathMaterial → Used with type: 'path' (surface)
pitchType → Used with type: 'pitch' (surface)
intersectionMaterial → Used with type: 'roadwayIntersection' (surface)
building* fields → Used with type: 'building' or type: 'buildingPart' (buildings)

PreviousCoordinate Systems (CRS)NextBuildings

Last updated 6 days ago