> For the complete documentation index, see [llms.txt](https://cityweft.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cityweft.gitbook.io/docs/basics/metadata-descriptors.md).
# Metadata (Descriptors)
### 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:
```json
{
"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)
***
###
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://cityweft.gitbook.io/docs/basics/metadata-descriptors.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.